Alexa.Responseインターフェース3

Alexa.Responseインターフェース3

Alexaディレクティブが正常に処理されると、応答イベントを使用して応答が行われます。最も一般的な応答イベントはAlexa.Responseです。一部のディレクティブには特定の応答イベントを使用します。たとえば、Alexa.ReportStateディレクティブにはAlexa.StateReport応答が必要ですが、Alexa.PowerControllerディレクティブはAlexa.Responseを使用します。正しい応答イベントを選択して使用するには、該当するインターフェースとディレクティブに関するトピックを確認してください。

ディレクティブを正しく処理できなかった場合は、Alexa.ErrorResponseイベントを使用して応答します。

メッセージプロパティの定義については、Alexaインターフェースのメッセージとプロパティを参照してください。

応答の種類

Alexaインターフェースは、次の3種類の応答をサポートします。

  • 同期 - Lambda関数からディレクティブに応答します。
  • 非同期 - デバイス制御クラウドからAlexaイベントゲートウェイに応答イベントを送信します。
  • 遅延 - ロックなど、物理的な変更に8秒以上かかるデバイスの場合は、通常の同期／非同期応答を送信する前に遅延応答を送信してください。

同期応答

同期応答には以下の情報を指定します。

  • endpointオブジェクトで応答のエンドポイントを識別します。
  • ディレクティブのリクエストの値を設定したcorrelationTokenを含めます。
  • payloadオブジェクトに応答プロパティを含めます。
  • 応答イベントのcontextオブジェクトに、エンドポイントのプロパティのうち変更があったすべてのプロパティの値と変更時刻を含めます。変更のないプロパティの値も含めて、Alexaにエンドポイントの現在の状態をすべて伝えることもできます。

同期応答の例

以下は、標準的な同期応答の例です。この例では、エンドポイントは Alexa.PowerControllerインターフェースをサポートし、TurnOnディレクティブに応答します。

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

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

同期応答プロパティ

プロパティ 説明 型 必須

event

ヘッダーとエンドポイントの情報を定義します。

Eventオブジェクト

◯

event.header

応答とインターフェースを指定します。
Alexaが応答をディレクティブと関連付けることができるようにするには、header.correlationTokenをディレクティブリクエストのheader.correlationToken値に設定する必要があります。

Headerオブジェクト

◯

event.endpointId

エンドポイントを指定します。

文字列

◯

event.payload

応答に必要なプロパティを指定します。
ペイロードは、インターフェースディレクティブと応答によって異なります。正しい応答プロパティについては、該当するインターフェースに関するトピックを確認してください。応答にプロパティが含まれない場合は、payloadを空のオブジェクトに設定します。

オブジェクト

◯

context

変更のないプロパティも含め、取得可能なすべてのプロパティの現在の状態を返す場合に指定します。

Contextオブジェクト

×

非同期応答

非同期で応答する場合、AlexaイベントゲートウェイにHTTPリクエストを送信し、リクエスト本文に応答イベントを含めます。応答には、Alexaに対してスキルのユーザーを認証するアクセストークンを含める必要があります。

非同期応答には以下の情報を指定します。

  • endpointオブジェクトにレポートのエンドポイントを指定します。
  • correlationTokenにディレクティブリクエストの値を設定して含めます。
  • endpoint.scopeオブジェクトにアクセストークンを指定して含めます。
  • payloadオブジェクトに応答プロパティを含めます。
  • 応答イベントのcontextオブジェクトに、エンドポイントのプロパティのうち変更があったすべてのプロパティの値と変更時刻を含めます。変更のないプロパティの値も含めて、Alexaにエンドポイントの現在の状態をすべて伝えることもできます。

非同期応答の例

以下は、非同期応答の例です。この例では、エンドポイントはAlexa.ColorTemperatureControllerインターフェースをサポートします。

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

POST /v3/events HTTP/1.1
Host: api-amazonalexa.com
Authorization: Bearer access-token-from-Amazon
Content-Type: application/json
{
  "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": "2017-02-03T08:00:00.10Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

非同期応答のプロパティ

プロパティ 説明 型 必須

event

ヘッダーとエンドポイントの情報を定義します。

Eventオブジェクト

◯

event.header

応答とインターフェースを指定します。
Alexaが応答をディレクティブと関連付けることができるようにするには、header.correlationTokenをディレクティブリクエストのheader.correlationToken値に設定する必要があります。

Headerオブジェクト

◯

event.endpointId

エンドポイントを指定します。

文字列

◯

event.endpoint.scope

Alexaイベントゲートウェイのアクセストークン詳細については、Alexaイベントゲートウェイへのアクセス権限のリクエストを参照してください。

Scopeオブジェクト

◯

event.payload

応答に必要なプロパティを指定します。
ペイロードは、インターフェースディレクティブと応答によって異なります。正しい応答プロパティについては、使用するインターフェースに関するトピックを確認してください。応答にプロパティが含まれない場合は、payloadを空のオブジェクトに設定します。

オブジェクト

◯

context

変更のないプロパティも含め、取得可能なすべてのプロパティの現在の状態を返す場合に指定します。

Contextオブジェクト

×

非同期のAlexa.Responseをゲートウェイに送信すると、Alexaは成功か失敗かを示すHTTPステータスコードを返します。

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

遅延応答

8秒待っても応答がない場合、Alexaはタイムアウトします。タイムアウトまでの時間がもっと短いインターフェースもあります。物理的な変更があるデバイスなど、一部のインターフェースではこれより長い場合もあります。応答に8秒以上かかる場合は、まず同期のAlexa.DeferredResponseイベントを送信し、その後、同期または非同期のAlexa.Responseイベントを送信します。

Alexaは、以下のインターフェースでAlexa.DeferredResponseをサポートしています。

Alexa.DeferredResponseは常に同期的に送信されるため、endpoint.scopeは含めないでください。

遅延応答の例

以下は、Alexa.Responseを7秒以内に推定する遅延応答の例です。

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

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "DeferredResponse",
      "messageId": "一意の識別子、バージョン4 UUIDが望ましい",
      "correlationToken": "リクエストに一致するopaque相関トークン",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "エンドポイントID"
    },
    "payload": {
      "estimatedDeferralInSeconds": 7
    }
  }
}

遅延応答のプロパティ

プロパティ 説明 型 必須

event

ヘッダーとエンドポイントの情報を定義します。

Eventオブジェクト

◯

event.header

応答とインターフェースを指定します。
Alexaが応答をディレクティブと関連付けることができるようにするには、header.correlationTokenをディレクティブリクエストのheader.correlationToken値に設定する必要があります。

Headerオブジェクト

◯

event.endpointId

エンドポイントを指定します。

文字列

◯

event.payload

遅延応答のプロパティを指定します。

オブジェクト

◯

event.payload.estimatedDeferralInSeconds

2回目の応答を送信するまでのおおよその時間（秒単位）。

整数

×

Alexaエラー

応答を送信した後、Alexaが応答待ちでタイムアウトしたり、応答ペイロードの処理中にエラーが発生したりすることがあります。これらのエラーが発生すると、ユーザーのリクエストを完了することができません。

Alexaエラーには次の例外があります。

  • SKILL_RESPONSE_TIMEOUT_EXCEPTION – スキルへのAlexaリクエストがタイムアウトした場合にスローされた例外です。
  • INVALID_SKILL_RESPONSE_EXCEPTION – Alexaがスキルから無効な応答を受け取った場合にスローされる例外です。

Alexaエラーは、Alexa開発者コンソールのレポート>機能ディレクティブページで確認できます。詳細については、エラーを参照してください。

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

最終更新日: 2025 年 09 月 01 日