Alexa.Commissionableインターフェース1.0

Alexa.Commissionableインターフェース1.0

AlexaスキルにAlexa.Commissionableインターフェースを実装すると、Matterなどのローカルプロトコルを使って、Alexaをユーザーのホームネットワーク上のエンドポイントにローカル接続できます。Alexaをエンドポイントにローカル接続することにより、別ルートでも制御ディレクティブを実行できるようになります。このルートを使うことで、エンドポイントをより高速に制御できるため、ネットワークがダウンしたり、スキルが利用できなくなったりした場合でも、より柔軟に対応できます。MatterデバイスとAmazonの統合について詳しくは、こちらのページを参照してください。

Alexa.Commissionableインターフェースがサポートするロケールについては、Alexaインターフェースとサポートしている言語の一覧を参照してください。メッセージプロパティの定義については、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ワークフロー

Alexa検出を行うMatterの要件

スキルがMatter対応デバイスをAlexaに接続する場合、これらのデバイスは複数のルートでAlexaに接続する可能性があります。たとえば、ユーザーは、複数のAlexaスマートホームスキルをAlexaアカウントにリンクして同じデバイスを制御する可能性があり、そのアカウントには同じデバイスへのローカルMatter接続がある可能性があります。Alexaが、これらのスキルのレポートしたエンドポイントおよびMatterのレポートしたエンドポイントを3つのデバイスではなく、1つのデバイスとしてユーザーに表示できるように、スキルはデバイスの識別情報を提供する必要があります。ここでの、Matterのレポートしたエンドポイントは、Matterファブリックに直接接続されるネイティブのMatterデバイス、Matter Bridge経由のブリッジデバイスとして公開される非Matterデバイスのいずれでもかまいません。

スキルがMatter対応デバイスとAlexaを接続する場合、直接接続であってもMatter Bridge経由であっても、スキルからのDiscover.ResponseイベントとAddOrUpdateReportイベントで次のMatterアトリビュートをAlexaにレポートする必要があります。

  • endpoint.additionalAttributes.customIdentifierプロパティに、ネイティブMatterデバイスのBasic ClusterまたはMatter BridgedデバイスのBridged Basic ClusterのUniqueIDアトリビュートの値を設定します。
  • endpoint.connections配列の接続タイプにMATTERを設定し、MatterデバイスのVendorIDアトリビュートとProductIDアトリビュートを含めます。わかっている場合は、Discriminatorアトリビュートを含めます。
    また、Amazonでは、macAddressとmacNetworkInterfaceをレポートすることを推奨しています（わかっている場合）。
  • endpoint.friendlyNameプロパティにアトリビュートを設定する場合、スキルがレポートする名前がネイティブMatterデバイスのBasic ClusterまたはMatter BridgedデバイスのBridged Basic ClusterのNodeLabelアトリビュートと一致することを確認してください。ユーザーがアプリでフレンドリー名を変更した場合、NodeLabelフィールドが設定されていれば、このフィールドも更新して変更を反映するようにしてください。NodeLabelを更新したら、AddOrUpdateReportイベントで更新後のendpoint.friendlyNameをプロアクティブにAlexaイベントゲートウェイに送信します。

Matterアトリビュートの例

以下は、Matter Basic Information Clusterからの値に基づいて検出プロパティをを設定する方法の例です。

クリップボードにコピーされました。

endpoint.friendlyName = matter_device.basicInformationCluster.nodeLabel
additional_attributes.customIdentifier = matter_device.basicInformationCluster.uniqueId

network_interfaces_map = { "WIFI": 1, "THREAD": 2, "ETHERNET": 4 }

if (matter_device.networkCommissioningCluster.featureFlag & network_interfaces_map.WIFI) {
    mac_network_interface = "WIFI"
}
else if (matter_device.networkCommissioningCluster.featureFlag & network_interfaces_map.THREAD) {
    mac_network_interface = "THREAD"
}
else if (matter_device.networkCommissioningCluster.featureFlag & network_interfaces_map.ETHERNET) {
    mac_network_interface = "ETHERNET"
}

connections = [{
   "type": "MATTER",
    "macAddress": matter_device.get_mac_address(),
    "macNetworkInterface": mac_network_interface,
    "matterVendorId": matter_device.basicInformationCluster.vendorId,
    "matterProductId": matter_device.basicInformationCluster.productId,
    "matterDiscriminator": matter_device.get_discriminator()
}]

クリップボードにコピーされました。

endpoint.friendlyName = matter_device.basicInformationCluster.nodeLabel
additional_attributes.customIdentifier = matter_device.basicInformationCluster.uniqueId

network_interfaces_map = { "WIFI": 1, "THREAD": 2, "ETHERNET": 4 }

if matter_device.networkCommissioningCluster.featureFlag & network_interfaces_map["WIFI"]:
    mac_network_interface = "WIFI"
elif matter_device.networkCommissioningCluster.featureFlag & network_interfaces_map["THREAD"]:
    mac_network_interface = "THREAD"
elif matter_device.networkCommissioningCluster.featureFlag & network_interfaces_map["ETHERNET"]:
    mac_network_interface = "ETHERNET"

connections = [{
    "type": "MATTER",
    "macAddress": matter_device.get_mac_address(),
    "macNetworkInterface": mac_network_interface,
    "matterVendorId": matter_device.basicInformationCluster.vendorId,
    "matterProductId": matter_device.basicInformationCluster.productId,
    "matterDiscriminator": matter_device.get_discriminator()
}]

検出

Alexa.Commissionableインターフェースをサポートするエンドポイントは、Alexa.Discoveryインターフェースの標準検出メカニズムを使用して表します。検出応答でAlexa.Commissionable機能をレポートすると、Alexaは、ユーザーのアカウントで利用可能なデバイスがあること、そのデバイスをローカルでEchoデバイスとペアリングできることを認識します。

検出応答プロパティに、Matter固有の設定をMatterの要件に従って適用します。

検出応答の例

以下は、Alexa.CommissionableインターフェースとAlexa.EndpointHealthインターフェースをサポートするMatter対応エンドポイントの検出応答の例です。

クリップボードにコピーされました。

{
    "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": "Matterの一意ID"
                },
                "cookie": {},
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.Commissionable",
                        "version": "1.0"
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3.1",
                        "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": "MatterベンダーID",
                "matterProductId": "Matter製品ID",
                "matterDiscriminator": "longDiscriminator"
            } ],
            "relationships": {}
            }]
        }
    }
}

AddOrUpdateReport

新規のMatterエンドポイントをコミッションしたり既存のエンドポイントを更新したりするには、Alexa.Discovery.AddOrUpdateReportイベントをプロアクティブに送信します。たとえば、ファームウェアアップデートで既存のエンドポイントをMatterに対応させたら、更新をレポートします。詳細については、AddOrUpdateReportを参照してください。

Matter固有の設定は、Matterプロトコル固有の要件に従って適用します。

AddOrUpdateReportイベントの例

以下は、新しいMatterエンドポイントに対して、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": "Matterの一意ID"
                },
                "cookie": {},
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.Commissionable",
                        "version": "1.0"
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3.1",
                        "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": "MatterベンダーID",
                "matterProductId": "Matter製品ID",
                "matterDiscriminator": "longDiscriminator"
            } ],
            "relationships": {}
            }]
        }
    }
}

ディレクティブとイベント

Alexa.Commissionableインターフェースは、次のディレクティブとイベントを定義します。

ReportCommissioningInformationディレクティブ

Discover.ResponseまたはAddOrUpdateReportイベントにAlexa.Commissionable機能がある場合、AlexaはReportCommissioningInformationディレクティブをスキルに送信します。このディレクティブを使って、Alexaはデバイス制御クラウドに、ローカルコミッションを有効にするために必要なアクションを実行するようリクエストします。

Matterデバイスの場合、次のアクションが発生します。

  • このディレクティブを受信すると、デバイス制御クラウドはデバイスを一定期間コミッションモードに設定し、コミッションの認証情報を返します。
  • また、デバイス制御クラウドは、デバイスがコミッションモードに設定される期間を表すコミッション有効期限のタイムスタンプも返します。

ReportCommissioningInformationディレクティブの例

以下は、Alexaがスキルに送信するReportCommissioningInformationディレクティブの例です。

{
    "directive": {
        "header": {
            "namespace": "Alexa.Commissionable",
            "name": "ReportCommissioningInformation",
            "messageId": "一意のバージョン4 UUID",
            "correlationToken": "opaque相関トークン",
            "payloadVersion": "1.0"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "OAuth2ベアラートークン"
            },
            "endpointId": "エンドポイントID",
            "cookie": {}
        },
        "payload": {}
    }
}

ReportCommissioningInformationディレクティブのペイロード

ReportCommissioningInformationディレクティブは、ペイロードパラメーターを定義しません。

ReportCommissioningInformationディレクティブの応答

スキルが正常にReportCommissioningInformationディレクティブを処理し、デバイスをコミッションモードに設定すると、CommissioningInformationReportイベントで応答します。

ReportCommissioningInformationディレクティブのエラー処理

スキルが正常にReportCommissioningInformationディレクティブを処理できず、コミッション固有のエラーの場合、Alexa.ReportCommissioningInformation.ErrorResponseイベントで応答します。一般的なエラーの場合、Alexa.ErrorResponseで応答します。ReportCommissioningInformationのエラータイプに加え、ENDPOINT_BUSY、ENDPOINT_UNREACHABLE、BRIDGE_UNREACHABLEといった一般的なAlexaのエラータイプを使うこともできます。

CommissioningInformationReportイベント

CommissioningInformationReportイベントをAlexaイベントゲートウェイに送信して、Alexaにデバイスがコミッションモードになったことを通知します。ReportCommissioningInformationディレクティブへの応答として、CommissioningInformationReportを送信します。

CommissioningInformationReportイベントの例

以下は、正常なCommissioningInformationReportイベントの例です。

クリップボードにコピーされました。

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

CommissioningInformationReportイベントのペイロード

次の表は、CommissioningInformationReport応答イベントのペイロードの詳細を示しています。

プロパティ 説明 型 必須

CommissioningInformation

Echoをデバイスとペアリングできるローカルプロトコルのリストです。

オブジェクトの配列

〇

CommissioningInformation.localProtocol

ローカルネットワーク上でこのデバイスとコミッションするプロトコルを指定します。
有効な値は MATTERです。

文字列

◯

CommissioningInformation.protocolData

プロトコル固有のコミッション情報です。

オブジェクト

◯

CommissioningInformation.protocolData.manualPairingCode

現在のMatter管理者がオープン中のコミッションウィンドウに入るよう指示したときに、Matterデバイスによって生成されるコードです。

文字列

◯

CommissioningInformation.protocolData.commissioningWindowExpirationTimestamp

Alexaがローカル接続を作成できなくなった後の、コミッションの期間（日時）を表します。このタイムスタンプによってAlexaは特定の時間までリトライを制限できます。また、Alexaがローカル接続できない理由がコミッション期限切れである場合には、トラブルシューティングにも役立ちます。
ISO 8601形式で定義し、YYYY-MM-DDThh:mm:ssZとなります。

文字列

✕

CommissioningInformationReport応答

成功すると、Alexaは、Alexaサービスがイベントを受け入れて詳しい論理検証と処理を行うことを示す202 Acceptedを送信します。イベントが受け入れられない場合、Alexaは適切なHTTPステータスコードを送信します。

このページは役に立ちましたか？

最終更新日: 2024 年 11 月 12 日