?
サポート

イベントゲートウェイにイベントを送信する

イベントゲートウェイにイベントを送信する

Alexaに応答するときは、Alexaイベントゲートウェイに応答することもできます。このドキュメントでは、メッセージに何が含まれるか、どこに送信するかについて説明します。

イベントエンドポイント、Lambda関数とユーザーの認可情報

プロアクティブステートイベントまたは非同期イベントをAlexaに送信するときは、スマートホームスキルの地域毎に割り当てられた適切なイベントエンドポイントと通信する必要があります。エンドポイントと、その網羅する地域の一覧を次に示します。

  • North America:https://api.amazonalexa.com/v3/events
  • Europe:https://api.eu.amazonalexa.com/v3/events
  • Far East(日本):https://api.fe.amazonalexa.com/v3/events

以下を実行します。

  • スキルが権限を必要とする各地域にLambdaを提供します。開発者ポータルで、スキルの「コンフィギュレーション(Configuration)」ページにある「地域エンドポイントを提供する(Provide geographical region endpoints)」オプションを使用してこれを有効化します。選択する各地域にARNを提供します。
  • 地域ごとにユーザー認可情報を取得して保存します。つまり、特定リージョン用のLambda関数がAcceptGrantリクエストを受信した場合、そのLambdaが認可情報にアクセスできるように、受け取った認可情報を保存します。
  • その地域のユーザーの認可情報を使い、Lambda関数と同じ地域のエンドポイントにイベントを通知します。

たとえば、米国および英国で変更通知を送信するスキルを提供する場合、LambdaをNorth AmericaとEuropeに対して設定する必要があります。米国のお客様へのAcceptGrantリクエストは、スキルのNorth America Lambdaに送信されます。LWAで認証フローを完了し、そのお客様のトークンを保存して、スキルのNorth America Lambdaがトークンにアクセスできるようにします。そのユーザー持つ機器からのイベントはhttps://api.amazonalexa.com/v3/eventsに送信します。英国のユーザーの場合、AcceptGrantはEurope用に設定されたLambdaに送信されます。イベントはEuropeエンドポイントに送信します。

また、ユーザーが地域を変更する場合、ユーザーはスキルを再有効化し、再度アカウントリンクを行う必要があるでしょう。スキルはこのような状況に適切に対処できる必要があります。

次の図は、ユーザーを認証し、お客様の代わりにメッセージをAlexaイベントゲートウェイに送信するプロセスを示しています。

図

メッセージの内容

非同期応答、変更レポート、状態レポートのイベントをAlexaに送るには、地域毎に適切なAlexaイベントゲートウェイにHTTP POSTメッセージを送信します。エンドポイントのリストについては、 Alexaイベントのエンドポイントを参照してください。

次の内容を含めます。

  • Authorization ヘッダーメッセージは ベアラートークンを持ちます。このトークンはscopeプロパティにも含まれる ベアラートークンと同じです。
  • コンテンツのタイプがJSONであることを示すContent-Typeヘッダー。
  • JSON形式のメッセージ本文。本文には、メッセージの目的に応じてResponseChangeReportStateReportのいずれかを含めることができます。
  • 次の2つの識別情報を含むendpointオブジェクト。
    • デバイスを識別するendpointId。このIDは、デバイス Discovery 応答時に提供したものと同じものである必要があります。
    • イベント通知の認可を受けた特定のユーザーを識別するための ベアラートークン。ユーザーの関連付けを実現し、トークンを取得する一連のプロセスに関する詳細は、Permissionsを設定してAlexaへのユーザー認証を実現するAlexa.Authorizationを参照してください。

メッセージ本体の例は、スマートホームスキルの状態レポートにある、各インターフェースに関するトピックのResponseの例を参照してください。

イベントゲートウェイへのメッセージの例を次に示します。

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

{
  "context": {
    "properties": [
    ]
  },
  "event": {
    "header": {
      "messageId": "abc-123-def-456",
      "correlationToken": "abcdef-123456",
      "namespace": "Alexa",
      "name": "Response",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "Alexa-access-token"
       },
       "endpointId" :  "endpoint-id"
    },
    "payload": {
    }
  }
}

成功の応答とエラー

メッセージをAlexaイベントゲートウェイに送信すると、成功を意味する202 Accepted応答か、エラーのどちらかを受信します。受け取る可能性のある応答と、関連するシナリオの一覧を次の表に示します。

HTTP応答 シナリオ
202 Accepted メッセージは処理可能として受け入れられました。メッセージは受け入れられましたが、中身のフォーマットが正しということが確認されたわけではなく、中身の整合性の確認はこの時点では行われていないことに注意してください。メッセージの整合性を確認するためには Validation Schema を使うことができます
403 Forbidden スキルは無効にされており、該当のユーザーの認可は取り消されました。
401 Unauthorized スキルは有効ですが、トークンの期限が切れています。
400 Bad Request メッセージには、無効なエンドポイントIDや correlation トークンなど、無効な識別情報が含まれています。

イベントの応答性

ディレクティブを受信したときは、同期応答を送信するか、または、ディレクティブを受信したことを示すDeferredResponseを送信し、後でAlexaのエンドポイントに非同期イベントを送信することができます。いずれの場合も、Alexaがタイムアウトする8秒以内に実施する必要があります。

以下は例外として、8秒以上でも実施可能となります。

機能のインターフェース 備考
LockController 低速ロックにし、DeferredResponseestimatedDeferralInSecondsを使用してResponseの時間を長めに設定します。

メッセージのテスト

Alexaイベントゲートウェイに送信されるイベントはAlexaアプリの表示に影響を与えるため、Alexaに送信するイベントの形式が正しく、正確な認証情報が含まれていることを確認してください。メッセージの形式が正しくないと、エンドポイントに拒否されることがあります。Alexa Smart Home GitHubリポジトリで提供されているリソースを使用して、メッセージを送信する前にそれらを検証するユニットテストとテストスクリプトを作成してください。