スキルメッセージAPIリファレンス
スキルメッセージAPIは、スキルにメッセージリクエストを送信するために使用します。詳細については、Alexaスキルのスキルイベント、Alexaスキルのリストイベント、スキルにメッセージを送信するようアプリケーションやサービスを設定するを参照してください。
北米(NA)およびヨーロッパ(EU)のPOSTコマンド
apiEndpoint
値から構築する最後のPOSTコマンドは、以下の形式で記述します。1つ目は米国のエンドポイント、2つ目はヨーロッパのエンドポイントです。
POST api.amazonalexa.com/v1/skillmessages/users/{userId}
POST api.eu.amazonalexa.com/v1/skillmessages/users/{userId}
スキルイベントを使用するスキルの場合、使用するエンドポイントは、このユーザーのイベントで送信されたapiEndpoint
値に基づいています。
スキルメッセージAPIの使い方
指定されたユーザーのスキルにメッセージリクエストを送信するにはスキルメッセージAPIを使います。
スキルメッセージAPIは非同期です。正常な応答とは、メッセージが受け取られ、スキルに送信されるキューに入ることです。受け取ったメッセージをスキルに配信するためには、スキルのエンドポイントを使用する必要があります。スキルのエンドポイントが使用できない場合、メッセージはexpiresAfterSeconds
フィールドに指定された期間、定期的に試行を繰り返します(指定されていない場合、デフォルトの有効期間が使われます)。正常な配信には、スキルがコンテキストを継承し、メッセージを確認しなければなりません。
スキルがオンラインの場合、メッセージは処理と同時に配信されます。メッセージ配信のタイミングや順序は保証されません。呼び出し元はメッセージを受信するスキルの所有者でもあるため、呼び出し元がスキルにメッセージが配信されたかどうかを判断します。配信メカニズムには受信確認機能はありません。呼び出し元は、複数のリクエストが送信された場合の重複メッセージの処理も行います。
スキルメッセージトークンを取得する
メッセージリクエストの送信で要求されるスキルメッセージトークンを取得するには、スキルに関連付けられた「クライアントID」と「クライアントシークレット」が必要です。この情報は開発者コンソールで確認できます。
- 開発者コンソールでスキルリストを開き、対象のスキルの編集をクリックします。
- ビルドタブで、左下のアクセス権限セクションをクリックします。
- アクセス権限ページをスクロールして、一番下のAlexaスキルメッセージングセクションを表示します。
- クライアントIDとクライアントシークレットの値を後で使用できるようにコピーします。
スキルの認証情報APIを使用してClientId
とClientSecret
の値にアクセスする方法や、ASK CLIを使用し、ask api get-skill-credentials -s {skill-id}
コマンドを実行する方法もあります。
スキルのクライアントIDとクライアントシークレットの値がわかったので、以下のcURLコマンドを使用してスキルメッセージトークンを取得します。
SKILL_CLIENT_ID='スキルのクライアントID'
SKILL_CLIENT_SECRET='xxxx'
API_URL='https://api.amazon.com/auth/O2/token'
curl -k -X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&scope=alexa:skill_messaging&client_id=$SKILL_CLIENT_ID&client_secret=$SKILL_CLIENT_SECRET" \
$API_URL
このcURLコマンドからの応答で、Atc|
で始まる「access_token」が提供されます。これは、以下のセクションのcURLメッセージリクエストのサンプルで使用される「skillMessagingToken」です。
スキルメッセージAPIのcURLメッセージリクエストのサンプル
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
スキルメッセージAPIのパラメーター
名前 | 位置 | 型 | 必須 | 説明 |
---|---|---|---|---|
userId |
パス | 文字列 | 必須 | スキルユーザーのIDです。このIDは、Alexaが送信するリクエストで提供されるuserIdと同じです。指定されたスキルの有効なユーザーでなければなりません。 |
skillMessagingToken |
ヘッダー | 文字列 | 必須 | 認可APIから提供されるトークンです。ベアラータイプのトークンです。例: Authorization: Bearer Atc|zzzzbbbccc
|
message |
本文 | オブジェクト | 必須 |
スキルに送信するメッセージで、以下のような形式になります。
|
Messageオブジェクト
パラメーター | 型 | 説明 |
---|---|---|
data | JSON | 必須です。メッセージと一緒に送信するペイロードデータです。データは、JSON形式のキーと値のペアで指定します。キーと値は文字列型にする必要があります。データ全体のサイズは6KB以下です。データサイズには、キーと値、それらを囲む引用符、キーと値を区切る「:」、ペア間を区切るカンマ、フィールドを囲む中かっこも含みます。ただし、キー/値ペア間のスペースはペイロードサイズには含まれません。同期メッセージなど、メッセージにペイロードデータがない場合、次のように空のオブジェクトとして渡すことができます。"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のドキュメントに記載されたContextオブジェクト(Node.js)を参照してください。
Messaging.MessageReceivedリクエストタイプ
Messaging.MessageReceived
リクエストタイプはスキルエンドポイントによって処理される必要があります(AWS Lambdaかウェブサービスいずれの場合にも適用)。リクエストはインテントの一種です。このため、このリクエストタイプでは、スキルにハンドリングメソッドを追加する必要があります。リクエストの形式を参照してください。
リクエスト | MessageRequest |
---|---|
インターフェース | メッセージ |
定義 |
|
アトリビュート | メッセージ: バックエンドのサードパーティアプリケーションによって提供されるメッセージのブロブです。システムでのメッセージブロブのサイズは最大6KBです。 |
リクエスト内のPermissionsオブジェクトの同意トークン
Messaging.MessageReceived
リクエストのサンプルでは、permissions
オブジェクトのconsentToken
を使用しています。 セッション外のメッセージリクエストでは、ユーザーが同意した場合、ユーザーの同意を含むconsentToken
がスキルに提供されます。Contextオブジェクトを参照してください。
同意トークンの有効期間は60分です。永続性を持たせるべきではありません。同意トークンは、スキルメッセージAPIが新しいセッション内リクエストまたはセッション外リクエストを受信するたびに、自動的に更新されます。
各userId
は、スキルユーザーのスキル有効化の期限が切れるまで有効です。ユーザーがスキルを無効にして再度有効にした場合、userId
は変更されます。そのため、ユーザーが次にスキルを使用するとき、そのユーザーは新しいユーザーとして認識されます。新しいユーザーの場合と同様、セッション外でのメッセージの送信に使用できるよう、スキルセッションの中で与えられたuserId
を記録しておく必要があります。スキルメッセージのエンドポイント(/skillmessages/users/{userId}
)を呼び出すのにスキルメッセージAPIが使用された場合、404エラー(userIdが見つかりません)が発生し、そのuserId
はシステムで有効ではなくなります。
各Messaging.MessageReceived
リクエストにPermissionsフィールドを含める
開発者コンソールで権限を有効にしている場合、Messaging.MessageReceived
リクエストごとにpermissions
フィールドが含まれます。ユーザーが権限に同意していない場合、このフィールドには入れ子になっているconsentToken
フィールドは含まれません。ただし、スキルに同意トークンが必要な場合、スキルは権限カードをスローして、ユーザーに権限の承認を求めるプロンプトを表示しなければなりません。詳細については、ユーザー同意をリクエストする新しい権限カードを参照してください。
permissions
フィールドについては、Messaging.MessageReceived
リクエストのサンプルを参照してください。
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": "<< メッセージのテキスト >>"
}
}
}
}
}
リクエスト内のContextオブジェクトのapiEndpoint値
IntentRequest
リクエストサンプルでは、System
オブジェクトのapiEndpoint
値を使用しています。値は、ユーザーの場所によって変わります。 Contextオブジェクトを参照してください。
北米(NA)のユーザー | ヨーロッパ(EU)のユーザー |
---|---|
https://api.amazonalexa.com | https://api.eu.amazonalexa.com |
権限サポートありのIntentRequestのサンプル
{
"version": "1.0",
"session": {
"new": false,
"sessionId": "amzn1.echo-api.session.0000000-0000-0000-0000-00000000000",
"application": {
"applicationId": "amzn1.echo-sdk-ams.app.000000-d0ed-0000-ad00-000000d00ebe"
},
"attributes": {
"supportedHoroscopePeriods": {
"daily": true,
"weekly": false,
"monthly": false
}
},
"user": {
"userId": "amzn1.account.AM3B00000000000000000000000"
}
},
"context": {
"System": {
"application": {
"applicationId": "amzn1.echo-sdk-ams.app.000000-d0ed-0000-ad00-000000d00ebe"
},
"user": {
"userId": "amzn1.account.AM3B00000000000000000000000"
},
"apiAccessToken": "AxThk...",
"apiEndpoint": "https://api.amazonalexa.com"
}
},
"request": {
"type": "IntentRequest",
"requestId": " amzn1.echo-api.request.0000000-0000-0000-0000-00000000000",
"timestamp": "2015-05-13T12:34:56Z",
"intent": {
"name": "GetZodiacHoroscopeIntent",
"slots": {
"ZodiacSign": {
"name": "ZodiacSign",
"value": "virgo"
}
}
}
}
}
ユーザー同意をリクエストするための権限カード
apiAccessToken
はスキルに対するすべてのリクエストに含まれます。これは、ユーザーがリクエストを完了するのに必要な権限をスキルに付与したかどうかは関係ありません。そのため、スキルがリクエストを完了するのに必要な正しい権限セットが、トークンに含まれていない可能性があります。スキルは特別な権限カードを表示して、ユーザーに動的に同意を求めることができます。
新しいカード | AskForPermissionsConsentCard |
---|---|
インターフェース | CardRenderer |
定義 |
|
アトリビュート | permissions :Alexaの権限にマッピングされるスコープ文字列のリストを含みます。スキルに必要で、かつAmazon開発者ポータルのスキルメタデータで宣言されたAlexa権限のみが含まれます。 |
apiAccessToken
はすべてのスキルリクエストに含まれるため、apiAccessToken
が存在するかどうかで必要な権限があるかを判断することはできません。代わりにAPIを呼び出して、応答コードを確認します。スキルに権限がない場合は403 Forbidden
の応答が返されるため、その時点でスキルのAlexaへの応答にAskForPermissionsConsent
カードを含めることができます。
権限カードありの応答のサンプル
セッション内の対話で、新しいAskForPermissionsConsent
カードを含む応答を返すことができます。以下は、書き込み権限をリクエストするカードに対する一般的な応答です。
{
"version": "1.0",
"response": {
"card": {
"type": "AskForPermissionsConsent",
"permissions": [
"write::alexa:household:list"
]
}
}
}
permissions
の値は、開発者コンソールのビルド>アクセス権限ページでスキルに対して宣言したスコープと同じです。