ユーザーにプログレッシブ応答を送信する



ユーザーにプログレッシブ応答を送信する

スキルは、ユーザーのリクエストへの完全な応答を準備している間もユーザーの関心を引き続けられるようプログレッシブ応答を送信することができます。プログレッシブ応答は、スキルの完全な応答を待つ間にAlexaが再生する割り込みのSSMLコンテンツ(テキストの読み上げや短いオーディオ)です。

プログレッシブ応答を送信するには、プログレッシブ応答APIを呼び出し、割り込みコンテンツを指定してdirectiveを送信します。

プログレッシブ応答を送信する場合

プログレッシブ応答は以下の目的に使用できます。

  • スキルがリクエストを受信し応答を処理していることを確認する読み上げテキストを送信します。
  • スキルに関連付けられた短いサウンドマークを再生します。
  • 完全な応答を待つ間にユーザーの関心を引き留めるその他のコンテンツを提供します。

プログレッシブ応答は、ユーザーがスキル応答の待ち時間をあまり認識しなくなるという利点もあります。

たとえば、タクシーを探して予約するスキルの場合、配車予約のためのAPIにアクセスするのに数秒かかります。スキルがこの処理を行う間無言でいる代わりに、スキルがリクエストを処理中であることをユーザーに知らせるメッセージを返すことができます。

ユーザー: アレクサ、タクシー予約に空港までの配車を予約して。 (通常のIntentRequestがタクシー予約スキルに送られます)
このインテントを満たすのに必要なすべての情報を収集するための以後のやりとり

Alexa: わかりました。配車の詳細を調べるまでお待ちください...(スキルが完全な応答を準備する間のプログレッシブ応答です。)
Alexa: お待たせしました。配車を予約しました。30分以内にご自宅に到着します。IntentRequestへの通常の応答)

プログレッシブ応答は、現在のLaunchRequestまたはIntentRequestのコンテキストから送信できます。その他の種類のリクエスト(AudioPlayerリクエストなど)からプログレッシブ応答を送信することはできません。

プログレッシブ応答の送信手順

プログレッシブ応答を送信するには、プログレッシブ応答APIを呼び出し、directiveを送信します。

  1. 受信したリクエスト(LaunchRequestまたはIntentRequest)から必要なデータを取得します。有効なプログレッシブ応答APIリクエストを作成するには、apiAccessTokenrequestIdが必要です。
  2. プログレッシブ応答APIを呼び出し、directiveVoicePlayer.Speakなど)を送信します。これには、読み上げテキストやSSMLを含めることができます。
  3. 通常のスキル処理を完了します。
  4. プログレッシブ応答の呼び出しが完了したら、スキルの完全なResponseオブジェクトを返します。Responseオブジェクトを返した後はそれ以上のプログレッシブ応答を送信することはできません。

再生できるのは、Alexaサービスがスキルの完全なResponseオブジェクトを受信する前に受信したプログレッシブ応答のみです。よりよいユーザーエクスペリエンスのために、スキルはプログレッシブ応答の呼び出しが完了するのを待ってから完全なResponseオブジェクトを送信することをおすすめします。プログレッシブ応答をデバイスに送信する準備ができたら、プログレッシブ応答APIは204コードを返します。

プログレッシブ応答でオーディオを使う

SSMLの<audio>タグを使って、プログレッシブ応答に録音した短いオーディオを組み込むことができます。オーディオは30秒以内に収める必要があります。この制限は、通常の<audio>タグで許容されるオーディオの長さより短いことに注意してください。

パフォーマンスを最適化するには、スキルをホスティングしている地域に近い地域でSSMLのMP3ファイルをホスティングすることをおすすめします。たとえば、スキルのLambda関数がアジアパシフィック(東京)地域でホスティングされている場合、MP3をアジアパシフィック(東京)のS3バケットにアップロードするとパフォーマンスが向上します。

このタグを使用する場合のMP3関連のその他要件については、<audio>を参照してください。

プログレッシブ応答APIに必要なデータを取得する

プログレッシブ応答APIのすべての呼び出しには、スキルに送信されるリクエストのapiAccessTokenrequestIDが必要です。これらはどちらもスキルに送信されるリクエストから取得できます。

APIアクセストークンを取得する

contextオブジェクトに指定されたapiAccessTokenを使用します。トークンは、スキルに送信されるすべてのリクエストに含まれます。

contextオブジェクトはすべてのリクエストに含まれます。context.System.apiAccessTokenapiAccessTokenにアクセスできます。プログレッシブ応答APIの呼び出しにこのプロパティの完全な値を含めます。

{
  "version": "1.0",
  "session": {},
  "context": {
    "AudioPlayer": {},
    "System": {
      "application": {
        "applicationId": "amzn1.ask.skill.[unique-value-here]"
      },
      "user": {},
      "device": {},
      "apiEndpoint": "https://api.amazonalexa.com",
      "apiAccessToken": "AxThk..."
    }
  },
  "request": {}
}

上の例では、わかりやすくするために一部のオブジェクトとプロパティを省略しています。

リクエストIDを取得する

requestIdはAlexaからスキルに送信された特定のリクエストを識別します。この値はスキルに送信されるすべてのリクエストに、requestオブジェクト(LaunchRequestIntentRequestなど)の一部として含まれます。requestIdrequest.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はプレーンテキストまたは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":"このテキストはスキルが完全な応答を処理している間に読み上げられます。"
  }
}

Authorizationヘッダーの実際のトークンはこの例よりも長い点に注意してください。

リクエストヘッダー

ヘッダー 必須

Authorization

次の形式でのAPIアクセストークンです。 Bearer apiAccessToken

スキルに送信されたリクエストcontext.System.apiAccessTokenプロパティからapiAccessTokenを取得します。

文字列

Content-Type

application/json

文字列

リクエスト本文

JSONオブジェクトでリクエスト本文を提供します。

{
  "header":{
    "requestId":"amzn1.echo-api.request.xxxxxxx"
  },
  "directive":{
    "type":"VoicePlayer.Speak",
    "speech":"このテキストはスキルが完全な応答を処理している間に読み上げられます。"
  }
}
パラメーター 必須

header.requestId

ユーザーリクエストのrequestIdです。

スキルに送信されたリクエストに含まれるrequest.requestIdプロパティからrequestIdを取得します。

requestIdはスキルに送信されるLaunchRequestまたはIntentRequestのIDと完全に一致する必要があります。

文字列

directive.type

directiveタイプです。サポートされるdirectiveVoicePlayer.Speakのみです。

文字列

directive.speech

Alexaが読み上げるテキストです。プレーンテキストまたはSSMLで指定できます。

  • テキストは600文字以内で指定してください。これはResponseオブジェクトoutputSpeechよりも小さいです。
  • SSMLの<audio>タグを使用する場合、オーディオは30秒以内に収める必要があります。これも、通常のオーディオの長さより短くなっています。このタグを使用する場合のMP3関連のその他要件については、<audio>を参照してください。

文字列

Directive応答

Alexaがdirectiveリクエストで指定したテキストを処理して読み上げることができる場合、サービスはHTTP 204コードを返します。応答には他のデータは含まれません。その他のステータスコードはAlexaがテキストを読み上げることのできないエラーを表します。

正しい形式のdirective応答がエラーになる場合、問題なく再送して再試行できます。Alexaが同じコンテンツを複数回再生することはありません。

有効な応答

directive応答が返す可能性のあるコードは以下のとおりです。

応答 説明
204 No Content Alexaは正常にディレクティブを処理しました。
400 Bad Request requestIdがないか、構造が正しくありません。
403 Forbidden 認証トークンが無効か、リソースに対するアクセス権限がありません。これはrequestIdが実施できないリクエストを表す場合にも返されます。たとえば、スキルの完全な応答の後にプログレッシブ応答を受信した場合などです。
405 Method Not Allowed メソッドがサポートされていません。
429 Too Many Requests リクエスト件数の超過によりスキルが制限されています。
500 Internal Error 想定外のエラーが発生しました。