Alexa.Discoveryインターフェース



Alexa.Discoveryインターフェース

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

プロパティとオブジェクト

endpointオブジェクト

endpointオブジェクトは、ユーザーのデバイス制御クラウドアカウントと関連付けられた、接続済みデバイス/コンポーネントを表します。エンドポイントには以下のいずれかの詳細が含まれます。

  • 物理デバイス
  • 仮想デバイス
  • デバイスのグループまたは集合
  • ソフトウェアコンポーネント

endpointオブジェクトの例

{
  "endpointId": "<エンドポイントの一意のID>",
  "manufacturerName": "サンプルメーカー",
  "description": "サンプルメーカーのスマート照明",
  "friendlyName": "リビングの照明",
  "additionalAttributes":  {
  },
  "displayCategories": [
    "LIGHT"
  ],
  "capabilities": [
  ],
  "connections": [
  ],
  "cookie": {
    "extraDetail1": "スキルが使用する情報",
    "extraDetail2": "複数のエントリを作成できる",
    "extraDetail3": "ここにはデバイスの状態を保存しない"
  }
}

endpointオブジェクトのスキーマ

フィールド 説明 タイプ 必須
endpointId エンドポイントの識別子です。識別子は、スキルを使用するすべてのデバイスで一意である必要があります。また、同じデバイスのすべての検出リクエストに対して、識別子は常に同じである必要があります。識別子には、英数字、スペース、次の特殊文字を使用できます。使用可能な特殊文字:_ - = # ; : ? @ &。識別子は、256文字以内でなければなりません。 文字列
manufacturerName デバイスのメーカーの名前です。この値には最大128文字を含めることができます。 文字列
description デバイスの説明です。説明には、メーカー名またはデバイスの接続方法を含める必要があります。たとえば、「サンプルメーカーによるスマートロック」や、「SmartHubを介して接続するWiFiサーモスタット」などです。この値には最大128文字を含めることができます。 文字列
friendlyName デバイスを識別するためにユーザーが使用する名前です。この値には最大128文字を含めることができます。特殊文字や句読点は使用できません。 文字列
additionalAttributes エンドポイントについての追加情報です。 additionalAttributesオブジェクト
displayCategories Alexaアプリで、デバイスが表示されるカテゴリーです。 display categoriesの文字列の配列
capabilities スキルがエンドポイントをサポートする機能インターフェースです。Alexa.BrightnessControllerAlexa.PowerControllerなどです。 capabilityオブジェクトの配列
connections デバイスがインターネットとスマートホームハブへの接続に使用する方法についての情報です。 connectionオブジェクトの配列
cookie スキルが使用するデバイスについての情報です。このプロパティのコンテンツは5,000バイト以内でなければなりません。APIではこのデータの読み取りや使用はしません。 名前と値のペアのリスト

additionalAttributesオブジェクト

additionalAttributesオブジェクトには、エンドポイントについての追加情報が含まれます。Alexaは、さまざまなスキルが同じデバイスを異なる方法で表している場合に、この情報を使用してデバイスを識別できます。

additionalAttributesオブジェクトの例

{
  "additionalAttributes":  {
    "manufacturer" : "サンプルメーカー",
    "model" : "サンプルモデル",
    "serialNumber": "<デバイスのシリアル番号>",
    "firmwareVersion" : "<デバイスのファームウェアバージョン>",
    "softwareVersion": "<デバイスのソフトウェアバージョン>",
    "customIdentifier": "<デバイスのカスタム識別子>"
  }
}

additionalAttributesオブジェクトのスキーマ

フィールド 説明 タイプ 必須
manufacturer デバイスのメーカーの名前です。この値には最大256文字の英数字を含めることができ、句読点も含めることができます。 文字列
model デバイスのモデルの名前です。この値には最大256文字の英数字を含めることができ、句読点も含めることができます。 文字列
serialNumber デバイスのシリアル番号です。この値には最大256文字の英数字を含めることができ、句読点も含めることができます。 文字列
firmwareVersion デバイスのファームウェアバージョンです。この値には最大256文字の英数字を含めることができ、句読点も含めることができます。 文字列
softwareVersion デバイスのソフトウェアバージョンです。この値には最大256文字の英数字を含めることができ、句読点も含めることができます。 文字列
customIdentifier デバイスのカスタム識別子です。この識別子は、システム内ですべてのユーザーアカウントにわたってグローバルに一意である必要があります。この値には最大256文字の英数字を含めることができ、句読点も含めることができます。 文字列

capabilityオブジェクト

capabilityオブジェクトは、スキルがサポートするインターフェースを表します。たとえば、スキルがAlexa.PowerControllerインターフェースをサポートすると、照明の点灯をサポートできます。スマートホームデバイスで利用可能なインターフェースを確認するには、機能インターフェースの一覧を参照してください。

capabilityオブジェクトの例

{
    "type": "AlexaInterface",
    "interface": "Alexa.PercentageController",
    "version": "3",
    "properties": {
        "supported": [
            {
                "name": "percentage"
            }
        ],
        "proactivelyReported": true,
        "retrievable": true
    }
}

capabilityオブジェクトのスキーマ

フィールド 説明 タイプ 必須
type capabilityの種類です。現在使用できる種類はAlexaInterfaceのみです。 文字列
interface 機能インターフェースの名前です。 文字列
version インターフェースのバージョンです。インターフェースごとにバージョンが異なります。常にインターフェースのドキュメントを参照して、最新のバージョンを確認してください。 文字列
properties.supported スキルがサポートするインターフェースのプロパティです。 名前と値のペアの配列
proactivelyReported プロパティが変更されたときにスキルが変更レポートを送信する場合はtrueです。デフォルトはfalseです。 ブール値
retrievable 状態レポートリクエストに応答してプロパティの値をレポートする場合はtrueです。デフォルトはfalseです。 ブール値

connectionsプロパティ

connectionsプロパティは、デバイスがインターネットとスマートホームハブへの接続に使用する方法を表します。connectionsプロパティにはconnectionオブジェクトの配列が含まれます。

connectionsプロパティの例

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

connectionオブジェクトのスキーマ

フィールド 説明 タイプ 必須
type 接続の種類です。TCP_IPZIGBEEZWAVE、またはUNKNOWNのいずれかです。 文字列
macAddress ネットワークインターフェースコントローラー(NIC)の一意の識別子です。このフィールドは、接続の種類がTCP_IPまたはZIGBEEの場合に、オプションとして含めることができます。 文字列
homeId エンドポイントが接続するZ-WaveネットワークのホームIDです。形式は、UTF-8文字で0x00000000です。このフィールドは、接続の種類がZWAVEの場合に、オプションとして含めることができます。 文字列
nodeId エンドポイントが接続するZ-WaveネットワークのエンドポイントのノードIDです。形式は、UTF-8文字で0x00です。このフィールドは、接続の種類がZWAVEの場合に、オプションとして含めることができます。 文字列
value 接続の種類をより具体的に識別できない場合の接続の情報です。このフィールドで提供する情報は、安定した具体的なものである必要があります。この値には最大256文字の英数字を含めることができ、句読点も含めることができます。 文字列 typeがUNKNOWNである場合は◯

ディレクティブ

Discoverディレクティブ

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

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

Alexa, discover my smart home devices.

Alexa, finde meine smarten geräte.

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

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

Discoverディレクティブの例

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

Discover.Responseイベント

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

Discover.Responseイベントのペイロードの詳細

フィールド 説明 タイプ 必須
endpoints ユーザーのアカウントに関連付けられているデバイスと、それに対してスキルがサポートする機能です。ユーザーのアカウントに関連付けられたデバイスがない場合、このプロパティには空の配列が返されます。返すことができるエンドポイントの最大数は300です。 endpointオブジェクトの配列

Discover.Responseイベントの例

デバイスが照明である場合のDiscover.Responseの例を次に示します。他の機能でのDiscover.Responseの例を確認するには、機能インターフェースの一覧で各インターフェースのドキュメントを参照してください。

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "<メッセージID>"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "appliance-001",
          "manufacturerName": "サンプルメーカー",
          "description": "サンプルメーカーのスマート照明",
          "friendlyName": "リビングの照明",
          "additionalAttributes":  {
            "manufacturer" : "サンプルメーカー",
            "model" : "サンプルモデル",
            "serialNumber": "<デバイスのシリアル番号>",
            "firmwareVersion" : "<デバイスのファームウェアバージョン>",
            "softwareVersion": "<デバイスのソフトウェアバージョン>",
            "customIdentifier": "<デバイスのカスタム識別子>"
          },
          "displayCategories": [
            "LIGHT"
          ],
          "capabilities": [
              {
                "type": "AlexaInterface",
                "interface": "Alexa.BrightnessController",
                "version": "3",
                "properties": {
                  "supported": [
                    {
                      "name": "brightness"
                    }
                  ],
                  "proactivelyReported": true,
                  "retrievable": true
                }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ColorController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "color"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "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
              }
            }
          ],
          "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"
            }
          ],
          "cookie": {
          }
        }
      ]
    }
  }
}

ビデオデバイス向けDiscover.Responseの例

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "<メッセージID>"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "<エンドポイントの一意のID>",
          "manufacturerName": "<エンドポイントのメーカー名>",
          "description": "<Alexaアプリに表示される説明>",
          "friendlyName": "上の階のビデオプレイヤー",
          "additionalAttributes":  {
            "manufacturer" : "サンプルメーカー",
            "model" : "サンプルモデル",
            "serialNumber": "<デバイスのシリアル番号>",
            "firmwareVersion" : "<デバイスのファームウェアバージョン>",
            "softwareVersion": "<デバイスのソフトウェアバージョン>",
            "customIdentifier": "<デバイスのカスタム識別子>"
          },
          "displayCategories": [
            "OTHER"
          ],
          "capabilities": [
            {
              "interface": "Alexa.RemoteVideoPlayer",
              "type": "AlexaInterface",
              "version": "1.0"
            },
            {
              "interface": "Alexa.ChannelController",
              "type": "AlexaInterface",
              "version": "3"
            },
            {
              "interface": "Alexa.PlaybackController",
              "type": "AlexaInterface",
              "version": "3",
              "supportedOperations": ["Play", "Pause", "Stop"]
            },
            {
              "interface": "Alexa.VideoRecorder",
              "type": "AlexaInterface",
              "version": "1.0"
            },
            {
              "interface": "Alexa.Launcher",
              "type": "AlexaInterface",
              "version": "1.0"
            }
          ],
          "connections": [
          ],
          "cookie": {
          }
        }
      ]
    }
  }
}

エンターテイメントデバイス向けDiscover.Responseの例

{
  "event":{
    "header":{
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "<メッセージID>"
    },
    "payload":{
      "endpoints":[
        {
          "endpointId": "<エンドポイントの一意のID>",
          "manufacturerName": "<エンドポイントのメーカー名>",
          "description": "サンプルメーカーのスマートスピーカー",
          "friendlyName": "リビングルームの音響システム",
          "additionalAttributes":  {
            "manufacturer" : "サンプルメーカー",
            "model" : "サンプルモデル",
            "serialNumber": "<デバイスのシリアル番号>",
            "firmwareVersion" : "<デバイスのファームウェアバージョン>",
            "softwareVersion": "<デバイスのソフトウェアバージョン>",
            "customIdentifier": "<デバイスのカスタム識別子>"
          },
          "displayCategories": [
            "SPEAKER"
          ],
          "capabilities":[
            {
              "type":"AlexaInterface",
              "interface":"Alexa.Speaker",
              "version":"3",
              "properties":{
                "supported":[
                  {
                    "name":"volume"
                  },
                  {
                    "name":"muted"
                  }
                ]
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.EndpointHealth",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "connectivity"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            }
          ],
          "connections": [
          ],
          "cookie": {
          }
        }
      ]
    }
  }
}

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

Discoverディレクティブを正しく処理できなかった場合は、Alexa.ErrorResponseイベントを使用して応答します。次のエラータイプのいずれかを適宜使用します。 BRIDGE_UNREACHABLEEXPIRED_AUTHORIZATION_CREDENTIALINSUFFICIENT_PERMISSIONSINTERNAL_ERRORINVALID_AUTHORIZATION_CREDENTIAL

AddOrUpdateReportイベント

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

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

フィールド 説明 タイプ 必須
endpoints ユーザーのアカウントに関連付けられているデバイスと、それに対してスキルがサポートする機能です。ユーザーのアカウントに関連付けられたデバイスがない場合、このプロパティには空の配列が返されます。返すことができるエンドポイントの最大数は300です。 endpointオブジェクトの配列
scope Alexaに対してユーザーを識別するベアラートークンを含むオブジェクトです。 scopeオブジェクト

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": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "<エンドポイントの一意のID>",
          "manufacturerName": "サンプルメーカー",
          "description": "サンプルメーカーのスマート照明",
          "friendlyName": "キッチンの照明",
          "additionalAttributes":  {
            "manufacturer" : "サンプルメーカー",
            "model" : "サンプルモデル",
            "serialNumber": "<デバイスのシリアル番号>",
            "firmwareVersion" : "<デバイスのファームウェアバージョン>",
            "softwareVersion": "<デバイスのソフトウェアバージョン>",
            "customIdentifier": "<デバイスのカスタム識別子>"
          },
          "displayCategories": [
            "LIGHT"
          ],
          "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": [
          ],
          "cookie": {
          }
        }
      ],
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-Amazon"
      }
    }
  }
}

DeleteReportイベント

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

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

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

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": "<メッセージID>",
        "payloadVersion": "3"
    },
    "payload": {
      "endpoints": [
          {
              "endpointId": "<エンドポイントID 1>"
          },
          {
              "endpointId": "<エンドポイントID 2>"
          }
      ],
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      }
    }
  }
}

表示カテゴリー

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

説明 説明
ACTIVITY_TRIGGER 特定の順序で状態が変化する必要がある場合の、特定の状態にセットされるデバイスの組み合わせを表します。たとえば、「Netflixを見る」シーンでは、TVの電源をオンにして、入力をHDMI1にセットする必要があります。 シーンに適用します。
CAMERA ビデオまたは写真機能を持つメディアデバイスです。
CONTACT_SENSOR 2面間の接点で発生した変化を検出してレポートするエンドポイントです。
DOOR ドアです。
DOORBELL インターホンです。
LIGHT 光源または照明器具です。
MICROWAVE 電子レンジです。
MOTION_SENSOR ある領域で発生した動きを検出してレポートするエンドポイントです。
OTHER これ以外のカテゴリーのいずれにも当てはまらないエンドポイントです。
SCENE_TRIGGER 状態変化の順序が重要ではない場合の、特定の状態にセットされるデバイスの組み合わせを表します。たとえば、就寝シーンには照明を消すこととサーモスタットの温度を下げることが含まれますが、この動作の順序は重要ではありません。 シーンに適用します。
SECURITY_PANEL セキュリティパネルです。
SMARTLOCK ロックをかけるエンドポイントです。
SMARTPLUG 既存の電源コンセントに差し込むモジュールです。このモジュールにデバイスが接続されます。たとえば、ユーザーはスマートプラグを電源コンセントに差し込み、照明をスマートプラグに接続することができます。 スマートプラグでさまざまなデバイスを制御できます。
SPEAKER スピーカーまたはスピーカーシステムです。
SWITCH 電気システムに直接配線されたスイッチです。 スイッチでさまざまなデバイスを制御できます。
TEMPERATURE_SENSOR 温度をレポートしますが、その制御は行わないエンドポイントです。 エンドポイントの温度データは、Alexaアプリでは表示されません。
THERMOSTAT 温度、直接温度制御が可能なスタンドアロンのエアコン、ヒーターを制御するエンドポイントです。
TV テレビです。