Alexa検出について

Alexa検出について

スマートホームスキルを有効にしてデバイスアカウントとHAQMアカウントをリンクしたユーザーは、Alexaにデバイスの検出をリクエストできます。Alexaは、有効になったスキルを使用して検出プロセスを開始し、ユーザーのコネクテッドデバイスに関する情報を取得します。ユーザーのデバイスアカウントに関連付けられたデバイスを識別するためには、Discoveryインターフェースを実装する必要があります。検出が完了するとAlexaアプリにデバイスのリストが表示され、Alexaにデバイスの制御をリクエストできます。

デバイスの説明に基づいて、各機能に対するプリビルド音声対話モデル（デバイスを制御するユーザー発話を定義）が自動的に有効になり、Alexaアプリと定型アクションを介したデバイスの制御も有効になります。

Discoveryインターフェース

ユーザーがAlexaアプリでスキルを有効にするか、Alexaにデバイスの検出をリクエストすると、Alexa.Discovery.Discoverディレクティブがスキルに送信され、コネクテッドデバイスに関する情報をリクエストします。このリクエストには、リクエストをシステムのユーザーアカウントに関連付けるアクセストークンが含まれています。ユーザーアカウントに関連付けられたデバイスを取得するため、スキルはこのアクセストークンを指定したリクエストをデバイス制御クラウドに送信し、クラウドはユーザーの既知のデバイスのリストを返します。

検出応答には、デバイスのエンドポイント、各エンドポイントの機能、および必要な場合はインターフェースの設定を含めます。検出応答の例は、各インターフェースのドキュメントを参照してください。デバイスタイプ別の詳細な例は、検出応答の例を参照してください。

エンドポイントを識別する

エンドポイントはユーザーのデバイスアカウントに関連付けられたコネクテッドデバイスを表し、以下のいずれかの詳細が含まれます。

  • 物理デバイス
  • 仮想デバイス
  • デバイスのグループまたは集合（シーン内のデバイスなど）
  • ソフトウェアコンポーネント（モバイルアプリなど）

各エンドポイントには、エンドポイントの一意のIDに加えて、メーカーやモデル、シリアル番号など、できるだけ多くの識別情報を定義します。これらの情報はAlexaアプリのユーザーエクスペリエンス向上に役立ちます。また、各エンドポイントの表示カテゴリーとフレンドリー名も指定します。表示カテゴリーによってAlexaアプリ内に表示されるアイコンとアイコンの位置が決まり、フレンドリー名はAlexaへのリクエストでデバイスの識別に使用します。ユーザーはフレンドリー名をAlexaアプリ内で変更できます。Endpointオブジェクトの詳細については、Endpointオブジェクトの詳細を参照してください。

以下は、照明エンドポイントの設定例です。

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

{
    "endpointId": "エンドポイントの一意のID",
    "manufacturerName": "サンプルメーカー",
    "description": "サンプルメーカーのスマート照明",
    "friendlyName": "リビングの照明",
    "displayCategories": ["LIGHT"],
    "additionalAttributes": {
        "manufacturer": "サンプルメーカー",
        "model": "サンプルモデル",
        "serialNumber": "デバイスのシリアル番号",
        "firmwareVersion": "デバイスのファームウェアバージョン",
        "softwareVersion": "デバイスのソフトウェアバージョン",
        "customIdentifier": "デバイスの任意のカスタム識別子"
    },
    "capabilities": [],
    "connections": [],
    "relationships": {},
    "cookie": {}
}

デバイスの機能を宣言する

検出応答には各エンドポイントの機能を含めます。エンドポイントの機能とはデバイスの機能で、指定するには応答にスマートホームAPIインターフェースを含めます。エンドポイントの機能を最もよく表すインターフェースを組み合わせて指定しください。たとえば、オン／オフの切り替えと明るさを調整できる照明の場合、実装すべきインターフェースは Alexa.PowerControllerとAlexa.BrightnessControllerの2つです。サポートする機能には、デバイスの状態に問題（バッテリー残量の低下や切断など）が発生した場合にユーザーに通知されるよう、必ずAlexa.EndpointHealthも含めてください。また、すべてのエンドポイントにAlexaインターフェースを含める必要があります。使用可能なスマートホームAPIについては、Alexaインターフェースとサポートしている言語の一覧を参照してください。

出力可能な各プロパティをretrievable = trueに設定し、スキルがサポートするAlexaインターフェースをproactivelyReported = trueに設定します。また、displayCategoriesプロパティをデバイスに最適なカテゴリーに設定してください。Alexaは、音声応答、Alexaアプリ、および画面付きAlexa搭載デバイスでデバイスの状態をユーザーに通知します。詳細については、状態および変更レポートについてを参照してください。

以下の例は、照明エンドポイントの機能を示しています。

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

{
    "capabilities": [{
            "type": "AlexaInterface",
            "interface": "Alexa.PowerController",
            "version": "3",
            "properties": {
                "supported": [{
                    "name": "powerState"
                }],
                "proactivelyReported": true,
                "retrievable": true
            }
        },
        {
            "type": "AlexaInterface",
            "interface": "Alexa.BrightnessController",
            "version": "3",
            "properties": {
                "supported": [{
                    "name": "brightness"
                }],
                "proactivelyReported": true,
                "retrievable": true
            }
        },
        {
            "type": "AlexaInterface",
            "interface": "Alexa.EndpointHealth",
            "version": "3.1",
            "properties": {
                "supported": [{
                    "name": "connectivity"
                }],
                "proactivelyReported": true,
                "retrievable": true
            }
        },
        {
            "type": "AlexaInterface",
            "interface": "Alexa",
            "version": "3"
        }
    ]
}

プロアクティブにエンドポイントを管理する

プロアクティブにエンドポイントを管理することで、Alexaはユーザーのデバイスについて常に最新の状態を把握することができます。そのためには、ユーザーがエンドポイントを追加、更新、または削除した際、変更についてプロアクティブにAlexaに通知します。変更内容は、非同期イベントとしてAlexaイベントゲートウェイに送信します。新しいエンドポイントに関するプロアクティブな更新を実装すると、デバイスが自動的にAlexaアプリに表示され、ユーザーは検出ステップをスキップできるようになります。

ユーザーが新しいエンドポイントを追加した場合、または既存のエンドポイントを更新したり名前を変更したりした場合、AddOrUpdateReportを送信してAlexaに新しいデバイスまたは更新されたデバイスを通知します。スキルの実装方法に応じて、ユーザーアカウントに関連付けられたすべてのエンドポイント、または新規または更新されたエンドポイントのみを含めることができます。

ユーザーがデバイスアカウントからデバイスを削除した場合、DeleteReportを送信してデバイスが使用されなくなったことをAlexaに通知します。

エンドポイント間の関係を識別する

リンクされたデバイスがAlexaアプリに複数のデバイスとして表示されると、ユーザーがデバイスを別々に表示したり、グループに追加しようとしたりする際に混乱を招く可能性があります。リンクされたデバイスには次のようなものがあります

  • 複合デバイス - スマートホームスキルがインストールされたAlexa搭載（ABI）デバイスなど
  • 複数のエンドポイントがあるスマートホーム製品
  • 複数のエンドポイントがあるシーン

リンクされたエンドポイント間の関係を報告するには、検出応答とプロアクティブな更新イベントにRelationshipsオブジェクトを含めます。これにより、Alexaアプリでは、関連するデバイスが親デバイスの下に表示されるようになります。また、ユーザーがグループに親を追加すると、関連するデバイスがすべて一緒に移動するようになります。たとえば、親がABIエンドポイントの場合はABI名がAlexaアプリに表示され、スマートホームデバイスの場合はエンドポイントのフレンドリー名が表示されます。

Alexa搭載エンドポイントで制御されるビデオデバイスの例

以下の例では、報告されたrelationshipsが、ビデオ機能のあるスマートホームエンドポイントとABIデバイスを関連付けています。この例ではABIデバイスがサウンドバーとテレビを制御しているため、Alexaは、メッセージとして ビデオスキルからDiscover.Responseを、ABIデバイスからAddOrUpdateReportを受け取ります。

この例では以下のエンドポイントIDを使用しています。

  • ABIのAlexa搭載ハブ： ABI-hub-endpointID
  • スマートホームのサウンドバー：soundbar-endpointID
  • テレビ：tv-endpointID

ホームシアターの例

以下の例では、報告されたrelationshipsが、複数のスマートホームエンドポイントをホームシアターのペアリングに関連付けています。この例では、スマートホームのサウンドバーがABIスピーカーとテレビを制御しています。この例では以下のエンドポイントIDを使用しています。

  • ABIスピーカー：speaker-endpoint-00X
  • スマートホームのサウンドバー：soundbar-endpointID
  • テレビ：tv-endpointID

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

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "AddOrUpdateReport",
            "payloadVersion": "3",
            "messageId": "一意の識別子、バージョン4 UUIDが望ましい"
        },
        "payload": {
            "scope": {
                "type": "BearerToken",
                "token": "sometoken.1"
            },
            "endpoints": [{
                    "endpointId": "soundbar-endpointID",
                    "friendlyName": "Living Room",
                    "displayCategories": ["SPEAKER"],
                    "relationships": {
                        "isClusterOf": [
                            {
                            "endpointId": "ABI-speaker-001",
                            "endpointTypeId": "speaker-productId-001",
                            "source": "AVS"
                            },
                            {
                            "endpointId": "ABI-speaker-002",
                            "endpointTypeId": "speaker-productId-001",
                            "source": "AVS"
                            },
                            {
                            "endpointId": "ABI-soundbar-001",
                            "endpointTypeId": "soundbar-productId-001",
                            "source": "AVS"
                            }
                        ]
                    }
                },
                {
                    "endpointId": "tv-endpointID",
                    "friendlyName": "TV",
                    "displayCategories": ["TV"],
                    "relationships": {
                        "isControlledBy": [{
                            "endpointId": "soundbar-endpointID"
                        }]
                    }
                }
            ]
        }
    }
}

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

最終更新日: 2025 年 06 月 13 日