Alexa.Discoveryインターフェース



Alexa.Discoveryインターフェース

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

制限

スキルでは、ユーザーごとに次の制限に準拠する必要があります。

  • サポートできるエンドポイントは最大300個です。
  • エンドポイントごとにサポートできる機能は最大100個です。
  • AddOrUpdateReportイベントのペイロードは最大256キロバイト(KB)です。

ディレクティブ

Discoverディレクティブ

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

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

Alexa, discover my smart home devices.

Alexa, finde meine smarten geräte.

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

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

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

Discoverディレクティブの例

次の例は、Alexaがスキルに送信する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 ユーザーのアカウントに関連付けられているデバイスと、それに対してスキルがサポートする機能です。ユーザーのアカウントに関連付けられたデバイスがない場合、このプロパティには空の配列が返されます。endpointsフィールドにはサイズ制限が適用されます。 endpointオブジェクトの配列

検出応答の例

以下は、Alexa.PowerControllerインターフェースとAlexa.BrightnessControllerインターフェースをサポートする1つの照明に対する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": ["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",
              "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ディレクティブのエラー処理

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

AddOrUpdateReportイベント

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

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

フィールド 説明 必須
endpoints ユーザーのアカウントに関連付けられているデバイスと、それに対してスキルがサポートする機能です。ユーザーのアカウントに関連付けられたデバイスがない場合、このプロパティには空の配列が返されます。endpointsフィールドにはサイズ制限が適用されます。 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": "<メッセージID>"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "<エンドポイントの一意のID>",
          "manufacturerName": "Sample Manufacturer",
          "description": "サンプルメーカーのスマート照明",
          "friendlyName": "キッチンの照明",
          "additionalAttributes":  {
            "manufacturer" : "Sample 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"
      }
    }
  }
}

DeleteReportイベント

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

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を観る」というシーンの場合、まずテレビの電源をオンにしてから、入力をHDMI1に設定します。
AIR_FRESHENER 室内空間で心地よい香りを放出し、不快な臭いを消臭するデバイスです。
AIR_PURIFIER 室内空間の空気の質を向上させるデバイスです。
AUTO_ACCESSORY 車載カメラなど、自動車内のスマートデバイスです。
CAMERA ビデオまたは写真機能を持つセキュリティデバイスです。
CHRISTMAS_TREE クリスマスの装飾です。多くの場合、ライトが付いています。
COFFEE_MAKER コーヒーを淹れるデバイスです。
COMPUTER デスクトップコンピューターなど、モバイル以外のコンピューターです。
CONTACT_SENSOR 2面間の接点で発生した変化を検出してレポートするエンドポイントです。
DOOR ドアです。
DOORBELL インターホンです。
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 掃除機です。
WEARABLE Apple Watch、Fitbit、Samsung Gearなど、ネットワークに接続されたウェアラブルデバイスです。