イベントの送信

イベントの送信

ユーザーのアクセストークンを取得して保存したら、前に受け取ったディレクティブに対する非同期応答やプロアクティブなイベントを送信することができます。これらのイベントは、適切なリージョンのAlexaイベントゲートウェイエンドポイントにHTTPメッセージとして送信します。

非同期イベントのタイプ

非同期応答とイベントの構造は同期メッセージの場合と同じですが、イベントの送信先はAlexaイベントゲートウェイです。

以下のイベントをイベントゲートウェイに送信します。

ゲートウェイエンドポイント

Alexaイベントゲートウェイにメッセージを送信するときは、スマートホームスキルやビデオスキルのリージョンと一致するイベントエンドポイントに送信します。以下のリストは、Alexaのリージョンと、それぞれに関連付けられているエンドポイントを示しています。

  • 北米：https://api.amazonalexa.com/v3/events
  • ヨーロッパ、インド：https://api.eu.amazonalexa.com/v3/events
  • 極東、オーストラリア：https://api.fe.amazonalexa.com/v3/events

たとえば、変更レポートを送信するスキルを米国と英国で提供する場合は、北米とヨーロッパのそれぞれのリージョンにAmazonウェブサービス（AWS）のLambda関数をデプロイする必要があります。米国のユーザーの場合は、Alexaは北米用に設定されたLambda関数にディレクティブを送信します。そのユーザーのアクセストークンを保存して、スキルの北米用Lambda関数からアクセスできるようにします。このユーザーの場合、イベントは北米のエンドポイントに送信します。英国のユーザーの場合は、Alexaはヨーロッパ用に設定されたLambda関数にディレクティブを送信し、トークンを保存して、ヨーロッパのエンドポイントにイベントを送信します。AWS Lambdaエンドポイントの詳細については、Lambda関数を複数のリージョンにデプロイするを参照してください。

また、ユーザーが地理的リージョン間を移動した場合、スキルの再有効化と再リンクを行う必要があります。これにより、関連付けられたユーザー情報の保存場所をスキルが変更できます。

非同期イベントの定義

非同期応答やイベントをAlexaに伝達するには、AlexaイベントゲートウェイにHTTP POSTメッセージを送信します。

APIエンドポイント

エンドポイントは、ユーザーがいるリージョンのゲートウェイエンドポイントに設定します。

認証

Alexaゲートウェイでスキルを認証するには、HTTPヘッダーでベアラートークン認証を使用します。このとき、保存されているユーザーのアクセストークンを含めます。アクセストークンは有効期限が切れる前に更新してください。

リクエスト

リクエストヘッダーとメッセージの本文にアクセストークンを含めます。

リクエストヘッダーの例

クリップボードにコピーされました。

POST /v3/events HTTP/1.1
Host: {gateway-endpoint}
Authorization: Bearer {access-token-from-Amazon}
Content-Type: application/json

リクエストヘッダーのパラメーター

パラメーター 説明 型 必須

gateway-endpoint

ユーザーがいるリージョンのゲートウェイエンドポイントに設定します。

文字列

◯

access-token-from-Amazon

ユーザーのアクセストークンです。
ユーザーのアクセストークンを取得するプロセスの詳細については、Alexaイベントゲートウェイへのアクセス権限のリクエストを参照してください。

文字列

◯

リクエスト本文の例

以下は、SetColorTemperatureディレクティブに対する非同期応答の例です。

クリップボードにコピーされました。

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "Response",
            "messageId": "一意の識別子、バージョン4 UUIDが望ましい",
            "correlationToken": "リクエストに一致するopaque相関トークン",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-Amazon"
            },
            "endpointId": "エンドポイントID"
        },
        "payload": {}
    },
    "context": {
        "properties": [{
            "namespace": "Alexa.ColorTemperatureController",
            "name": "colorTemperatureInKelvin",
            "value": 5500,
            "timeOfSample": "2022-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
        }]
    }
}

リクエスト本文のパラメーター

リクエスト本文の定義については、個々のイベントタイプのドキュメントを参照してください。endpointオブジェクトにはscopeプロパティが含まれ、そのtypeはBearerToken、tokenはLWAから受け取ったaccess_tokenに設定されています。

応答

成功すると、Alexaは、イベントが受け入れられて詳しい論理検証と処理が行われることを示す202 Acceptedを送信します。リクエストが受け付けられない場合、Alexaは適切なHTTPステータスコードを送信します。たとえば、期限切れのトークンを含むリクエストを送信すると、AlexaからHTTP 401 Unauthorized応答が返されます。

応答本文のパラメーター

この応答には本文はありません。

HTTPステータスコード

次の表は、スキルがAlexaイベントゲートウェイから受け取る可能性のあるHTTPステータスコードの一覧です。エラーを受け取った場合は、payloadオブジェクトにcodeフィールドとdescriptionフィールドが含まれます。これらのフィールドはログ記録の目的でのみ使用してください。

ステータス ペイロードのコード 説明

202 Accepted

—

リクエストは認可され、メッセージは構文的に有効なイベントでした。ゲートウェイはイベントを受け付け、論理的な検証と処理に進みます。

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イベントを送信する権限があることを確認してください。詳細については、Alexaイベントゲートウェイへのアクセス権限のリクエストを参照してください。

404 Not Found

ACCOUNT_NOT_FOUND_EXCEPTION

指定されたIDに関連付けられたアカウントレコードが存在しないか、期限が切れています。このエラーは、イベントの送信が遅すぎた場合や、無効なIDが指定された場合に発生する可能性があります。指定されたIDと認可コードが正しいことを確認してください。

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秒以上空けてください。問題が解消されない場合、Alexa開発者向け問い合わせ窓口にお問い合わせください。

503 Service Unavailable

SERVICE_UNAVAILABLE_EXCEPTION

Alexaがメッセージを受け取れませんでした。メッセージを再送してください。ただし、再送は最大3回までで、再送の間隔は1秒以上空けてください。問題が解消されない場合、Alexa開発者向け問い合わせ窓口にお問い合わせください。

応答本文401 Unauthorizedの例

以下は、エラー応答の例です。

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_ACCESS_TOKEN_EXCEPTION",
      "description": "アクセストークンが無効、有効期限切れ、形式が正しくないのいずれかです。"
  }
}

このページは役に立ちましたか？

最終更新日: 2024 年 12 月 17 日