$id (必須）$ref 名前 (必須）title description version extrinsicVersion (必須）extrinsicId (必須）$defs extrinsicProperties プロパティアクションイベント

機能定義のスキーマ

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

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

properties
actions
events

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

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

$id (必須）

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

URI /schema-versions/ プレフィックスで始める
capability スキーマタイプを含める
URI パス区切り文字としてスラッシュ (/) を使用する
フラグメントをピリオドで区切ってスキーマ ID を含める (.）
@ 文字を使用してスキーマ ID とバージョンを区切る
ピリオド (.) を使用してバージョンフラグメントを分離し、セムバーバージョンで終わる

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

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

注記

予約された名前空間awsや matter

例 $id


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

$ref

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

注記

タイプ定義または機能は、 $ref ファイルで指定された値で存在する必要があります。

例 $ref の例


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

名前 (必須）

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

英数字、ピリオド (.)、スラッシュ (/)、ハイフン (-)、スペースのみを含む
文字で始める
最大 64 文字

名前要素は、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 要素はオプションです。これは、スキーマドキュメントのバージョンを表す文字列です。以下の制約があります。

セムバー形式を使用し、次のバージョンフラグメントを . (ピリオド) で区切ります。
- MAJOR バージョン、最大 3 桁
- MINOR バージョン、最大 3 桁
- PATCH バージョン (オプション）、最大 4 桁
長さは 3～12 文字です。

例バージョン例

1.0


1.12


1.4.1

機能バージョンの使用

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

下位互換性のない API 変更を行う場合のメジャーバージョンの増加
下位互換性のある方法で機能を追加するとマイナーバージョンが増加する
機能に影響のない軽微な追加を行うと、パッチバージョンが増加します。

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 桁の数字です。

例バージョン例

extrinsicId (必須）

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

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

注記

AWSベンダー ID (VID) は 0x1577 で、Matter の場合は 0 です。システムは、カスタムスキーマがこれらの予約済み VIDs を機能に使用しないようにします。

例 extrinsicIds の例


0018
0x001A
0x15771002

$defs

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

注記

システムは、有効なマップ$defsであり、各サブスキーマが有効な JSON スキーマであるのみを適用します。追加のルールは適用されません。

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

定義名には URI フレンドリ文字のみを使用する
各値が有効なサブスキーマであることを確認します。
スキーマドキュメントのサイズ制限内に収まる任意の数のサブスキーマを含める

extrinsicProperties

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

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

プロパティ名はスペースや特殊文字を含まない英数字にする必要があります
プロパティ値は任意の JSON スキーマ値にすることができます
最大 20 個のプロパティ

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

注記

外部プロパティは、機能の action、event、property、および structフィールド要素でサポートされていますが、機能やクラスター自体ではサポートされていません。

プロパティ

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

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

プロパティ名には英数字のみを使用し、スペースや特殊文字は使用しない
スキーマドキュメントのサイズ制限内に収まる任意の数のプロパティを含める

プロパティの使用

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

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

値

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

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

シンプルな型の場合は、 type と、 maxLengthやなどのその他のネイティブ JSON スキーマ制約を使用します。 maximum
複合型の場合は、oneOf、allOf、またはを使用しますanyOf。システムは notキーワードをサポートしていません
任意のグローバルタイプを参照するには、有効な検出可能なリファレンス$refでを使用します。
null 可能性については、nullable 属性にブールフラグを指定して OpenAPI タイプのスキーマ定義に従います (truenull が許容値である場合）。

例:


{
    "$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 文字です。

レスポンス名

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

レスポンスの従来の名前は、アクション名Responseにを追加することによって算出されます。
別の名前を使用する場合は、このname要素で指定できます。レスポンスで nameが指定されている場合、この値は従来の名前よりも優先されます。

エラー

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

制約:

メッセージ項目は、次のフィールドを持つ JSON オブジェクトとして宣言されます。
- code: 英数字と _ (アンダースコア) を含み、長さが 1～64 文字の文字列
- message: 無制限の文字列値

例エラーメッセージの例


"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、以下を参照してください。

リクエストまたはレスポンスで extrinsicIdが指定されている場合、この値はアクションレベルで提供される値よりも優先されます。システムがextrinsicId最初にリクエスト/レスポンスレベルを使用する必要があります。見つからない場合はアクションレベルを使用してください。 extrinsicId
リクエストまたはレスポンスで extrinsicPropertiesが指定されている場合、これらのプロパティはアクションレベルで提供される va 値よりも優先されます。システムはアクションレベルを取得しextrinsicProperties、リクエスト/レスポンスレベルで提供されるキーと値のペアを置き換える必要があります extrinsicProperties

例 extrinsicId および 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: 状態プロパティの値を読み取るmanagedThingコマンドをに送信します。デバイスの状態を強制的に更新する方法ReadStateとしてを使用します。
UpdateState: 一部のプロパティを更新するコマンドを送信します。

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

デバイスは一定期間オフラインであり、イベントを出力していませんでした。
デバイスはプロビジョニングされたばかりで、クラウドにまだ状態が維持されていません。
デバイスの状態がデバイスの実際の状態と同期していません。

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
              }
            }
          ]
        }
      ]
    }
  ]
}

イベント

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

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

イベント配列に一意のイベントのみを含める
スキーマドキュメントのサイズ制限内に収まる任意の数のイベントを含める

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

データモデルスキーマ

タイプ定義のスキーマ

機能定義のスキーマ

$id (必須）

注記

例 $id

$ref

注記

例 $ref の例

名前 (必須）

例 名前の例

title

例 タイトルの例

description

例 説明の例

version

例 バージョン例

機能バージョンの使用

extrinsicVersion (必須）

例 バージョン例

extrinsicId (必須）

注記

例 extrinsicIds の例

$defs

注記

extrinsicProperties

注記

プロパティ

プロパティの使用

値

取得可能

Mutable

報告対象

アクション

アクションの使用

説明

リクエスト

リクエストの説明

レスポンス

レスポンスの説明

レスポンス名

エラー

例 エラーメッセージの例

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

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

パラメータフィールド

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

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

組み込みアクション

ReadState の例

UpdateState の例

イベント

例名前の例

例タイトルの例

例説明の例

例バージョン例

例バージョン例

例エラーメッセージの例

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