Alexa.Commissionableインターフェース
AlexaスキルにAlexa.Commissionableインターフェースを実装すると、Matterなどのローカルプロトコルを使って、Alexaをユーザーのホームネットワーク上のエンドポイントにローカル接続できます。Alexaをエンドポイントにローカル接続することにより、別ルートでも制御ディレクティブを実行できるようになります。このルートを使うことで、エンドポイントをより高速に制御できるため、ネットワークがダウンしたり、スキルが利用できなくなったりした場合でも、より柔軟に対応できます。MatterデバイスとAmazonの統合について詳しくは、こちらのページを参照してください。
Alexa.Commissionableインターフェースがサポートするロケールについては、Alexaインターフェースとサポートしている言語の一覧を参照してください。
発話
Alexa.Commissionableはユーザーと対話するインターフェースではないため、音声を使ったユーザーとAlexaの直接の対話はサポートされません。
ワークフロー
Alexa.Commissionableは、ユーザーおよび開発者の既存ワークフローにシームレスに統合されます。通常どおり、ユーザーがまずデバイスをアプリに登録し、Amazonアカウントを使ってアプリをアカウントリンクすることにより、スマートホームスキルを有効にします。Alexaとのアカウントリンクの詳細については、アプリ間アカウントリンクの設定を参照してください。次のいずれかのアクティビティが発生すると、デバイスのAlexaへのコミッションが開始します。
- ユーザーがAlexaにデバイスを探すようリクエストした場合。Alexaはスキルに
Discoverディレクティブを送信し、スキルは、Alexa.Commissionable機能を持つDiscover.Responseイベントを、そのエンドポイントについて初めてレポートします。詳細については、検出を参照してください。 - スキルが
AddOrUpdateReportイベントを使って、Alexa.Commissionable機能を持つデバイスをプロアクティブにレポートする場合。詳細については、AddOrUpdateReportを参照してください。
Alexa.Commissionable機能を持つDiscover.ResponseイベントまたはAddOrUpdateReportイベントを受信すると、AlexaはReportCommissioningInformationディレクティブを送信してデバイスのコミッション情報をリクエストします。スキルがCommissioningInformationReportを送信すると、Alexaはローカルコミッションをトリガーするワークフローを開始します。
この図は、ユーザーがスキルを有効にしていない場合の検出ワークフローを表しています。画像をクリックすると拡大します。
この図は、ユーザーが既にスキルを有効にしている場合のAddOrUpdateReportワークフローを表しています。画像をクリックすると拡大します。
Matterプロトコル固有の要件
Matterデバイスの場合、Alexa.DiscoveryのDiscover.ResponseまたはAddOrUpdateReportイベントレポートに以下の設定を適用します。
Endpointオブジェクトでは、ローカルのMatter接続時に、スキルからレポートされるfriendlyNameをデバイスの基本情報クラスターのNodeLabelフィールドからも取得できます。ユーザーがアプリでフレンドリー名を変更した場合は、NodeLabelフィールドにも変更を反映する必要があります。AdditionalAttributesオブジェクトでは、customIdentifierフィールドに、デバイスの基本情報クラスターの静的なUniqueIDフィールドの値を設定します。このフィールドを使って、スキルおよびローカルのAlexaデバイスからレポートされるデバイスの重複を排除します。Connectionsプロパティでは、タイプをMATTER接続としてレポートします。MatterデバイスのmatterDiscriminator、macAddress、matterVendorId、matterProductId、macNetworkInterfaceの値をレポートすることをお勧めします。
macAddressをプロアクティブにレポートする必要があります。詳細については、イベントゲートウェイにイベントを送信するを参照してください。検出
Alexa.Commissionableをサポートするデバイスのエンドポイントは、Alexa.DiscoveryインターフェースおよびAlexa検出オブジェクト／connectionsプロパティで説明されている標準の検出メカニズムを使って記述します。検出応答レポートでAlexa.Commissionable機能を報告すると、Alexaは、ユーザーのアカウントで利用可能なデバイスがあること、そのデバイスをローカルでEchoデバイスとペアリングできることを認識します。
Matter固有の設定は、Matterプロトコル固有の要件に従って適用します。
検出応答の例
以下は、Alexa.CommissionableインターフェースとAlexa.EndpointHealthインターフェースをサポートするエンドポイントのDiscover.Responseメッセージの例です。
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "＜一意の識別子、バージョン4 UUIDが望ましい＞"
},
"payload": {
"endpoints": [{
"endpointId": "エンドポイントの一意のID",
"manufacturerName": "エンドポイントのメーカー名",
"description": "<Alexaアプリに表示される説明>",
"friendlyName": "新しいMatterデバイス",
"displayCategories": ["LIGHT"],
"additionalAttributes": {
"manufacturer": "<エンドポイントのメーカー名>",
"model": "<デバイスのモデル>",
"serialNumber": "デバイスのシリアル番号",
"firmwareVersion": "デバイスのファームウェアバージョン",
"softwareVersion": "デバイスのソフトウェアバージョン",
"customIdentifier": "デバイスのカスタム識別子"
},
"cookie": {},
"capabilities": [{
"type": "AlexaInterface",
"interface": "Alexa.Commissionable",
"version": "1.0"
},
{
"type": "AlexaInterface",
"interface": "Alexa.EndpointHealth",
"version": "3.2",
"properties": {
"supported": [{
"name": "connectivity"
}],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
],
"connections": [{
"type": "MATTER",
"macAddress": "00:11:22:AA:BB:33:44:55",
"macNetworkInterface": "THREAD",
"matterVendorId": "MatterVendorId",
"matterProductId": "MatterProductId",
"matterDiscriminator": "longDiscriminator"
} ],
"relationships": {}
}]
}
}
}
AddOrUpdateReport
たとえば、ファームウェアアップデートにより既存のエンドポイントをMatterに対応させるなど、既存のエンドポイントや新規のMatterエンドポイントをコミッションするには、Alexa.Discovery.AddOrUpdateReportイベントをプロアクティブに送信できます。詳細については、AddOrUpdateReportイベントを参照してください。
Matter固有の設定は、Matterプロトコル固有の要件に従って適用します。
AddOrUpdateReportイベントの例
以下は、新しいエンドポイントに対して、Echoデバイスがこのデバイスをコミッションできるよう指定するAddOrUpdateReportメッセージの例です。
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "AddOrUpdateReport",
"payloadVersion": "3",
"messageId": "一意の識別子、バージョン4 UUIDが望ましい"
},
"payload": {
"endpoints": [{
"endpointId": "新しいエンドポイントの一意ID",
"manufacturerName": "エンドポイントのメーカー名",
"description": "<Alexaアプリに表示される説明>",
"friendlyName": "新しいMatterデバイス",
"displayCategories": ["LIGHT"],
"additionalAttributes": {
"manufacturer": "<エンドポイントのメーカー名>",
"model": "<デバイスのモデル>",
"serialNumber": "デバイスのシリアル番号",
"firmwareVersion": "デバイスのファームウェアバージョン",
"softwareVersion": "デバイスのソフトウェアバージョン",
"customIdentifier": "デバイスのカスタム識別子"
},
"cookie": {},
"capabilities": [{
"type": "AlexaInterface",
"interface": "Alexa.Commissionable",
"version": "1.0"
},
{
"type": "AlexaInterface",
"interface": "Alexa.EndpointHealth",
"version": "3.2",
"properties": {
"supported": [{
"name": "connectivity"
}],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
],
"connections": [{
"type": "MATTER",
"macAddress": "00:11:22:AA:BB:33:44:55",
"macNetworkInterface": "THREAD",
"matterVendorId": "MatterVendorId",
"matterProductId": "MatterProductId",
"matterDiscriminator": "longDiscriminator"
} ],
"relationships": {}
}]
}
}
}
ディレクティブとイベント
ReportCommissioningInformationディレクティブ
Discover.ResponseまたはAddOrUpdateReportイベントにAlexa.Commissionable機能がある場合、AlexaはReportCommissioningInformationディレクティブをスキルに送信します。このディレクティブを使って、Alexaはデバイス制御クラウドに、ローカルコミッションを有効にするために必要なアクションを実行するようリクエストします。Matterプロトコルの場合、以下のアクションが発生します。このディレクティブを受信すると、デバイス制御クラウドはデバイスを一定期間コミッションモードに設定し、コミッションの認証情報を返します。また、デバイス制御クラウドは、デバイスがコミッションモードに設定される期間を表すコミッション有効期限のタイムスタンプも返します。
ReportCommissioningInformationディレクティブの例
次の例は、Alexaがスキルに送信するReportCommissioningInformationディレクティブを示しています。
{
"directive": {
"header": {
"namespace": "Alexa.Commissionable",
"name": "ReportCommissioningInformation",
"messageId": "メッセージID",
"correlationToken": "opaque相関トークン",
"payloadVersion": "1.0"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2ベアラートークン"
},
"endpointId": "エンドポイントID",
"cookie": {}
},
"payload": {}
}
}
ReportCommissioningInformationディレクティブの応答イベント
スキルが正常にReportCommissioningInformationディレクティブを処理し、デバイスをコミッションモードに設定すると、CommissioningInformationReportイベントで応答します。
CommissioningInformationReportイベントのペイロード
次の表は、CommissioningInformationReport応答イベントのペイロードの詳細を示しています。
| プロパティ | 説明 | 型 | 必須 |
|---|---|---|---|
|
|
プロトコルオブジェクトの配列です。Alexaがデバイスとペアリングできるローカルプロトコルのリストが含まれます。プロトコルオブジェクトの |
オブジェクトの配列 |
〇 |
|
|
ローカルネットワーク上でこのデバイスとコミッションするプロトコルを示す文字列の列挙値です。有効な値は |
文字列 |
◯ |
|
|
|
オブジェクト |
◯ |
|
|
Matterデバイスは、現在の管理者がデバイスに無期限のコミッション期間に入るよう指示した場合に、このコードを生成します。 |
文字列 |
◯ |
|
|
Alexaがローカル接続を作成できなくなった後にスキルが提供する、コミッション期間を表すオプションのタイムスタンプです。このタイムスタンプにより、特定の時間までにAlexaの再試行を制限でき、Alexaがローカル接続できない理由がコミッション期限切れである場合には、トラブルシューティングもできます。タイムスタンプは、特定の日付と時刻を協定世界時で表します。ISO 8601形式形式の |
文字列 |
✕ |
応答イベントの例
以下は、ReportCommissioningInformationディレクティブを送信する、成功時の応答イベントの例です。
{
"event": {
"header": {
"namespace": "Alexa.Commissionable",
"name": "CommissioningInformationReport",
"messageId": "＜一意の識別子、バージョン4 UUIDが望ましい＞",
"correlationToken": "opaque相関トークン",
"payloadVersion": "1.0"
},
"endpoint": {
"endpointId": "エンドポイントID"
},
"payload": {
"commissioningInformation": [{
"localProtocol": "MATTER",
"protocolData": {
"manualPairingCode": "ManualPairingCode",
"commissioningWindowExpirationTimestamp": "2021-02-03T16:20:50Z"
}
}
]
}
}
}
ReportCommissioningInformationディレクティブのエラー処理
スキルが正常にReportCommissioningInformationディレクティブを処理できない場合、ReportCommissioningInformation.ErrorResponseイベントで応答します。
ReportCommissioningInformationのエラータイプに加え、ENDPOINT_BUSY、ENDPOINT_UNREACHABLE、BRIDGE_UNREACHABLEといったAlexaの標準エラータイプを使うこともできます。詳細については、ErrorResponseイベント／エラータイプの値を参照してください。
関連トピック
最終更新日: 2022 年 04 月 28 日