プロアクティブにエンドポイントを管理するには



プロアクティブにエンドポイントを管理するには

プロアクティブなエンドポイント管理とは、ユーザーがサービスを利用しているアカウントに変更を加えたときに、スキルに関連付けられたエンドポイントの追加、更新、削除をAlexaに通知できるということです。

はじめに

プロアクティブなエンドポイント管理とは、ユーザーがアカウントのデバイスを追加、更新、削除したときに、Alexaがそのエンドポイントの関連付け、更新、または関連付けの解除を行えるように、メッセージをプロアクティブに送信することです。これによって、ユーザーは検出ステップをスキップすることができ、デバイスが自動的にAlexaアプリに表示されます。プロアクティブな検出を機能させるには、ユーザーがスマートホームスキルを有効にし、アカウントをシステムにリンクする必要があります。

以前は、ユーザーが新しいエンドポイントを追加したときや既存のエンドポイントを更新した場合(新しいデバイスの追加やデバイスアカウントのシーンの名前変更など)、Alexaにデバイスの検出やAlexaアプリの使用を指示する必要がありました。その後、Alexaはユーザーによって有効にされているすべてのスマートホームスキルに検出リクエストを送信していました。スキルは、ユーザーのアカウントに関連付けられているエンドポイントを記述した応答を送信していました。Alexaが有効にされているエンドポイントを削除する場合も同様に、ユーザーはデバイスを管理するアカウントとAlexaアプリの2か所でエンドポイントを削除する必要がありました。

デバイスをプロアクティブに追加または更新するには、更新されたエンドポイントまたはユーザーに関連付けられているすべてのエンドポイントに関する詳細を含むメッセージを送信します。これは検出応答に似ています。メッセージはAlexaイベントゲートウェイに送信されます。

デバイスを削除するには、エンドポイントIDを含むメッセージをイベントゲートウェイに送信します。つまり、ユーザーはAlexaアプリからデバイスを削除する必要がありません。

前提条件

プロアクティブなエンドポイント管理を有効にするには、Alexaイベントを送信できる既存のスマートホームスキルがあり、ユーザーの認証トークンが正常に取得され保存されている必要があります。詳細については、以下のトピックを参照してください。

新しいイベントを送信するコードを追加する

メッセージを作成し、以下を実行するコードを追加する必要があります。

新規または更新されたデバイスをAlexaに通知する

ユーザーが新しいデバイスを追加したとき、または既存のものを更新したときは、AddOrUpdateReport イベントを送信します。形式はdiscovery responseと同じです。このメッセージは、エンドポイントでサポートされる機能とプロパティを説明します。ただし、AddOrUpdateReportイベントと検出応答の間には明確な違いがあります。

  • メッセージのnameAddOrUpdateReportにセットされます。
  • メッセージにはscopeが含まれます。scopeにはAlexaに対してユーザーを識別するベアラートークン、同じベアラートークンを含むHTTP認可ヘッダーが含まれます
  • メッセージはAlexaイベントゲートウェイに送信されます。
  • このメッセージにはユーザーアカウントに関連付けられたすべてのエンドポイントか、新規または更新されたエンドポイントのみを含めることができます。スキルの実装内容に応じて選択できます。

例: AddOrUpdateReport

以下は照明についての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": "appliance-001",
        "friendlyName": "リビングの照明",
        "description": "サンプルメーカーのスマート照明",
        "manufacturerName": "サンプルメーカー",
        "displayCategories": [
          "LIGHT"
        ],
        "cookie": {
          "extraDetail1": "optionalDetailForSkillToReferenceThisDevice",
          "extraDetail2": "複数のエントリーがある場合があります",
          "extraDetail3": "参照目的で使用します",
          "extraDetail4": "デバイスの状態を管理する目的では使用しないでください。"
        },
        "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
            }
          }
        ]
      }],
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-Amazon"
      }
    }
  }
}

削除されたデバイスをAlexaに通知する

ユーザーがアカウントからデバイスを削除するときは、endpointIdsのマップを含むDeleteReportイベントを送信してユーザーのアカウントからデバイスを削除します。

削除レポート:

  • scopeが含まれます。scopeにはAlexaに対してユーザーを識別するベアラートークン、および同じベアラートークンを含むHTTP認可トークンが含まれます。
  • Alexaイベントゲ-トウェイに送信されます。
  • 削除するエンドポイントを識別するエンドポイントIDのリストを含むペイロードがあります。

例: DeleteReport


POST /v3/events HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer access-token-from-Amazon
Content-Type: application/json

{
  "event": {
    "header": {
      "messageId": "0a29824b-9299-4d55-b0c3-1d96ecfae81e",
      "name": "DeleteReport",
      "namespace": "Alexa.Discovery",
      "payloadVersion": "3"
    },
    "payload": {
      "endpoints": [{
          "endpointId": "videoDevice-001"
        },
        {
          "endpointId": "speaker-001"
        }
      ],
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-Amazon"
      }
    }
  }
}

必要に応じてエラーを処理する

AddOrUpdateReportまたはDeleteReportイベントが正常に受け付けられると、応答でHTTP 202を受け取ります。その他の場合は、イベントゲートウェイにイベントを送信するで説明されているエラーのいずれかを受け取ります。手順に従って問題を診断および修正します。

トピック 説明
Alexa.Discovery スマートホームスキルの検出機能を記述します。
Alexa.Authorization Alexaユーザーのセキュリティトークンを取得する機能を記述します。
イベントゲートウェイにイベントを送信する Alexaイベントゲートウェイにプロアクティブまたは非同期のメッセージを送信する方法を記述します。