機能定義のスキーマ

機能は、システム内で機能する方法について明確な契約を提供する宣言型 JSON ドキュメントを使用して文書化されます。

機能の場合、必須要素は $id、、extrinsicId、extrinsicVersionおよび以下のセクションの少なくとも 1 nameつの要素です。

機能のオプションの要素は、$ref、title、、descriptionversion、$defsおよび ですextrinsicProperties。機能については、$ref「」を参照してくださいaws.capability。

以下のセクションでは、機能定義に使用されるスキーマについて詳しく説明します。

$id (必須）

$id 要素はスキーマ定義を識別します。次の構造に従う必要があります。

スキーマ ID は、3～12 文字のルート名前空間で始まり、その後にオプションのサブ名前空間と名前が続く必要があります。

セムバーバージョンには、メジャーバージョン (最大 3 桁）、マイナーバージョン (最大 3 桁）、オプションの PATCH バージョン (最大 4 桁) が含まれます。

/schema-version/capability/aws.Recording@1.0

$ref

$ref 要素は、システム内の既存の機能を参照します。これは、 $id要素と同じ制約に従います。

/schema-version/definition/aws.capability@1.0

名前 (必須）

name 要素は、スキーマドキュメント内のエンティティ名を表す文字列です。多くの場合、略語が含まれているため、次のルールに従う必要があります。

名前要素は、Amazon Web Services コンソールの UI とドキュメントで使用されます。

Door Lock
On/Off
Wi-Fi Network Management
PM2.5 Concentration Measurement
RTCSessionController
Energy EVSE

title

title 要素は、スキーマドキュメントで表されるエンティティの記述文字列です。任意の文字を含めることができ、ドキュメントで使用されます。機能タイトルの最大長は 256 文字です。

Real-time Communication (RTC) Session Controller
Energy EVSE Capability

description

description 要素は、スキーマドキュメントで表されるエンティティの詳細な説明を提供します。任意の文字を含めることができ、ドキュメントで使用されます。機能の説明の最大長は 2048 文字です

Electric Vehicle Supply Equipment (EVSE) is equipment used to charge an Electric Vehicle (EV) or Plug-In Hybrid Electric Vehicle. 
            This capability provides an interface to the functionality of Electric Vehicle Supply Equipment (EVSE) management.

version

version 要素はオプションです。これは、スキーマドキュメントのバージョンを表す文字列です。以下の制約があります。

1.0

1.12

1.4.1

機能バージョンの使用

機能は、イミュータブルなバージョニングされたエンティティです。すべての変更は、新しいバージョンを作成することが期待されます。システムは、MAJOR.MINOR.PATCH 形式のセマンティックバージョニングを使用します。ここで、

Matter クラスターから派生した機能はバージョン 1.4 からベースライン化され、各 Matter リリースはシステムにインポートされる予定です。Matter バージョンはセムバーのメジャーレベルとマイナーレベルの両方を消費するため、マネージド統合では PATCH バージョンのみを使用できます。

Matter に PATCH バージョンを追加するときは、 Matter がシーケンシャルリビジョンを使用することに注意してください。すべての PATCH バージョンは Matter 仕様に記載されているリビジョンに準拠し、下位互換性がある必要があります。

下位互換性のない問題を修正するには、Connection Standards Alliance (CSA) と協力して仕様の問題を解決し、新しいリビジョンをリリースする必要があります。

AWSマネージド機能は、 の初期バージョンでリリースされました1.0。これらを使用すると、3 つのレベルのバージョンをすべて使用できます。

extrinsicVersion (必須）

これは、 AWS IoT システムの外部で管理されるバージョンを表す文字列です。Matter 機能の場合、 は にextrinsicVersionマッピングされます。 revision

これは文字列化された整数値として表され、長さは 1～10 桁の数字です。

7

1567

extrinsicId (必須）

extrinsicId 要素は、Amazon Web Services IoT システムの外部で管理される識別子を表します。Matter 機能の場合、コンテキストに応じて 、fieldId、、clusterIdattributeIdcommandIdeventId、または にマッピングされます。

は、文字列化された 10 進数整数 (1～10 桁) または文字列化された 16 進数整数 (0x または 0X プレフィックス、1～8 桁の 16 進数) のいずれかextrinsicIdです。

0018
0x001A
0x15771002

$defs

$defs セクションは、JSON スキーマで許可されているスキーマドキュメント内で参照できるサブスキーマのマップです。このマップでは、 キーはローカル参照定義で使用され、 値は JSON スキーマを提供します。

定義を使用する場合は、以下の制約事項に従ってください。

extrinsicProperties

extrinsicProperties 要素には、外部システムで定義されているが、データモデル内で維持されている一連のプロパティが含まれています。Matter 機能の場合、ZCL クラスター、属性、コマンド、またはイベント内のさまざまなモデル化されていない要素または部分的にモデル化された要素にマッピングされます。

外部プロパティは、次の制約に従う必要があります。

システムは、extrinsicProperties、、、 などcliFunctionName、さまざまな access apiMaturity cliをサポートしています。これらのプロパティにより、データモデル変換への AWS （またはその逆の) ACL が容易になります。

プロパティ

プロパティは、 機能のデバイス管理の状態を表します。各状態はキーと値のペアとして定義され、キーは状態の名前を記述し、値は状態の定義を記述します。

プロパティを使用する場合は、次の制約事項に従ってください。

プロパティの使用

機能内のプロパティは、マネージド統合を使用するデバイスの特定の状態を表す基本的な要素です。デバイスの現在の状態または設定を表します。これらのプロパティの定義と構造を標準化することで、スマートホームシステムはさまざまなメーカーのデバイスが効果的に通信できるようにし、シームレスで相互運用可能なエクスペリエンスを実現します。

機能プロパティの場合、必須要素は extrinsicIdと ですvalue。機能プロパティのオプション要素は、description、retrievable、mutable、reportableおよび ですextrinsicProperties。

値

ビルダーが JSON スキーマ準拠の制約を適用して、このプロパティのデータ型を定義できるようにする無制限の構造。

値を定義するときは、次の制約に従います。

例:

{
    "$ref": "/schema-versions/definition/matter.uint16@1.4",
    "nullable": true,
    "maximum": 4096
}

取得可能

状態が読み取り可能かどうかを説明するブール値。

状態の可読性の側面は、デバイスの 機能の実装に委ねられます。デバイスは、特定の状態が読み取り可能かどうかを決定します。状態のこの側面は、機能レポートではまだ報告されないため、システム内で強制されません。

例: true または false

Mutable

状態が書き込み可能かどうかを説明するブール値。

状態の書き込み可能性の側面は、デバイスの 機能の実装に委ねられます。デバイスは、特定の状態が書き込み可能かどうかを決定します。状態のこの側面は、機能レポートではまだ報告されないため、システム内で強制されません。

例: true または false

報告対象

状態に変化があったときに 状態がデバイスによって報告されるかどうかを説明するブール値。

状態のレポート可能性の側面は、デバイスの 機能の実装に委ねられます。デバイスは、特定の状態が報告可能かどうかを決定します。状態のこの側面は、機能レポートではまだ報告されないため、システム内で強制されません。

例: true または false

アクション

アクションは、リクエスト/レスポンスモデルに従うスキーマ管理オペレーションです。各アクションは、デバイス実装オペレーションを表します。

アクションを実装するときは、次の制約に従ってください。

アクションの使用

アクションは、マネージド統合システムでデバイス機能とやり取りして制御するための標準化された方法です。これは、デバイスで実行できる特定のコマンドまたはオペレーションを表し、必要なリクエストまたはレスポンスパラメータをモデル化するための構造化された形式で補完されます。これらのアクションは、ユーザーの意図とデバイスオペレーションの橋渡しとして機能し、さまざまなタイプのスマートデバイス間で一貫した信頼性の高い制御を可能にします。

アクションの場合、必須要素は nameと ですextrinsicId。オプションの要素は、description、extrinsicProperties、requestおよび ですresponse。

説明

説明の最大長は 1536 文字です。

リクエスト

リクエストセクションはオプションであり、リクエストパラメータがない場合は省略できます。省略すると、システムは の名前を使用するだけでペイロードなしでリクエストを送信できますAction。これは、照明のオン/オフなどの簡単なアクションで使用されます。

複雑なアクションには、追加のパラメータが必要です。たとえば、カメラの映像をストリーミングするリクエストには、使用するストリーミングプロトコルに関するパラメータや、ストリームを特定のディスプレイデバイスに送信するかどうかに関するパラメータが含まれる場合があります。

アクションリクエストの場合、必須要素は ですparameters。オプションの要素は、description、extrinsicId、および ですextrinsicProperties。

リクエストの説明

説明はセクション 3.5 と同じ形式で、最大長は 2048 文字です。

レスポンス

マネージド統合では、SendManagedThingCommand API を介して送信されたアクションリクエストについて、リクエストはデバイスに到達し、非同期レスポンスが返されることを期待します。アクションレスポンスは、このレスポンスの構造を定義します。

アクションリクエストの場合、必須要素は ですparameters。オプションの要素は、name、description、extrinsicId、extrinsicProperties、errorsおよび ですresponseCode。

レスポンスの説明

説明は と同じ形式に従いdescription、最大長は 2048 文字です。

レスポンス名

名前は と同じ形式に従います。詳細については名前 (必須）、以下を参照してください。

エラー

リクエストの処理中にエラーが発生した場合にレスポンスで提供される一意のメッセージの無制限の配列。

制約:

"errors": [
   {  
      "code": "AD_001", 
      "message": "Unable to receive signal from the sensor. Please check connection with the sensor." 
   }
]

Response Code (レスポンスコード)

リクエストの処理方法を示す整数コード。デバイスコードは、HTTP サーバーのレスポンスステータスコード仕様を使用してコードを返し、システム内での統一を可能にすることをお勧めします。

制約: 100～599 の範囲の整数値。

リクエストまたはレスポンスパラメータ

パラメータセクションは、名前とサブスキーマのペアのマップとして定義されます。スキーマドキュメントに収まる場合、任意の数のパラメータをリクエストパラメータ内で定義できます。

パラメータ名に使用できるのは英数字のみです。スペースやその他の文字は使用できません。

パラメータフィールド

の必須要素は extrinsicIdと parameterですvalue。オプションの要素は descriptionおよび ですextrinsicProperties。

description 要素は と同じ形式に従いdescription、最大長は 1024 文字です。

extrinsicId および extrinsicPropertiesオーバーライド

extrinsicId および は、 extrinsicId (必須）および と同じ形式extrinsicPropertiesに従います。詳細についてはextrinsicProperties、以下を参照してください。

{
   "name": "ToggleWithEffect",
   "extrinsicId": "0x0001",
  
   "extrinsicProperties": {
      "apiMaturity": "provisional",
      "introducedIn": "1.2"
   },
   "request": {
      "extrinsicProperties": {
         "apiMaturity": "stable",
         "manufacturerCode": "XYZ"
      },
      "parameters": {
         ...
      }
   },
   "response": {
      "extrinsicProperties": {
         "noDefaultImplementation": true
      },
      "parameters": {
 {
         ...
      }
   }
}

上記の例では、アクションリクエストの有効な値は次のようになります。

# effective request
"name": "ToggleWithEffect",
"extrinsicId": "0x0001",
"extrinsicProperties": {
   "apiMaturity": "stable",
   "introducedIn": "1.2"
   "manufacturerCode": "XYZ"
},
"parameters": {
   ...
}

# effective response
"name": "ToggleWithEffectResponse",
"extrinsicId": "0x0001",
"extrinsicProperties": {
   "apiMaturity": "provisional",
   "introducedIn": "1.2"
   "noDefaultImplementation": true
},
"parameters": {
   ...
}

組み込みアクション

すべての機能で、キーワード ReadStateと を使用してカスタムアクションを実行できますUpdateState。これら 2 つのアクションキーワードは、データモデルで定義された機能のプロパティに作用します。

デバイス状態の同期を強制することは、以下のシナリオで役立ちます。

ReadState の例

SendManagedThingCommand API を使用して、ライトがオンまたはオフになっているかどうかを確認します。

{
  "Endpoints": [
    {
      "endpointId": "1",
      "capabilities": [
        {
          "id": "aws.OnOff",
          "name": "On/Off",
          "version": "1",
          "actions": [
            {
              "name": "ReadState",
              "parameters": {
                "propertiesToRead": [ "OnOff" ]
              }
            }
          ]
        }
      ]
    }
  ]
}

matter.OnOff 機能のすべての状態プロパティを読み取ります。

{
  "Endpoints": [
    {
      "endpointId": "1",
      "capabilities": [
        {
          "id": "aws.OnOff",
          "name": "On/Off",
          "version": "1",
          "actions": [
            {
              "name": "ReadState",
              "parameters": {
                "propertiesToRead": [ "*" ] 
                // Use the wildcard operator to read ALL state properties for a capability
              }
            }
          ]
        }
      ]
    }
  ]
}

UpdateState の例

SendManagedThingCommand API を使用してOnTime照明の を変更します。

{
  "Endpoints": [
    {
      "endpointId": "1",
      "capabilities": [
        {
          "id": "matter.OnOff",
          "name": "On/Off",
          "version": "1",
          "actions": [
            {
              "name": "UpdateState",
              "parameters": {
                "OnTime": 5
              }
            }
          ]
        }
      ]
    }
  ]
}

イベント

イベントは、デバイスによって実装されるスキーマ管理の単方向シグナルです。

以下の制約に従ってイベントを実装します。