Alexa.Commissionableインターフェース

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はローカルコミッションをトリガーするワークフローを開始します。

この図は、ユーザーがスキルを有効にしていない場合の検出ワークフローを表しています。画像をクリックすると拡大します。

Alexa.Commissionableインターフェースの検出ワークフロー

この図は、ユーザーが既にスキルを有効にしている場合のAddOrUpdateReportワークフローを表しています。画像をクリックすると拡大します。

Alexa.CommissionableインターフェースのAddorUpdateワークフロー

Matterプロトコル固有の要件

Matterデバイスの場合、Alexa.DiscoveryのDiscover.ResponseまたはAddOrUpdateReportイベントレポートに以下の設定を適用します。

  • Endpointオブジェクトでは、ローカルのMatter接続時に、スキルからレポートされるfriendlyNameをデバイスの基本情報クラスターのNodeLabelフィールドからも取得できます。ユーザーがアプリでフレンドリー名を変更した場合は、NodeLabelフィールドにも変更を反映する必要があります。
  • AdditionalAttributesオブジェクトでは、customIdentifierフィールドに、デバイスの基本情報クラスターの静的なUniqueIDフィールドの値を設定します。このフィールドを使って、スキルおよびローカルのAlexaデバイスからレポートされるデバイスの重複を排除します。
  • Connectionsプロパティでは、タイプをMATTER接続としてレポートします。MatterデバイスのmatterDiscriminatormacAddressmatterVendorIdmatterProductIdmacNetworkInterfaceの値をレポートすることをお勧めします。

検出

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応答イベントのペイロードの詳細を示しています。

プロパティ 説明 必須

CommissioningInformation

プロトコルオブジェクトの配列です。Alexaがデバイスとペアリングできるローカルプロトコルのリストが含まれます。プロトコルオブジェクトのCommissioningInformation.localProtocolCommissioningInformation.protocolDataには、そのプロトコルを使ってコミッションするのに必要な情報が含まれます。

オブジェクトの配列

CommissioningInformation.localProtocol

ローカルネットワーク上でこのデバイスとコミッションするプロトコルを示す文字列の列挙値です。有効な値はMATTERです。AlexaがMatterプロトコルを使ってデバイスと接続できることを表します。

文字列

CommissioningInformation.protocolData

CommissioningInformation.protocolData.manualPairingCodeCommissioningInformation.protocolData.commissioningWindowExpirationTimestampなど、プロトコル固有のコミッションデータを含むオブジェクトです。

オブジェクト

CommissioningInformation.protocolData.manualPairingCode

Matterデバイスは、現在の管理者がデバイスに無期限のコミッション期間に入るよう指示した場合に、このコードを生成します。

文字列

CommissioningInformation.protocolData.commissioningWindowExpirationTimestamp

Alexaがローカル接続を作成できなくなった後にスキルが提供する、コミッション期間を表すオプションのタイムスタンプです。このタイムスタンプにより、特定の時間までにAlexaの再試行を制限でき、Alexaがローカル接続できない理由がコミッション期限切れである場合には、トラブルシューティングもできます。タイムスタンプは、特定の日付と時刻を協定世界時で表します。ISO 8601形式形式のYYYY-MM-DDThh:mm:ssZに則ったRFC 3339プロファイルを使用する文字列です。

文字列

応答イベントの例

以下は、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_BUSYENDPOINT_UNREACHABLEBRIDGE_UNREACHABLEといったAlexaの標準エラータイプを使うこともできます。詳細については、ErrorResponseイベント/エラータイプの値を参照してください。

Matter Frustration-Free Setup(英語)

スマートホームスキルを理解する