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



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

通常、スキルではLambda関数から同期的にAlexaに応答します。しかし、場合によっては、非同期に応答する必要があります。このとき、デバイス制御クラウドからAlexaイベントゲートウェイに応答イベントを送信します。同期、非同期、遅延応答の違いについては、Alexa.Responseインターフェースを参照してください。

このドキュメントでは、Alexaイベントゲートウェイへのメッセージに含める内容と送信先について説明します。

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

Alexaイベントゲートウェイにメッセージを送信するときは、スマートホームスキルのリージョンと一致するイベントエンドポイントに送信します。以下は、エンドポイントとその地域のリストです。

  • 北米:https://api.amazonalexa.com/v3/events
  • ヨーロッパ:https://api.eu.amazonalexa.com/v3/events
  • 極東:https://api.fe.amazonalexa.com/v3/events

以下の要件を満たす必要があります。

  • スキルが権限を必要とする地域ごとにLambdaを指定します。開発者コンソールのスキルのビルドページで地域を選択して、Lambdaを有効にします。選択した地域ごとにARNを指定します。
  • 地域ごとにユーザー認証情報を取得し保存します。つまり、地域固有のLambda関数に対するAcceptGrantリクエストを受信した場合、同じLambdaがアクセスできるようにその認証情報を保存します。
  • Lambda関数と同じ地域のエンドポイントと、その地域のユーザーに代わって通信します。

たとえば、米国と英国で変更レポートイベントを送信するスキルを提供する場合、北米とヨーロッパの両方にLambdaを設定する必要があります。米国のユーザーに対するAcceptGrantリクエストは、スキルの北米のLambdaに送信されます。LWAを使った認可フローを完了してそのユーザーのトークンを保存し、スキルの北米のLambdaからエンドポイントにアクセスできるようにします。そのユーザーのイベントをhttps://api.amazonalexa.com/v3/eventsに送信します。英国のユーザーの場合、AcceptGrantをヨーロッパ向けに設定されたLambdaに送信してトークンを保存し、ヨーロッパのエンドポイントにイベントを送信します。

また、ユーザーが地域間を移動する場合、ユーザーはスキルの再有効化と再リンクを行い、ユーザー情報の保存先を変更する必要があります。

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

メッセージコンテンツ

非同期メッセージをAlexaに通信するには、HTTP POSTメッセージをAlexaイベントゲートウェイに送信します。Alexaイベントゲートウェイにメッセージを送信するときは、次を含めます。

  • ベアラートークンを含む認可ヘッダー。ベアラートークンはメッセージのscopeプロパティにも含まれます。
  • コンテンツタイプを含むContent-Typeヘッダー。コンテンツタイプにはJSONを指定します。
  • JSON形式のメッセージ本文。

メッセージの本文は、検出応答ディレクティブの応答変更レポート、その他のメッセージなどのタイプによって異なります。

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

POST /v3/events HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer access-token-from-Amazon
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": "access-token-from-Amazon"
       },
       "endpointId" :  "endpoint-id"
    },
    "payload": {
    }
  }
}

イベントゲートウェイの成功コード

次の表は、Alexaイベントゲートウェイが返す成功ステータスコードの一覧です。

HTTP応答のステータスコード 説明
202 Accepted リクエストは認可され、メッセージは構文的に有効なイベントでした。イベントは受け付けられ、論理的な検証と処理に進みます。

イベントゲートウェイのエラーコード

Alexaイベントゲートウェイからエラーコードを受け取ったら、ペイロードから codedescriptionフィールドを取得して、エラーに関する詳細情報を取得します。codeフィールドはログ記録にのみ使用します。codeフィールドをプログラムのロジックに組み込まないでください。

AlexaイベントゲートウェイからのHTTP 400エラーの例を次に示します。

HTTP/1.1 400 Bad Request
Date: Wed, 07 Mar 2018 20:25:31 GMT
Connection: close

{
  "header": {
    "namespace": "System",
    "name": "Exception",
    "messageId": "90c3fc62-4b2d-460c-9c8b-77251f1698a0"
  },
  "payload": {
    "code": "INVALID_REQUEST_EXCEPTION",
    "description": "リクエストの形式が正しくありません"
  }
}

次の表は、Alexaイベントゲートウェイが返すエラーステータスコードの一覧です。

HTTP応答のステータスコード ペイロードのエラーコード 説明と解決策
400 Bad Request INVALID_REQUEST_EXCEPTION メッセージが無効です。原因としては、フィールドがない、値が正しくない、正しいJSON形式ではないことが考えられます。ドキュメントと照合して、メッセージにすべての必須フィールドが含まれていることを確認します。
401 Unauthorized INVALID_ACCESS_TOKEN_EXCEPTION 有効期限が切れているか、形式が正しくないため、アクセストークンが無効です。トークンを更新して、リクエストを再試行してください。ユーザーがスキルを無効にすると、アクセストークンも無効になります。つまり、ユーザーが認可を取り消したため、これらについての変更レポートの送信を停止できるということです。
403 Forbidden SKILL_NEVER_ENABLED_EXCEPTION イベントを正しい地域のエンドポイントに送信していることを確認してください。たとえば、北米のイベントは北米のエンドポイントに送信する必要があります。
403 Forbidden INSUFFICIENT_PERMISSION_EXCEPTION トークンに必要な権限がありません。スキルにAlexaイベントを送信する権限があることを確認してください。非同期メッセージ認証のステップを参照してください。
404 Not Found SKILL_NOT_FOUND_EXCEPTION このトークンに関連付けられたスキルIDが見つかりませんでした。このエラーは、スキルが認定中などの異なるステージにあるときにユーザーのアクセストークンが生成された場合に発生します。このユーザーでスキルの無効化と有効化を行ってみてください。
413 Payload Too Large REQUEST_ENTITY_TOO_LARGE_EXCEPTION イベントペイロードが大きすぎます。1回のリクエストで許容されるエンドポイントの最大数は300です。より小さいペイロードでメッセージを送信してください。
429 Too Many Requests THROTTLING_EXCEPTION リクエスト数が多すぎます。メッセージを最大3回再送します。再送の間隔は、1秒以上空けます。
500 Internal Server Error INTERNAL_SERVICE_EXCEPTION Alexaでエラーが発生したため、メッセージを処理できませんでした。メッセージを最大3回再送します。再送の間隔は、1秒以上空けます。問題が解消されない場合、Amazonサポートに問い合わせてください。
503 Service Unavailable SERVICE_UNAVAILABLE_EXCEPTION Alexaがメッセージを受け付けられませんでした。メッセージを最大3回再送できます。再送の間隔は、1秒以上空けます。問題が解決しない場合は、Alexa開発者向け問い合わせ窓口にお問い合わせください。

テストツール

Alexaスマートホームスキルを開発する際に、状態やイベントのテストやデバッグを行うさまざまなツールが用意されています。詳細については、スマートホームスキルのデバッグを参照してください。

メッセージをテストする

Alexaイベントゲートウェイに送信されるイベントによってAlexaアプリでの表示に影響を与えるため、Alexaに送信するイベントの形式が正しいこと、正しい認証情報が含まれていることを確認してください。AlexaスマートホームGitHubリポジトリで提供されているリソースを使用して、単体テストとテストスクリプトを作成し、送信する前にメッセージを検証してください。