スキルにメッセージリクエストを送信する
指定されたユーザーのスキルにメッセージリクエストを送信するにはスキルメッセージ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です。 |
リクエスト内のPermissionsオブジェクトの同意トークン
以下の例にある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": "<< メッセージのテキスト >>"
}
}
}
}
}