スキルにメッセージリクエストを送信する

Note: Sign in to the developer console to build or publish your skill.

スキルにメッセージリクエストを送信する

cURLメッセージリクエストのサンプル
受信したメッセージのスキルでの処理
- 必須で行う必要があるスキルサービスからのスキルメッセージAPIに対する確認応答
- 新しいリクエストタイプ

指定されたユーザーのスキルにメッセージリクエストを送信するにはスキルメッセージAPIを使います。

スキルメッセージAPIは非同期です。正常な応答とは、メッセージが受け取られ、スキルに送信されるキューに入ることです。受け取ったメッセージをスキルに配信するためには、スキルのエンドポイントを使用する必要があります。スキルのエンドポイントが使用できない場合、メッセージはexpiresAfterSecondsフィールドに指定された期間、定期的に試行を繰り返します（指定されていない場合、デフォルトの有効期間になります）。正常な配信には、スキルがコンテキストを「継承」し、メッセージを確認しなければなりません。

スキルがオンラインの場合、メッセージは処理と同時に配信されます。メッセージ配信のタイミングや順序は保証されません。呼び出し元はメッセージを受信するスキルの所有者でもあるため、スキルにメッセージが配信されたかどうかの判断も呼び出し元の責任です。配信メカニズムにはビルトインの受信確認機能はありません。複数のリクエストが送信された場合の重複メッセージの処理も呼び出し元の責任です。

メッセージリクエストの形式は以下のとおりです。

cURLメッセージリクエストのサンプル

以下の例は、北米（NA）エンドポイントのAPI_URL値です。

EUエンドポイントを使用する場合は、API_URL=https://api.eu.amazonalexa.com/v1/skillmessages/users/USERIDになります。FEエンドポイントを使用する場合は、API_URL=https://api.fe.amazon.com/v1/skillmessages/users/USERIDになります。

ALEXA_USER_ID='ReplaceWithUserId'
SKILL_MESSAGING_TOKEN='ReplaceWithToken'
MESSAGE='{"data":{ "sampleMessage": "Sample Message"}, "expiresAfterSeconds": 60}'
API_URL=https://api.amazonalexa.com/v1/skillmessages/users/$ALEXA_USER_ID

 curl -v -s -k -X POST \
      -H "Authorization: Bearer $SKILL_MESSAGING_TOKEN" \
      -H "Content-Type: application/json" \
      -d "$MESSAGE" \
      $API_URL

名前	位置	型	必須	説明
`userId`	パス	文字列	必須	スキルユーザーのIDです。このIDは、Alexaが送信するリクエストで提供される`userId`と同じです。指定されたスキルの有効なユーザーでなければなりません。
`skillMessagingToken`	ヘッダー	文字列	必須	認可APIから提供されるトークンです。ベアラータイプのトークンです。例： `Authorization: Bearer Atz\|zzzzbbbccc`
`message`	本文	オブジェクト	必須	スキルに送信するメッセージで、以下のような形式になります。`expiresAfterSeconds`には適切な数値を指定します。`json { data: { }, expiresAfterSeconds: integer }`

Messageオブジェクト

パラメーター	型	説明
data	JSON	必須です。メッセージと一緒に送信するペイロードデータです。データは、JSON形式のキーと値のペアで指定します。キーと値は文字列型にする必要があります。データ全体のサイズは6KB以下です。6KBには、キーと値、それらを囲む引用符、キーと値を区切る「:」、ペア間を区切るカンマ、フィールドを囲む中かっこも含みます。ただし、キー／値ペア間のスペースはペイロードサイズには含まれません。同期メッセージなど、メッセージにペイロードデータがない場合、次のように空のオブジェクトとして渡すことができます。`json "data": {}`
`expiresAfterSeconds`	整数	任意です。メッセージの配信に失敗した場合に再試行のために、メッセージを保持する秒数です。60（1分）以上86400（1日）以下の値を指定できます。デフォルトは3600（1時間）です。この期間中、複数回再試行されます。再試行のロジックは、等比級数的に増加します。最初の再試行が30秒後に行われ、再試行の回数ごとにその間隔が倍になっていきます。再試行はメッセージの最初の配信からの合計経過時間が、`expiresAfterSeconds`に指定された値を超えたときに終了します。スキルにコンテキストを自動的に継承するハンドラーがある場合など、メッセージハンドラーが正しくセットアップされていれば、メッセージの期限切れが問題になることはあまりありません。正しくセットアップが行われていれば、1回ですぐにメッセージを受信できます。この再試行メカニズムは、メッセージの配信中にスキルがダウンした場合のセーフガードとなります。

（スキルメッセージAPIへのリクエストに対する）応答

コード	説明	ヘッダー
202	メッセージは正常に受け取られ、スキルに送信されます。	X-Amzn-RequestID

X-Amzn-RequestIDオブジェクト

名前	型	説明
X-Amzn-RequestID	文字列	リクエストを一意に識別する作成値です。問題が発生する場合、Amazonサポートはこの値をトラブルシューティングに使用します。

エラーコード

コード	エラー	説明
400	不正なリクエスト	データが存在しないか、有効ではありません。
403	許可されないリクエスト	`skillmessagingToken`が有効期限切れか、無効です。
404	見つかりません	`userId`が存在しません。
429	メッセージレートが超過しています	リクエストが、メッセージのレートの最大値を超過しました。
500	内部サービス例外

受信したメッセージのスキルでの処理

スキルでイベントが使えるようにし、スキルに対応するアプリケーションを構成したら、スキルのサービス（AWS Lambdaまたはウェブサービス）で受信したメッセージの処理方法が指定されていることを確認します。

Messaging.MessageReceivedは、スキルが受信する他のリクエストに似たリクエストタイプです。標準のリクエスト形式の詳細については、リクエストの形式を参照してください。

必須で行う必要があるスキルサービスからのスキルメッセージAPIに対する確認応答

セッション外のメッセージの場合、スキルのサービス（AWS Lambdaまたはウェブサービス）はメッセージを受信したという確認応答をスキルメッセージAPIに送信する必要があります。確認応答が返されていない間、APIは有効期間が切れるまでメッセージを送信し続けます。

Node.jsを使用している場合、メッセージを処理した後にcontext.succeed();を呼び出して確認応答を送信します。別の言語の場合、確認応答として空の成功メッセージを送信します。スキルサービスがメッセージの受信後に他のAPI呼び出しを行う際に、これらのAPIリクエストが同期的に戻された後もコンテキストを継承することが重要です。

詳細については、AWS Lambdaのドキュメントに記載されたNode.js ランタイム v0.10.42 のコンテキストメソッドを参照してください。

新しいリクエストタイプ

Messaging.MessageReceivedリクエストタイプはスキルエンドポイントによって処理される必要があります（AWS Lambdaかウェブサービスいずれの場合にも適用）。リクエストはインテントの新しいタイプです。このため、このリクエストタイプでは、スキルにハンドリングメソッドを追加する必要があります。リクエストの形式を参照してください。

リクエスト	MessageRequest
インターフェース	メッセージ
定義	`json "request": { "type": "Messaging.MessageReceived", "requestId":"string", "timestamp":"string", "message": < object > }`
アトリビュート	メッセージ：バックエンドのサードパーティアプリケーションによって提供されるメッセージのブロブです。システムでのメッセージブロブのサイズは最大6KBです。

以下の例にあるMessaging.MessageReceivedリクエストのサンプルでは、permissionsオブジェクトのconsentTokenを使用しています。セッション外のメッセージリクエストでは、ユーザーの同意を含むconsentTokenがスキルに提供されます。Contextオブジェクトを参照してください。

同意トークンの有効期間は60分です。永続性を持たせるべきではありません。同意トークンは、スキルメッセージAPIが新しいセッション内リクエストまたはセッション外リクエストを受信するたびに、自動的に更新されます。

各userIdは、スキルユーザーのスキル有効化の期限が切れるまで有効です。ユーザーがスキルを無効にして再度有効にした場合、userIdは変更されます。そのため、ユーザーが次にスキルを使用するとき、そのユーザーは新しいユーザーとして認識されます。新しいユーザーの場合と同様、セッション外での通知の送信に使用できるよう、スキルセッションの中で与えられたuserIdを記録しておく必要があります。スキルメッセージのエンドポイント（/skillmessages/users/{userId}）を呼び出すのにスキルメッセージAPIが使用された場合、404エラー（userIdが見つかりません）が発生し、そのuserIdはシステムで有効ではなくなります。

リクエスト内のContextオブジェクトのapiEndpoint値

以下の例にあるIntentRequestサンプルでは、SystemオブジェクトのapiEndpoint値を使用しています。値は、ユーザーの場所によって変わります。 Contextオブジェクトを参照してください。

北米（NA）のユーザー	ヨーロッパ（EU）のユーザー
https://api.amazonalexa.com	https://api.eu.amazonalexa.com

Messaging.MessageReceivedリクエストのサンプル

この例では、IDは変更され、切り捨てられています。

{
  "version": "1.0",
  "context": {
    "System": {
      "application": {
        "applicationId": "amzn1.echo-sdk-ams.app.b4277435"
      },
      "user": {
        "userId": "amzn1.ask.account.AGQ3PQ",
        "permissions": {
         "consentToken": "ZZZZZZZ..."
        }	
      },
      "apiAccessToken": "AxThk...",
      "request": {
        "type": "Messaging.MessageReceived",
        "requestId": "amzn1.echo-api.request.0000000-0000-0000-0000-00000000000",
        "timestamp": "2015-05-13T12:34:56Z",
        "message": {
          "notice": "<< メッセージのテキスト  >>"
        }
      }
    }
  }
}

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

フィードバックを送信

スキルにメッセージリクエストを送信する

cURLメッセージリクエストのサンプル

Messageオブジェクト

（スキルメッセージAPIへのリクエストに対する）応答

X-Amzn-RequestIDオブジェクト

エラーコード

受信したメッセージのスキルでの処理

必須で行う必要があるスキルサービスからのスキルメッセージAPIに対する確認応答

新しいリクエストタイプ

リクエスト内のPermissionsオブジェクトの同意トークン

リクエスト内のContextオブジェクトのapiEndpoint値

Messaging.MessageReceivedリクエストのサンプル

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