Alexa.Discoveryインターフェース 3

Alexa.Discoveryインターフェース 3

Alexa.Discoveryインターフェースには、ユーザーのデバイスアカウントに関連付けられたエンドポイントの識別に使用するメッセージが含まれます。スマートホームスキルに関連付けられたエンドポイントをAlexaが検出できるように、検出ディレクティブに応答します。また、ユーザーアカウントに関連付けられたエンドポイントの追加、更新、削除を行うイベントをプロアクティブに送信します。

検出の概要については、Alexa検出についてを参照してください。

インターフェースの制限事項

検出インターフェースには、ユーザーごとに以下の制限があります。

  • エンドポイントの最大数 — 300
  • 各エンドポイントの機能の最大数 — 100
  • AddOrUpdateReportイベントの最大ペイロードサイズ — 256キロバイト（KB）

発話

Alexa.Discoveryインターフェースではプリビルド音声対話モデルを使用します。以下に、ユーザーの発話の例を示します。

اليكسا، اكتشف أجهزتي

Alexa, ontdek mijn apparaten.

Alexa, discover my smart home devices.

Alexa, finde meine smarten Geräte.

Alexa, découvre mes appareils.

Alexa, मेरे उपकरण खोजें.

Alexa, scopri miei dispositivi.

アレクサ、デバイスを検出して

Alexa, descubra meus dispositivos.

Alexa, descubre mis dispositivos.

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

Discoverディレクティブ

Discoverディレクティブをサポートすると、ユーザーはアカウントに関連付けられたスマートデバイスを探すことができます。ユーザーはAlexaにデバイスを探すように頼むか、またはAlexaアプリを開いてデバイスを検出を選択することができます。

Discoverディレクティブの例

次の例は、Alexaがスキルに送信するDiscoverディレクティブを示しています。

{
  "directive": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover",
      "messageId": "一意の識別子、バージョン4 UUIDが望ましい",
      "payloadVersion": "3"
    },
    "payload": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0ベアラートークン"
      }
    }
  }
}

Discoverディレクティブペイロードの詳細

フィールド 説明 型
scope リクエストの認可と識別情報を提供します。アクセストークンを使用してシステムでユーザーを識別します。 Scopeオブジェクト

Discoverの応答

Discoverディレクティブを正しく処理したら、Discover.Responseを使用して応答します。応答では、ユーザーのデバイス制御クラウドのアカウントに関連付けられているすべてのエンドポイントと、各デバイスに対してスキルがサポートする機能を返します。Alexaが一意のデバイスを識別できるよう、AdditionalAttributesオブジェクトを含め、できるだけ多くのフィールドを設定してください。Amazonでは、少なくともモデルとメーカーを含めることを推奨しています。

出力可能な各プロパティをretrievable = trueに設定し、スキルがサポートするAlexaインターフェースをproactivelyReported = trueに設定します。また、displayCategoriesプロパティをデバイスに最適なカテゴリーに設定してください。

検出応答の例

以下は、Alexa.PowerControllerインターフェースとAlexa.BrightnessControllerインターフェースをサポートする1つの照明に対するDiscover.Responseメッセージの例です。ほかの機能での検出応答の例を確認するには、各インターフェースのドキュメントを参照するか、その他の検出応答の例を参照してください。デバイスで正常性に関する問題（接続の切断など）が発生した場合にAlexaがユーザーに通知できるように、必ずAlexa.EndpointHealthをサポート対象の機能のリストに含めてください。また、すべてのエンドポイントにAlexaインターフェースを含める必要もあります。

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

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover.Response",
            "payloadVersion": "3",
            "messageId": "一意の識別子、バージョン4 UUIDが望ましい"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "エンドポイントの一意のID",
                "manufacturerName": "サンプルメーカー",
                "description": "サンプルメーカーのスマート照明",
                "friendlyName": "リビングの照明",
                "additionalAttributes": {
                    "manufacturer": "サンプルメーカー",
                    "model": "サンプルモデル",
                    "serialNumber": "デバイスのシリアル番号",
                    "firmwareVersion": "デバイスのファームウェアバージョン",
                    "softwareVersion": "デバイスのソフトウェアバージョン",
                    "customIdentifier": "デバイスの任意のカスタム識別子"
                },
                "displayCategories": ["LIGHT"],
                "cookie": {},
                "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"
                    }
                ],
                "connections": [
                    {
                        "type": "TCP_IP",
                        "macAddress": "00:11:22:AA:BB:33:44:55"
                    },
                    {
                        "type": "MATTER",
                        "macAddress": "00:11:22:AA:BB:33:44:55",
                        "macNetworkInterface": "WIFI",
                        "matterVendorId": "MatterベンダーID",
                        "matterProductId": "Matter製品ID",
                        "matterDiscriminator": "longDiscriminator"
                    }
                ]
            }]
        }
    }
}

検出応答のペイロード

フィールド 説明 型 必須
endpoints ユーザーのアカウントに関連付けられているデバイスと、各デバイスに対してスキルがサポートする機能を表します。ユーザーのアカウントに関連付けられたデバイスがない場合、このプロパティには空の配列が返されます。endpointsフィールドにはサイズ制限が適用されます。 Endpointオブジェクトの配列 ◯

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

Discoverディレクティブを正しく処理できなかった場合は、Alexa.ErrorResponseイベントを使用して応答します。次のエラータイプのうち、適切なものを使用します： BRIDGE_UNREACHABLE、EXPIRED_AUTHORIZATION_CREDENTIAL、INSUFFICIENT_PERMISSIONS、INTERNAL_ERROR、INVALID_AUTHORIZATION_CREDENTIAL。

AddOrUpdateReportイベント

ユーザーが新しいエンドポイントをアカウントに追加する場合や、シーン名の変更など既存のエンドポイントに変更を加える場合、AddOrUpdateReportイベントをプロアクティブに送信します。AddOrUpdateReportイベントをAlexaイベントゲートウェイに送信します。ユーザーアカウントに関連付けられたすべてのエンドポイントか、新規または更新されたエンドポイントのみを含めることができます。スキルの実装内容に応じて選択できます。

AddOrUpdateReportイベントの例

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

POST /v3/events HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer access-token-from-Amazon
Content-Type: application/json
{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "AddOrUpdateReport",
            "payloadVersion": "3",
            "messageId": "一意の識別子、バージョン4 UUIDが望ましい"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "エンドポイントの一意のID",
                "manufacturerName": "サンプルメーカー",
                "description": "サンプルメーカーのスマート照明",
                "friendlyName": "キッチンの照明",
                "additionalAttributes": {
                    "manufacturer": "サンプルメーカー",
                    "model": "サンプルモデル",
                    "serialNumber": "デバイスのシリアル番号",
                    "firmwareVersion": "デバイスのファームウェアバージョン",
                    "softwareVersion": "デバイスのソフトウェアバージョン",
                    "customIdentifier": "デバイスの任意のカスタム識別子"
                },
                "displayCategories": ["LIGHT"],
                "cookie": {},
                "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"
                    }
                ],
                "connections": [{
                    "type": "BLUETOOTH_MESH",
                    "deviceUuid": "90b6eeb8cb58c9a7887d4797543bbe8a"
                }]
            }],
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-Amazon"
            }
        }
    }
}

AddOrUpdateReportイベントのペイロード

フィールド 説明 型 必須
endpoints ユーザーのアカウントに関連付けられているデバイスと、それに対してスキルがサポートする機能を表します。ユーザーのアカウントに関連付けられたデバイスがない場合、このプロパティには空の配列が返されます。endpoints配列にはサイズ制限が適用されます。 Endpointオブジェクトの配列 ◯
scope Alexaに対してユーザーを識別するベアラートークンを含みます。 Scopeオブジェクト ◯

DeleteReportイベント

ユーザーがアカウントからエンドポイントを削除する場合、DeleteReportイベントをプロアクティブに送信します。DeleteReportメッセージをAlexaイベントゲートウェイに送信します。

DeleteReportイベントの例

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

POST /v3/events HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer access-token-from-Amazon
Content-Type: application/json
{
  "event": {
    "header": {
        "namespace": "Alexa.Discovery",
        "name": "DeleteReport",
        "messageId": "一意の識別子、バージョン4 UUIDが望ましい",
        "payloadVersion": "3"
    },
    "payload": {
      "endpoints": [
          {
              "endpointId": "エンドポイントID 1"
          },
          {
              "endpointId": "エンドポイントID 2"
          }
      ],
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0ベアラートークン"
      }
    }
  }
}

DeleteReportイベントのペイロード

フィールド 説明 型 必須
endpoints ユーザーアカウントから削除するエンドポイントです。Discover.ReponseイベントまたはAddOrUpdateReportイベントで定義されている有効なendpointIdを使用します。 文字列の配列 ◯
scope Alexaに対してユーザーを識別するベアラートークンを含みます。 Scopeオブジェクト ◯

表示カテゴリー

検出応答で表示カテゴリーを指定すると、エンドポイントがAlexaアプリの正しいカテゴリーに、正しいアイコンで表示され、ユーザーは簡単にデバイスを見つけてモニタリングできるようになります。displayCategoriesプロパティをデバイスに最適なカテゴリーに設定してください。

値 説明
ACTIVITY_TRIGGER 特定の状態に設定されたデバイスの組み合わせです。状態変化が特定の順序で起こる場合は、シーンのアクティビティトリガーを使用します。たとえば、「Netflixを観る」というシーンの場合、まずテレビの電源をオンにしてから、入力をHDMI1に設定します。
AIR_CONDITIONER 室内空間の空気を冷却するデバイスです。
AIR_FRESHENER 室内空間で心地よい香りを放出し、不快な臭いを消臭するデバイスです。
AIR_PURIFIER 室内空間の空気の質を向上させるデバイスです。
AIR_QUALITY_MONITOR 室内空間の空気の質を測定するデバイスです。
ALEXA_VOICE_ENABLED Alexa搭載デバイスです。
AUTO_ACCESSORY 車載カメラなど、自動車内のスマートデバイスです。
BLUETOOTH_SPEAKER Bluetooth経由でオーディオソースに接続するスピーカーです。
CAMERA ビデオまたは写真機能を持つセキュリティデバイスです。
CHRISTMAS_TREE クリスマスの装飾です。多くの場合、ライトが付いています。
COFFEE_MAKER コーヒーを淹れるデバイスです。
COMPUTER デスクトップコンピューターなど、モバイル以外のコンピューターです。
CONTACT_SENSOR 2面間の接点で発生した変化を検出してレポートするエンドポイントです。
DISHWASHER 食器を洗う家電機器です。
DOOR 建物、部屋、クローゼット、食器棚、車両の出入口となるエンドポイントです。
DOORBELL スマートドアベルです。
DRYER 濡れた衣類を乾燥させる家電機器です。
EXTERIOR_BLIND 建物の窓の外側に取り付けられたブラインドやシェードなどです。
FAN 冷却や換気を行うデバイスです。
GAME_CONSOLE Microsoft XboxやNintendo Switchなどのビデオゲーム機です。
GARAGE_DOOR 車両をガレージに入れるためのエンドポイントです。ガレージドアの開閉を行うには、Alexa.ModeControllerインターフェースを実装する必要があります。
HEADPHONES 音声を直接耳に伝えるウェアラブルデバイスです。
HUB スマートホームハブです。
INTERIOR_BLIND 建物の窓の内側に取り付けられたブラインドやシェードなどです。
LAPTOP ノートパソコンなどのモバイルコンピューターです。
LIGHT 光源または照明器具です。
MICROWAVE 電子レンジ調理器です。
MOBILE_PHONE 携帯電話です。
MOTION_SENSOR ある範囲で発生した動きを検出してレポートするエンドポイントです。
MUSIC_SYSTEM ネットワーク接続型の音楽システムです。
NETWORK_HARDWARE ネットワークルーターです。
OTHER ほかのカテゴリーのいずれにも当てはまらないエンドポイントです。
OVEN オーブン調理器です。
PHONE 固定電話やIP電話など、携帯電話以外の電話です。
PRINTER 印刷用のデバイスです。
REMOTE リモートスイッチやスマートボタンなど、ステートレスイベントをサポートするデバイスです。
ROUTER ネットワークルーターです。
SCENE_TRIGGER 特定の状態に設定されたデバイスの組み合わせです。状態変化の順序が重要でないシーンの場合はシーントリガーを使用します。たとえば、「就寝」というシーンの場合、照明を消し、サーモスタットの設定温度を下げますが、その順序は問いません。
SCREEN プロジェクタースクリーンです。
SECURITY_PANEL セキュリティパネルです。
SECURITY_SYSTEM セキュリティシステムです。
SLOW_COOKER カウンターに置いて低温で調理するための電気調理器です。多くの場合、調理鍋のような形をしています。
SMARTLOCK ロックをかけるエンドポイントです。
SMARTPLUG 既存の電源コンセントに差し込むモジュールです。このモジュールにデバイスを接続します。たとえば、ユーザーはスマートプラグを電源コンセントに差し込み、照明をスマートプラグに接続することができます。スマートプラグでさまざまなデバイスを制御できます。
SPEAKER スピーカーまたはスピーカーシステムです。
STREAMING_DEVICE Apple TV、Chromecast、Rokuなどのストリーミングデバイスです。
SWITCH 電気システムに直接配線されたスイッチです。スイッチでさまざまなデバイスを制御できます。
TABLET タブレットコンピューターです。
TEMPERATURE_SENSOR 温度をレポートするエンドポイントです。温度の制御は行いません。エンドポイントの温度データは、Alexaアプリでは表示されません。エンドポイントで温度の管理も行う場合、代わりにTHERMOSTATを使用します。
THERMOSTAT 温度、スタンドアロンのエアコン、直接温度制御が可能なヒーターを制御するエンドポイントです。温度を検知しても制御は行わないエンドポイントの場合、代わりにTEMPERATURE_SENSORを使用します。
TV テレビです。
VACUUM_CLEANER 掃除機です。
VEHICLE 自動車です。
WASHER 衣類を洗濯する家電機器です。
WATER_HEATER 水を加熱するデバイスです。多くの場合、大型のタンクが使われています。
WEARABLE Apple Watch、Fitbit、Samsung Gearなど、ネットワーク接続型のウェアラブルデバイスです。

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

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