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



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

Alexaに応答する場合、Alexaイベントゲートウェイに応答することができます。このドキュメントでは、メッセージのコンテンツと送信先について説明します。

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

ChangeReport、非同期の応答、プロアクティブな検出イベントを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イベントゲートウェイにメッセージを送信するプロセスを示しています。

メッセージコンテンツ

スキルの非同期の応答と変更レポートイベントは、HTTP POSTメッセージを適切なAlexaイベントゲートウェイに送信することでAlexaに伝えます。エンドポイントのリストは、Alexaイベントのエンドポイントを参照してください。

メッセージには以下が含まれます。

  • ベアラートークンを含む認可ヘッダー。ベアラートークンはメッセージのscopeプロパティにも含まれます。
  • コンテンツタイプを含むContent-Typeヘッダー。コンテンツタイプにはJSONを指定します。
  • JSON形式のメッセージ本文。本文には、メッセージの目的に応じて以下のいずれかを含めることができます。

  • 以下の2つの識別情報を含むendpointオブジェクト。

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

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イベントゲートウェイにメッセージを送信すると、メッセージの処理が受け付けられたことを表す202 Accepted応答か、エラーのいずれかを受信します。受信する可能性のある応答、注釈、エラーの解決方法を以下に示します。

成功

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

エラー

エラー応答を受信したら、ペイロードのcodeフィールドを取得して、エラーの原因を判断する必要があります。ペイロードにはdescriptionフィールドも含まれますが、このフィールドはログ目的のみに使用し、ビジネスロジックには使用しないでください。以下の表は、受信する可能性のあるHTTP応答のタイプ、関連するエラーコード、エラー解決のヒントを表しています。

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

以下は、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イベントゲートウェイに送信されるイベントによってAlexaアプリでの表示に影響を与えるため、Alexaに送信するイベントの形式が正しいこと、正しい認証情報が含まれていることを確認してください。メッセージの形式が正しくない場合、エンドポイントで拒否される可能性があります。AlexaスマートホームGitHubリポジトリで提供されているリソースを使用して、単体テストとテストスクリプトを作成し、送信する前にメッセージを検証してください。

フェーズのテストとツール

Alexaはスキルのクエリー(ReportStateディレクティブの送信)とプロアクティブな状態更新(スキルからのChangeReportイベント)を組み合わせて、ユーザーがAlexaアプリで正確なデバイス情報を受け取れるようにしています。ChangeReportデータが正確であるという高い信頼度が得られるまでは、ReportStateChangeReportの両方の情報を参照することができます。

ChangeReportを送信している開発者向けのツールが提供されており、プロアクティブな状態更新が正確に行われるかどうかに関わる問題を特定できます。

状態レポートのテストツールへのアクセスをリクエストするには、次の手順に従います。

アクセスが可能になった時点、または追加情報が必要な場合に、Amazonが連絡します。

テストツールの詳細については、状態レポートのテストツールを使用する方法を参照してください。

イベントの応答性

ディレクティブを受信したら、同期的な応答を送信するか、ディレクティブを受信したことを表すDeferredResponseを送信して、後から非同期のイベントをAlexaエンドポイントに送信します。どちらの場合も、Alexaがタイムアウトするまでの時間は8秒です。

8秒のタイムアウトの例外は、以下のとおりです。

機能インターフェース 説明
LockController 低速ロックに設定し、想定されるResponseの遅延の秒数をDeferredResponseestimatedDeferralInSecondsに指定します。