Alexa.Discoveryインターフェース

Alexa.Discoveryインターフェース

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

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

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

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

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

Discoverディレクティブ

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

以下は、ユーザーの発話の例です。

Alexa, discover my smart home devices.

Alexa, finde meine smarten Geräte.

Alexa, découvre mes appareils.

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

Discoverディレクティブの例

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

{
  "directive": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover",
      "messageId": "メッセージID",
      "payloadVersion": "3"
    },
    "payload": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2ベアラートークン"
      }
    }
  }
}

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

フィールド 説明 型
scope リクエストの認可と識別情報を提供します。 scopeオブジェクト

Discoverの応答

Discoverディレクティブを正しく処理したら、Discover.Responseイベントを使用して応答します。応答では、ユーザーのデバイス制御クラウドのアカウントに関連付けられているすべてのデバイスと、それに対してスキルがサポートする機能を返します。

Discoverの応答例

以下は、Alexa.PowerControllerインターフェースとAlexa.BrightnessControllerインターフェースをサポートする1つの照明に対するDiscover.Responseメッセージの例です。ほかの機能での検出応答の例を確認するには、各インターフェースのドキュメントを参照するか、その他の検出応答の例を参照してください。

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

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "＜一意の識別子、バージョン4 UUIDが望ましい＞"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "エンドポイントの一意のID",
          "manufacturerName": "サンプルメーカー",
          "description": "サンプルメーカーのスマート照明",
          "friendlyName": "リビングの照明",
          "additionalAttributes":  {
            "manufacturer" : "サンプルメーカー",
            "model" : "サンプルモデル",
            "serialNumber": “U11112233456”,
            "firmwareVersion" : "1.24.2546",
            "softwareVersion": "1.036",
            "customIdentifier": "サンプルカスタムID"
          },
          "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.2",
              "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": "ZIGBEE",
              "macAddress": "00:11:22:33:44:55"
            },
            {
              "type": "ZWAVE",
              "homeId": "0x00000000",
              "nodeId": "0x00"
            },
            {
              "type": "UNKNOWN",
              "value": "00:11:22:33:44:55"
            }
          ]
        }
      ]
    }
  }
}

Discover応答のペイロードの詳細

フィールド 説明 型 必須
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
              }
            }
          ],
          "connections": [
          ]
        }
      ],
      "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": "エンドポイントID1"
          },
          {
              "endpointId": "エンドポイントID2"
          }
      ],
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2ベアラートークン"
      }
    }
  }
}

DeleteReportイベントのペイロードの詳細

フィールド 説明 型 必須
endpoints ユーザーアカウントから削除するエンドポイントです。 エンドポイントIDの配列 ◯
scope Alexaに対してユーザーを識別するベアラートークンを含むオブジェクトです。 scopeオブジェクト ◯

表示カテゴリー

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

値 説明
ACTIVITY_TRIGGER 特定の状態に設定されたデバイスの組み合わせです。状態変化が特定の順序で起こる場合は、シーンのアクティビティトリガーを使用します。たとえば、「Netflixを観る」というシーンの場合、まずテレビの電源をオンにしてから、入力をHDMI1に設定します。
AIR_CONDITIONER 室内空間の空気を冷却するデバイスです。
AIR_FRESHENER 室内空間で心地よい香りを放出し、不快な臭いを消臭するデバイスです。
AIR_PURIFIER 室内空間の空気の質を向上させるデバイスです。
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 ガレージのドアです。ガレージドアでドアの開閉を行うには、ModeControllerインターフェースを実装する必要があります。
HEADPHONES 耳にオーディオを直接送信するウェアラブルデバイスです。
HUB スマートホームハブです。
INTERIOR_BLIND 建物の窓の内側に取り付けられたブラインドやシェードなどです。
LAPTOP ノートパソコンなどのモバイルコンピューターです。
LIGHT 光源または照明器具です。
MICROWAVE 電子レンジです。
MOBILE_PHONE 携帯電話です。
MOTION_SENSOR ある領域で発生した動きを検出してレポートするエンドポイントです。
MUSIC_SYSTEM ネットワークに接続された音楽システムです。
NETWORK_HARDWARE ネットワークルーターです。
OTHER ほかのカテゴリーのいずれにも当てはまらないエンドポイントです。
OVEN 調理器具のオーブンです。
PHONE 固定電話やIP電話などの携帯でない電話です。
PRINTER 印刷するデバイスです。
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など、ネットワークに接続されたウェアラブルデバイスです。