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 日