?
サポート

Alexa.Discoveryインターフェース

Alexa.Discovery

Alexa.Discoveryインターフェースには、デバイス制御クラウドに登録されているエンドユーザーデバイスの一覧をリクエストし、特定するために使用されるメッセージが含まれます。ユーザーのスマートホームスキルに関連付けられているデバイスやシーンを検出できるように、Discoveryディレクティブに応答する必要があります。

ディレクティブ

このインターフェースの制御とクエリのディレクティブは、次の言語を対象とするスキルでサポートされています。

  • 英語(米国)
  • 英語(英国)
  • 英語(インド)
  • ドイツ語
  • 日本語

詳細については、「スマートホームスキルを複数の言語で開発する」を参照してください。

Discover

エンドユーザーのデバイス制御クラウドアカウントに関連付けられたデバイスやシーンの検出をリクエストします。検出するデバイスがない場合や、ユーザーのアクセストークンが期限切れになっている場合、またはデバイス制御クラウドで他のエラーが発生した場合には、スキルは空のDiscover.Responseを返します。エラーメッセージは返しません。

「Alexa、デバイスを見つけて」

「Alexa, discover my smart home devices」

Discovery

{
  "directive": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover",
      "payloadVersion": "3",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
    },
    "payload": {
      "scope": {
        "type": "BearerToken",
        "token": "some-access-token"
      }
    }
  }
}

ペイロードの詳細

検出リクエストのペイロードに含まれるオブジェクトは、scope オブジェクトだけです。

scope は、メッセージに認証および識別情報を提供するポリモーフィックなオブジェクトです。Discover リクエストの場合、デバイス制御クラウドで管理されているユーザーを識別するための ベアラートークンが、scope に含まれます。これはアカウントリンクによってスキルから与えられたトークンの値です

イベントとプロパティ

このインターフェースでは、次の応答を使用する必要があります。

  • 同期的。つまり、Lambda関数からAlexaにResponseを送信します。

Responseを送信するときには、メッセージのcontextにレポート可能なプロパティの状態を含める必要があります。

レポート可能なプロパティ

なし

Discover.Response

エンドユーザーのデバイス制御クラウドアカウントに関連付けられたすべてのデバイスを返します。Discoverディレクティブへの予期される応答です。この応答で、一意の識別子、デバイスにユーザーが付けた名前、各デバイスのどのプロパティが取得可能かなどの、各デバイスの詳細を提供し、その現在の状態を報告します。検出するデバイスがない場合、またはデバイスクラウドでエラーが発生した場合、空のendpointsを返します。

Discover.Response例:

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "appliance-001",
          "friendlyName": "Living Room Light",
          "description": "Smart Light by Sample Manufacturer",
          "manufacturerName": "Sample Manufacturer",
          "displayCategories": [
            "LIGHT"
          ],
          "cookie": {
            "extraDetail1": "optionalDetailForSkillAdapterToReferenceThisDevice",
            "extraDetail2": "There can be multiple entries",
            "extraDetail3": "but they should only be used for reference purposes",
            "extraDetail4": "This is not a suitable place to maintain current device state"
          },
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ColorTemperatureController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "colorTemperatureInKelvin"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.EndpointHealth",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "connectivity"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ColorController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "color"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "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
              }
            }
          ]
        },
        {
          "endpointId": "appliance-002",
          "friendlyName": "Hallway Thermostat",
          "description": "Smart Thermostat by Sample Manufacturer",
          "manufacturerName": "Sample Manufacturer",
          "displayCategories": [
            "THERMOSTAT"
          ],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ThermostatController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "lowerSetpoint"
                  },
                  {
                    "name": "targetSetpoint"
                  },
                  {
                    "name": "upperSetpoint"
                  },
                  {
                    "name": "thermostatMode"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.TemperatureSensor",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "temperature"
                  }
                ],
                "proactivelyReported": false,
                "retrievable": true
              }
            }
          ]
        },
        {
          "endpointId": "appliance-003",
          "friendlyName": "Front Door",
          "description": "Smart Lock by Sample Manufacturer",
          "manufacturerName": "Sample Manufacturer",
          "displayCategories": [
            "SMARTLOCK"
          ],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.LockController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "lockState"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            }
          ]
        },
        {
          "endpointId": "appliance-004",
          "friendlyName": "Goodnight",
          "description": "Smart Scene by Sample Manufacturer",
          "manufacturerName": "Sample Manufacturer",
          "displayCategories": [
            "SCENE_TRIGGER"
          ],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.SceneController",
              "version": "3",
              "supportsDeactivation": false,
              "proactivelyReported": true
            }
          ]
        },
        {
          "endpointId": "appliance-005",
          "friendlyName": "Watch TV",
          "description": "Smart Activity by Sample Manufacturer",
          "manufacturerName": "Sample Manufacturer",
          "displayCategories": [
            "ACTIVITY_TRIGGER"
          ],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.SceneController",
              "version": "3",
              "supportsDeactivation": true,
              "proactivelyReported": true
            }
          ]
        },
        {
          "endpointId": "appliance-006",
          "friendlyName": "Back Door Camera",
          "description": "Smart Camera by Sample Manufacturer",
          "manufacturerName": "Sample Manufacturer",
          "displayCategories": [
            "CAMERA"
          ],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.CameraStreamController",
              "version": "3",
              "cameraStreamConfigurations": [
                {
                  "protocols": [
                    "RTSP"
                  ],
                  "resolutions": [
                    {
                      "width": 1920,
                      "height": 1080
                    },
                    {
                      "width": 1280,
                      "height": 720
                    }
                  ],
                  "authorizationTypes": [
                    "BASIC"
                  ],
                  "videoCodecs": [
                    "H264",
                    "MPEG2"
                  ],
                  "audioCodecs": [
                    "G711"
                  ]
                },
                {
                  "protocols": [
                    "RTSP"
                  ],
                  "resolutions": [
                    {
                      "width": 1920,
                      "height": 1080
                    },
                    {
                      "width": 1280,
                      "height": 720
                    }
                  ],
                  "authorizationTypes": [
                    "NONE"
                  ],
                  "videoCodecs": [
                    "H264"
                  ],
                  "audioCodecs": [
                    "AAC"
                  ]
                }
              ]
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.PowerController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "powerState"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            }
          ]
        }
      ]
    }
  }
}

ペイロードの詳細

フィールド 説明 必須
endpoints ユーザーのデバイス制御クラウドアカウントと関連付けられたデバイスを表す、endpointオブジェクトの配列です。ユーザーのアカウントに関連付けられたデバイスがない場合、このプロパティには空の配列が含まれます。エラーが発生した場合は、このプロパティはNullとなる場合があります。配列に格納できるアイテムの最大数は300です。 オブジェクト配列

endpointオブジェクト

お客様のデバイス制御クラウドアカウントと関連付けられた、接続済みデバイスを表します。

フィールド 説明 必須
endpoint.endpointId デバイスの識別子。この識別子は、スキルのドメイン内で1人のエンドユーザーが所有するすべてのデバイスの間でユニークである必要があります。また、複数回の Discovery リクエストに対して、同じデバイスは常に同じ識別子を返す必要があります。識別子には、英数字を使用できます。また以下の特殊文字も使用できます。_ - = # ; :?@ &。識別子は、256文字以内でなければなりません。 英数字および以下の特殊文字を含む文字列:_ - = # ; :?@ &
endpoint.manufacturerName デバイスメーカーの名前。この値は128文字以内でなければなりません。 string
endpoint.friendlyName デバイスを識別するためにユーザーが使用する名前。この値は128文字以内でなければなりません。また特殊文字や句読点を使用できません。 string
endpoint.description 人間が読める形式の、デバイスの説明。この値は128文字以内でなければなりません。説明には、メーカー名またはデバイスの接続方法を含める必要があります。たとえば、「サンプルメーカーによるSmart Lock」や、「SmartHubを介して接続するWiFiサーモスタット」などです。この値は128文字以内でなければなりません。 string
endpoint.displayCategories Alexaアプリ内でデバイスが表示されるグループ名を示します。サポートされている値については、表示カテゴリーを参照してください。 文字列配列
endpoint.cookie スキルが使用するデバイスについての追加情報を表す、文字列名/値のペアです。このプロパティの内容は5,000バイト以内でなければなりません。APIはこのデータを使用せず、また解釈もしません。 文字列と値のペアのマップ ×
endpoint.capabilities デバイスがサポートし応答できるアクションを表す、capabilityオブジェクトの配列です。capabilityオブジェクトは、型によって異なるフィールドを含みます。 オブジェクト配列

表示カテゴリー

表示カテゴリーに正しい値を指定すると、そのエンドポイントはAlexaアプリの中で正しいカテゴリー、正しいアイコンで表示されます。これにより、ユーザーはデバイスを簡単に見つけ、状態を確認することができるようになります。

説明 備考
ACTIVITY_TRIGGER 特定の状態に遷移するために複数のデバイスが一定の順序で操作されるようなものを示します。たとえば、「Netflixを視聴する」シーンが次の操作を行うような場合です。1.テレビの電源がオンにする、2.入力をHDMI1に設定する シーンに適用
CAMERA ビデオや写真の機能を備えたメディア端末を示します。  
DOOR ドアを示します。  
LIGHT 光源または照明器具を示します。  
OTHER 他のカテゴリーに該当しないエンドポイント。  
SCENE_TRIGGER 特定の状態に遷移するために複数のデバイスが操作されるようなものを示します。ACTIVITY_TRIGGERと異なり、それぞれの操作は常に一定の順序である必要はないものを示しています。たとえば、「ベッドタイム」シーンには、照明を消してサーモスタットの設定温度を下げる処理が含まれますが、この処理の順序は重要ではありません。 シーンに適用
SMARTLOCK ロックするエンドポイントを示します。  
SMARTPLUG コンセントに差し込み、電源のON/OFFなどができるモジュールを示します。 さまざまなデバイスを制御できます。
SPEAKERS エンドポイントがスピーカーまたはスピーカーシステムであることを示します。  
SWITCH 壁埋込型の電源スイッチを示します。 さまざまなデバイスを制御できます。
TEMPERATURE_SENSOR 温度のレポートのみを行うエンドポイントを示します。  
THERMOSTAT 温度を制御するエンドポイント、独立した空調機器、直接温度制御機能を備えたヒーターなどを示します。  
TV エンドポイントがテレビであることを示します。  

capabilityオブジェクト

capabilityはポリモーフィックな型です。現在のところ、capabilityがサポートする唯一の型はAlexaInterfaceです。

AlexaInterface の capability

エンドポイントが実行できるアクションと、取得できるプロパティを示し、状態クエリーと、状態変化のイベント通知が可能かを示します。

フィールド 説明 必須
type capabilityの型を示し、capabilityがどのフィールドを持つかを決定します。 文字列「AlexaInterface」
interface デバイスが対応するアクションを示します。対応するインターフェースの修飾名を記述します。 string
version このエンドポイントがサポートするインターフェースバージョンを示します。 string
properties.supported このエンドポイントがサポートするインターフェースのプロパティを、"name":"<propertyName>"形式で示します。この配列内の reportable プロパティを特定しない場合、デフォルトでプロパティ proactivelyReportedretrievable は「false」とみなされます。 名前/値ペアの配列 ×
proactivelyReported このエンドポイントにリストされているプロパティの値が変化した時Change.Reportイベントを生成するかどうかを示します。 ブール値 ×
retrievable このエンドポイントに対してリストされているプロパティを、状態レポートのために取得できるかどうかを示します。 ブール値 ×
capabilityのバージョン

capabilityのバージョンは、単独で変更することができます。インターフェースを実装するときは常にインターフェースのトピックを確認し、現在のバージョンが何なのかを調べ、capabilityでは適切な値を与えてください。

追加の例

エンターテイメント端末のDiscover.Responseの例

{
   "event":{
      "header":{
         "namespace":"Alexa.Discovery",
         "name":"Discover.Response",
         "payloadVersion":"3",
         "messageId":"5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4"
      },
      "payload":{
         "endpoints":[
            {
               "endpointId":"appliance-001",
               "friendlyName":"Living Room Sound System",
               "description":"Smart Speaker by Sample Manufacturer",
               "manufacturerName":"Sample Manufacturer",
               "displayCategories": ["SPEAKERS"],
               "cookie":{
                  "extraDetail1":"optionalDetailForSkillAdapterToReferenceThisDevice",
                  "extraDetail2":"There can be multiple entries",
                  "extraDetail3":"but they should only be used for reference purposes",
                  "extraDetail4":"This is not a suitable place to maintain current device state"
               },
               "capabilities":[
                  {
                     "type":"AlexaInterface",
                     "interface":"Alexa.Speaker",
                     "version":"1.0",
                     "properties":{
                        "supported":[
                           {
                              "name":"volume"
                           },
                           {
                              "name":"muted"
                           }
                        ]
                     }
                  },
                  {
                     "type":"AlexaInterface",
                     "interface":"Alexa.StepSpeaker",
                     "version":"1.0",
                     "properties":{

                     }
                  }
               ]
            }
         ]
      }
   }
}

ビデオスキルのDiscover.Responseの例

{
    "event": {
        "header": {
            "messageId": "0a29824b-9299-4d55-b0c3-1d96ecfae81e",
            "name": "Discover.Response",
            "namespace": "Alexa.Discovery",
            "payloadVersion": "3"
        },
        "payload": {
            "endpoints": [
                {
                    "capabilities": [
                        {
                            "interface": "Alexa.RemoteVideoPlayer",
                            "type": "AlexaInterface",
                            "version": "1.0"
                        },
                        {
                            "interface": "Alexa.ChannelController",
                            "type": "AlexaInterface",
                            "version": "1.0"
                        },
                        {
                            "interface": "Alexa.PlaybackController ",
                            "type": "AlexaInterface",
                            "version": "1.0"
                        }
                    ],
                    "endpointId": "videoDevice-001",
                    "description": "Device description for the customer",
                    "displayCategories": ["OTHER"],
                    "friendlyName": "Upstairs Amazon Player",
                    "manufacturerName": "Amazon",
                    "cookie": {}

                }
            ]
        }
    }
}

追加のサンプルコード

リクエストの例と応答メッセージについては、AlexaスマートホームGitHubリポジトリを参照してください。

検出