ユーザーにプログレッシブ応答を送信する
スキルは、ユーザーのリクエストへの完全な応答を準備している間もユーザーの関心を引き続けられるようプログレッシブ応答を送信することができます。プログレッシブ応答は、スキルの完全な応答を待つ間にAlexaが再生する割り込みのSSMLコンテンツ（テキストの読み上げや短いオーディオ）です。
プログレッシブ応答を送信するには、プログレッシブ応答APIを呼び出し、割り込みコンテンツを指定してdirectiveを送信します。
- プログレッシブ応答を送信する場合
- プログレッシブ応答の送信手順
- プログレッシブ応答でオーディオを使う
- プログレッシブ応答APIに必要なデータを取得する
- スキルのAPIエンドポイントと地域
- Directiveを送信する
- 関連トピック
プログレッシブ応答を送信する場合
プログレッシブ応答は以下の目的に使用できます。
- スキルがリクエストを受信し応答を処理していることを確認する読み上げテキストを送信します。
- スキルに関連付けられた短いサウンドマークを再生します。
- 完全な応答を待つ間にユーザーの関心を引き留めるその他のコンテンツを提供します。
プログレッシブ応答は、ユーザーがスキル応答の待ち時間をあまり認識しなくなるという利点もあります。
たとえば、タクシーを探して予約するスキルの場合、配車予約のためのAPIにアクセスするのに数秒かかります。スキルがこの処理を行う間無言でいる代わりに、スキルがリクエストを処理中であることをユーザーに知らせるメッセージを返すことができます。
ユーザー： アレクサ、タクシー予約で空港までの配車を予約して。 （通常のIntentRequestがタクシー予約スキルに送られます）
このインテントを満たすのに必要なすべての情報を収集するための以後のやりとり
Alexa： わかりました。配車の詳細を調べるまでお待ちください...（スキルが完全な応答を準備する間のプログレッシブ応答です。）
Alexa： お待たせしました。配車を予約しました。30分以内にご自宅に到着します。 （IntentRequestへの通常の応答）
プログレッシブ応答は、現在のLaunchRequestまたはIntentRequestのコンテキストから送信できます。その他の種類のリクエスト（AudioPlayerリクエストなど）からプログレッシブ応答を送信することはできません。
プログレッシブ応答の送信手順
プログレッシブ応答を送信するには、プログレッシブ応答APIを呼び出し、directiveを送信します。
- 受信したリクエスト（
LaunchRequestまたはIntentRequest）から必要なデータを取得します。有効なプログレッシブ応答APIリクエストを作成するには、apiAccessTokenとrequestIdが必要です。 - プログレッシブ応答APIを呼び出し、
directive（VoicePlayer.Speakなど）を送信します。コンテンツは、<speak>タグで囲まれた、有効なSSMLである必要があります。 - 通常のスキル処理を完了します。
- プログレッシブ応答の呼び出しが完了したら、スキルの完全なResponseオブジェクトを返します。Responseオブジェクトを返した後はそれ以上のプログレッシブ応答を送信することはできません。
再生できるのは、Alexaサービスがスキルの完全なResponseオブジェクトを受信する前に受信したプログレッシブ応答のみです。よりよいユーザーエクスペリエンスのために、スキルはプログレッシブ応答の呼び出しが完了するのを待ってから完全なResponseオブジェクトを送信することをおすすめします。プログレッシブ応答をデバイスに送信する準備ができたら、プログレッシブ応答APIは204コードを返します。
プログレッシブ応答でオーディオを使う
SSMLの<audio>タグを使って、プログレッシブ応答に録音した短いオーディオを組み込むことができます。オーディオは30秒以内に収める必要があります。この制限は、通常の<audio>タグで許容されるオーディオの長さより短いことに注意してください。
パフォーマンスを最適化するには、スキルをホスティングしている地域に近い場所でSSMLのMP3ファイルをホスティングすることをおすすめします。たとえば、スキルのLambda関数がアジアパシフィック（東京）地域でホスティングされている場合、MP3をアジアパシフィック（東京）のS3バケットにアップロードするとパフォーマンスが向上します。
このタグを使用する場合のMP3関連のその他要件については、<audio>を参照してください。
プログレッシブ応答APIに必要なデータを取得する
プログレッシブ応答APIのすべての呼び出しには、スキルに送信されるリクエストのapiAccessTokenとrequestIDが必要です。これらはどちらもスキルに送信されるリクエストから取得できます。
APIアクセストークンを取得する
contextオブジェクトに指定されたapiAccessTokenを使用します。トークンは、スキルに送信されるすべてのリクエストに含まれます。
contextオブジェクトはすべてのリクエストに含まれます。context.System.apiAccessTokenのapiAccessTokenにアクセスできます。プログレッシブ応答APIの呼び出しにこのプロパティの完全な値を含めます。
{
"version": "1.0",
"session": {},
"context": {
"AudioPlayer": {},
"System": {
"application": {
"applicationId": "amzn1.ask.skill.[unique-value-here]"
},
"user": {},
"device": {},
"apiEndpoint": "https://api.fe.amazonalexa.com",
"apiAccessToken": "AxThk..."
}
},
"request": {}
}
上の例では、わかりやすくするために一部のオブジェクトとプロパティを省略しています。
リクエストIDを取得する
requestIdはAlexaからスキルに送信された特定のリクエストを識別します。この値はスキルに送信されるすべてのリクエストに、requestオブジェクト（LaunchRequestやIntentRequestなど）の一部として含まれます。requestIdはrequest.requestIdから取得できます。
{
"version": "1.0",
"session": {},
"context": {},
"request": {
"type": "LaunchRequest",
"requestId": "amzn1.echo-api.request.xxxxxxx",
"timestamp": "2015-05-13T12:34:56Z",
"locale": "ja-JP"
}
}
上の例では、わかりやすくするために一部のオブジェクトとプロパティを省略しています。
request.requestIdプロパティの値全体を、プログレッシブ応答APIに渡します。
スキルのAPIエンドポイントと地域
プログレッシブ応答APIのエンドポイントはスキルの地域によって異なります。正しいベースURLはSystemオブジェクト（context.System.apiEndpoint）のapiEndpoint値から取得できます。
{
"version": "1.0",
"session": {},
"context": {
"System": {
"application": {
"applicationId": "amzn1.ask.skill.<skill-id>"
},
"user": {},
"apiAccessToken": "AxThk...",
"apiEndpoint": "https://api.fe.amazonalexa.com"
}
},
"request": {}
}
このドキュメントの例では、日本のエンドポイント（https://api.fe.amazonalexa.com/）を使用しています。
複数言語用にスキルを設定する詳細については、多言語に対応するスキルを開発するを参照してください。
Directiveを送信する
このAPI呼び出しは、指定したdirectiveをAlexaに送信します。現時点でサポートされているディレクティブはVoicePlayer.Speakのみです。このディレクティブはAlexaに指定したspeechを読み上げるよう指示します。speechは<speak>タグで囲む必要があります。必要に応じてspeech内でSSMLタグを使用できます。
スキルは1件のユーザーリクエストにつき、最大5つのdirectiveリクエストを送信できます。この制限を超える呼び出しは拒否されます。各directiveリクエストは個別のAPI呼び出しとして送信する必要があります。
エンドポイント： /v1/directives
メソッド： POST
Directiveリクエスト
POST https://api.fe.amazonalexa.com/v1/directives HTTP/1.1
Authorization: Bearer AxThk...
Content-Type: application/json
{
"header":{
"requestId":"amzn1.echo-api.request.xxxxxxx"
},
"directive":{
"type":"VoicePlayer.Speak",
"speech":"<speak>このテキストはスキルが完全な応答を処理している間に読み上げられます。</speak>"
}
}
Authorizationヘッダーの実際のトークンはこの例よりも長い点に注意してください。
リクエストヘッダー
| ヘッダー | 値 | 型 | 必須 |
|---|---|---|---|
|
|
次の形式でのAPIアクセストークンです。 スキルに送信されたリクエストの |
|
|
|
|
|
|
◯ |
リクエスト本文
JSONオブジェクトでリクエスト本文を提供します。
{
"header":{
"requestId":"amzn1.echo-api.request.xxxxxxx"
},
"directive":{
"type":"VoicePlayer.Speak",
"speech":"<speak>このテキストはスキルが完全な応答を処理している間に読み上げられます。</speak>"
}
}
| パラメーター | 値 | 型 | 必須 |
|---|---|---|---|
|
|
ユーザーリクエストの スキルに送信されたリクエストに含まれる
|
|
◯ |
|
|
directiveタイプです。サポートされるdirectiveは |
|
◯ |
|
|
Alexaが読み上げるテキストです。SSMLの
|
|
◯ |
Directive応答
Alexaがdirectiveリクエストで指定したテキストを処理して読み上げることができる場合、サービスはHTTP 204コードを返します。応答には他のデータは含まれません。その他のステータスコードはAlexaがテキストを読み上げることのできないエラーを表します。
正しい形式のdirective応答がエラーになる場合、問題なく再送して再試行できます。Alexaが同じコンテンツを複数回再生することはありません。
有効な応答
directive応答が返す可能性のあるコードは以下のとおりです。
| 応答 | 説明 |
|---|---|
| 204 No Content | Alexaは正常にディレクティブを処理しました。 |
| 400 Bad Request | requestIdがないか、構造が正しくありません。 |
| 401 Unauthorized | 認証トークンが無効か、リソースに対するアクセス権限がありません。これはrequestIdが実施できないリクエストを表す場合にも返されます。たとえば、スキルの完全な応答の後にプログレッシブ応答を受信した場合などです。以前403エラーとなっていたエラーは、401エラーとなります。 |
| 405 Method Not Allowed | メソッドがサポートされていません。 |
| 429 Too Many Requests | リクエスト件数の超過によりスキルが制限されています。 |
| 500 Internal Error | 想定外のエラーが発生しました。 |
関連トピック
- Alexaから送信されたリクエストを処理する
- カスタムスキルのJSONインターフェースのリファレンス
- 標準のリクエストタイプのリファレンス
- カスタムスキルのビルド手順
- プログレッシブ応答APIの例（GitHub）
- Alexa Skills Kit SDK for Node.jsのディレクティブサービス（GitHub）
最終更新日: 2022 年 07 月 04 日