翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # 機能定義のスキーマ 機能は、システム内で機能する方法について明確な契約を提供する宣言型の JSON ドキュメントを使用して文書化されます。 機能の場合、必須要素は `$id`、、`extrinsicId`、`extrinsicVersion`および以下のセクションの少なくとも 1 `name`つの要素です。 + `properties` + `actions` + `events` 機能のオプションの要素は、`$ref`、`title`、、`description``version`、`$defs`および です`extrinsicProperties`。機能については、`$ref`「」を参照してください`aws.capability`。 以下のセクションでは、機能定義に使用されるスキーマについて詳しく説明します。 ## $id (必須) $id 要素はスキーマ定義を識別します。次の構造に従う必要があります。 + URI `/schema-versions/` プレフィックスで開始する + `capability` スキーマタイプを含める + URI パス区切り文字としてスラッシュ (`/`) を使用する + フラグメントをピリオドで区切ってスキーマ ID を含める (`.`) + `@` 文字を使用してスキーマ ID とバージョンを区切る + セムバーバージョンで終わり、ピリオド (`.`) を使用してバージョンフラグメントを区切る スキーマ ID は、3～12 文字のルート名前空間で始まり、その後にオプションのサブ名前空間と名前が続く必要があります。 セムバーバージョンには、メジャーバージョン (最大 3 桁）、マイナーバージョン (最大 3 桁）、オプションの PATCH バージョン (最大 4 桁) が含まれます。 **注記** 予約された名前空間`aws`や `matter` **Example $id の例** ``` /schema-version/capability/aws.Recording@1.0 ``` ## $ref `$ref` 要素は、システム内の既存の機能を参照します。これは、 `$id`要素と同じ制約に従います。 **注記** タイプ定義または機能は、 `$ref` ファイルで指定された値で存在する必要があります。 **Example $ref の例** ``` /schema-version/definition/aws.capability@1.0 ``` ## 名前 (必須) name 要素は、スキーマドキュメント内のエンティティ名を表す文字列です。多くの場合、略語が含まれているため、次のルールに従う必要があります。 + 英数字、ピリオド (.)、スラッシュ (/)、ハイフン (-)、スペースのみを含む + 文字で始める + 最大 64 文字 名前要素は、Amazon Web Services コンソールの UI とドキュメントで使用されます。 **Example 名前の例** ``` Door Lock On/Off Wi-Fi Network Management PM2.5 Concentration Measurement RTCSessionController Energy EVSE ``` ## title title 要素は、スキーマドキュメントで表されるエンティティの記述文字列です。任意の文字を含めることができ、ドキュメントで使用されます。機能タイトルの最大長は 256 文字です。 **Example タイトルの例** ``` Real-time Communication (RTC) Session Controller Energy EVSE Capability ``` ## 説明 `description` 要素は、スキーマドキュメントで表されるエンティティの詳細な説明を提供します。任意の文字を含めることができ、ドキュメントで使用されます。機能の説明の最大長は 2048 文字です **Example 説明の例** ``` 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` 要素はオプションです。これは、スキーマドキュメントのバージョンを表す文字列です。以下の制約があります。 + セムバー形式を使用し、次のバージョンフラグメントを `.` (ピリオド) で区切ります。 + `MAJOR` バージョン、最大 3 桁 + `MINOR` バージョン、最大 3 桁 + `PATCH` バージョン (オプション）、最大 4 桁 + 長さは 3～12 文字です。 **Example バージョン例** ``` 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 桁の数字です。 **Example バージョン例** ``` 7 ``` ``` 1567 ``` ## extrinsicId (必須) `extrinsicId` 要素は、Amazon Web Services IoT システムの外部で管理される識別子を表します。Matter 機能の場合、コンテキストに応じて `clusterId`、`fieldId`、、`attributeId``commandId``eventId`、または にマッピングされます。 は、文字列化された 10 進数整数 (1～10 桁) または文字列化された 16 進数整数 (0x または 0X プレフィックス、その後に 1～8 桁の 16 進数) `extrinsicId`のいずれかになります。 **注記** AWSベンダー ID (VID) は 0x1577 で、Matter の場合は 0 です。システムは、カスタムスキーマがこれらの予約済み VIDs機能に使用しないようにします。 **Example 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 タイプのスキーマ定義に従います (`true`null が許容値である場合）。 例: ``` { "$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](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_SendManagedThingCommand.html) API を介して送信されたアクションリクエストについて、リクエストはデバイスに到達し、非同期レスポンスが返されることを期待します。アクションレスポンスは、このレスポンスの構造を定義します。 アクションリクエストの場合、必須要素は です`parameters`。オプションの要素は、`name`、`description`、`extrinsicId`、`extrinsicProperties`、`errors`および です`responseCode`。 #### レスポンスの説明 説明は と同じ形式に従い[説明](#capability-schema-description)、最大長は 2048 文字です。 #### レスポンス名 名前は と同じ形式に従います。詳細については[名前 (必須)](#capability-schema-name)、以下を参照してください。 + レスポンスの従来の名前は、アクション名`Response`に を追加して算出されます。 + 別の名前を使用する場合は、この`name`要素で指定できます。レスポンスで `name`が指定されている場合、この値は従来の名前よりも優先されます。 #### エラー リクエストの処理中にエラーが発生した場合にレスポンスで提供される一意のメッセージの無制限の配列。 制約: + メッセージ項目は、次のフィールドを持つ JSON オブジェクトとして宣言されます。 + `code`: 英数字と `_` (アンダースコア) を含み、長さが 1～64 文字の文字列 + `message`: 無制限の文字列値 **Example エラーメッセージの例** ``` "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 要素は と同じ形式に従い[説明](#capability-schema-description)、最大長は 1024 文字です。 ### `extrinsicId` および `extrinsicProperties`オーバーライド `extrinsicId` および は、 [extrinsicId (必須)](#capability-schema-extrinsicId)および と同じ形式`extrinsicProperties`に従います。詳細については[extrinsicProperties](#capability-schema-extrinsicProperties)、以下を参照してください。 + リクエストまたはレスポンスで `extrinsicId`が指定されている場合、この値はアクションレベルで提供される値よりも優先されます。システムが`extrinsicId`最初にリクエスト/レスポンスレベルを使用する必要があります。見つからない場合はアクションレベルを使用してください。 `extrinsicId` + リクエストまたはレスポンスで `extrinsicProperties`が指定されている場合、これらのプロパティはアクションレベルで提供される va 値よりも優先されます。システムはアクションレベルを取得し`extrinsicProperties`、リクエスト/レスポンスレベルで提供されるキーと値のペアを置き換える必要があります `extrinsicProperties` **Example 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 一部のプロパティを更新するコマンドを送信します。 デバイス状態の同期を強制することは、以下のシナリオで役立ちます。 1. デバイスは一定期間オフラインであり、イベントを出力しませんでした。 1. デバイスはプロビジョニングされたばかりで、クラウドにまだ状態が維持されていません。 1. デバイスの状態がデバイスの実際の状態と同期していません。 #### ReadState の例 [SendManagedThingCommand](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_SendManagedThingCommand.html) 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](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_SendManagedThingCommand.html) API を使用して`OnTime`照明の を変更します。 ``` { "Endpoints": [ { "endpointId": "1", "capabilities": [ { "id": "matter.OnOff", "name": "On/Off", "version": "1", "actions": [ { "name": "UpdateState", "parameters": { "OnTime": 5 } } ] } ] } ] } ``` ## イベント イベントは、デバイスによって実装されるスキーマ管理の単方向シグナルです。 以下の制約に従ってイベントを実装します。 + イベント配列に一意のイベントのみを含める + スキーマドキュメントのサイズ制限内に収まる任意の数のイベントを含める