PutSession - Amazon Lex V1

Amazon Lex V2 を使用している場合は、代わりに Amazon Lex V2 ガイドを参照してください。

 

Amazon Lex V1 を使用している場合は、ボットを Amazon Lex V2 にアップグレードすることをお勧めします。V1 には新機能を追加されませんので、すべての新しいボットには V2 を使用することを強くお勧めします。

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

PutSession

Amazon Lex ボットで新しいセッションを作成するか、既存のセッションを変更します。このオペレーションにより、アプリケーションでボットの状態を設定できるようになります。

詳細については、「セッションの管理」を参照してください。

リクエストの構文

POST /bot/botName/alias/botAlias/user/userId/session HTTP/1.1 Accept: accept Content-type: application/json { "activeContexts": [ { "name": "string", "parameters": { "string" : "string" }, "timeToLive": { "timeToLiveInSeconds": number, "turnsToLive": number } } ], "dialogAction": { "fulfillmentState": "string", "intentName": "string", "message": "string", "messageFormat": "string", "slots": { "string" : "string" }, "slotToElicit": "string", "type": "string" }, "recentIntentSummaryView": [ { "checkpointLabel": "string", "confirmationStatus": "string", "dialogActionType": "string", "fulfillmentState": "string", "intentName": "string", "slots": { "string" : "string" }, "slotToElicit": "string" } ], "sessionAttributes": { "string" : "string" } }

URI リクエストパラメータ

リクエストでは、次の URI パラメータを使用します。

accept

Amazon Lex がレスポンスで返すメッセージは、このフィールドの値に応じて、テキストまたは音声ベースになります。

  • 値が text/plain; charset=utf-8 の場合、Amazon Lex はレスポンス内にテキストを返します。

  • 値が audio/ で始まっている場合、Amazon Lex はレスポンスで音声を返します。Amazon Lex は Amazon Polly を使用して、指定された構成で音声を生成します。例えば、値として audio/mpeg を指定した場合、Amazon Lex は MPEG 形式の音声を返します。

  • 値が audio/pcm の場合、返される音声は audio/pcm で、16 ット、リトルエンディアン形式です。

  • 受け入れ可能な値は以下の通りです。

    • audio/mpeg

    • audio/ogg

    • audio/pcm

    • audio/* (デフォルトは mpeg)

    • text/plain; charset=utf-8

botAlias

セッションデータを含むボットに使用されるエイリアス。

必須: はい

botName

セッションデータを含むボットの名前。

必須: はい

userId

クライアントアプリケーションユーザーの ID。Amazon Lex は、ユーザーとボットとの会話を識別するために使用します。

長さの制限: 最小長は 2 です。最大長は 100 です。

パターン: [0-9a-zA-Z._:-]+

必須: はい

リクエストボディ

リクエストは以下の JSON 形式のデータを受け入れます。

activeContexts

リクエストに対してアクティブなコンテキストのリスト。コンテキストは、以前のインテントが達成されたとき、またはリクエストにコンテキストが含まれているときに有効になります。

コンテキストのリストを指定しない場合、Amazon Lex はセッションの現在のコンテキストリストを使用します。空のリストを指定すると、セッションのすべてのコンテキストがクリアされます。

型: ActiveContext オブジェクトの配列

配列メンバー:最小数は 0 項目です。最大数は 20 項目です。

必須: いいえ

dialogAction

会話を成立させるために、ボットが取るべき次のアクションを設定します。

型: DialogAction オブジェクト

必須: いいえ

recentIntentSummaryView

ボットの最近のインテントのサマリー。インテントサマリービューを使って、インテントにチェックポイントラベルを設定したり、インテントの属性を変更したりすることができます。また、インテントサマリーオブジェクトをリストから削除したり、追加したりするのにも使用できます。

修正したり、リストに追加するインテントは、ボットにとって意味のあるものでなければなりません。例えば、インテント名はボットが検証できるインテントでなければなりません。有効な値を指定する必要があります:

  • intentName

  • スロットの名前

  • slotToElict

PutSession リクエストで recentIntentSummaryView パラメータを送信した場合、新しいサマリービューの内容が古いサマリービューに置き換わることになります。例えば、GetSession のリクエストがサマリービューで 3 つのインテントを返し、PutSession をサマリービューで 1 つのインテントで呼び出した場合、次に GetSession を呼び出しても 1 つのインテントしか返されません。

型: IntentSummary オブジェクトの配列

配列メンバー:最小数は 0 項目です。最大数は 3 項目です。

必須: いいえ

sessionAttributes

セッション固有のコンテキスト情報を表すキーバリューのペアのマップ。Amazon Lex とクライアントアプリケーションの間で渡されるアプリケーション情報を含みます。

型: 文字列間のマッピング

必須: いいえ

レスポンスの構文

HTTP/1.1 200 Content-Type: contentType x-amz-lex-intent-name: intentName x-amz-lex-slots: slots x-amz-lex-session-attributes: sessionAttributes x-amz-lex-message: message x-amz-lex-encoded-message: encodedMessage x-amz-lex-message-format: messageFormat x-amz-lex-dialog-state: dialogState x-amz-lex-slot-to-elicit: slotToElicit x-amz-lex-session-id: sessionId x-amz-lex-active-contexts: activeContexts audioStream

レスポンス要素

アクションが成功すると、サービスは HTTP 200 レスポンスを返します。

レスポンスでは、以下の HTTP ヘッダーが返されます。

activeContexts

セッションのアクティブコンテキストのリスト。

contentType

リクエストの Accept HTTP ヘッダーで指定されたコンテンツタイプ。

dialogState

  • ConfirmIntent - Amazon Lex は、インテントを達成する前に、インテントを確認するために「はい」か「いいえ」のレスポンスを待機しています。

  • ElicitIntent - Amazon Lex は、ユーザーのインテントを引き出したいと考えています。

  • ElicitSlot - Amazon Lex は、現在のインテントのためのスロット値を想定しています。

  • Failed - ユーザーとの会話が失敗したことを伝えます。これは、ユーザーがサービスからのプロンプトに適切なレスポンスを提供しない場合 (Amazon Lex がユーザーに特定の情報を促す回数を設定できます) や、Lambda 関数がインテントを達成できない場合など、さまざまな理由で発生します。

  • Fulfilled - Lambda 関数がインテントを正常に達成したことを伝えます。

  • ReadyForFulfillment - クライアントがインテントを達成する必要性を伝えます。

有効な値:ElicitIntent | ConfirmIntent | ElicitSlot | Fulfilled | ReadyForFulfillment | Failed

encodedMessage

ユーザーに提示する次のメッセージ。

encodedMessage フィールドは base-64 エンコードです。値を使用する前に、フィールドをデコードする必要があります。

長さの制限:最小長は 1 です。最大長は 1366 です。

intentName

現在のインテントの名前。

message

このヘッダーは廃止されました。

ユーザーに提示する次のメッセージ。

このフィールドは、de-DE、en-AU、en-GB、en-US、es-419、es-ES、es-US、fr-CA、fr-FR、および it-IT ロケールでのみ使用できます。その他すべてのロケールでは、message フィールドが null です。代わりに encodedMessage のフィールドを使用する必要があります。

長さの制限: 最小長は 1 です。最大長は 1,024 です。

messageFormat

応答メッセージの形式。次のいずれかの値になります。

  • PlainText - メッセージには UTF-8 形式テキストが含まれています。

  • CustomPayload - メッセージはクライアント向けのカスタム形式です。

  • SSML - メッセージには音声出力のテキスト形式が含まれています。

  • Composite - メッセージには、インテントの作成時にメッセージが割り当てられたグループからの 1 つ以上のメッセージを含むエスケープされた JSON オブジェクトが含まれています。

有効な値:PlainText | CustomPayload | SSML | Composite

sessionAttributes

セッション固有のコンテキスト情報を表すキーバリューのペアのマップ。

sessionId

セッションの一意の識別子。

slots

会話中にユーザーの入力から検出されたゼロ以上のインテントスロット (名前と値のペア) Amazon Lex のマップ。

Amazon Lex は、あるスロットに対して可能性の高い値を含む解決リストを作成します。返す値は、スロットタイプの作成時や更新時に選択された valueSelectionStrategy によって決まります。valueSelectionStrategyORIGINAL_VALUE に設定されている場合、ユーザーの値がスロットの値と類似していれば、ユーザーが提供した値が返されます。valueSelectionStrategyTOP_RESOLUTION Amazon Lex に設定されている場合は、解決リストの最初の値を返し、解決リストがない場合は null を返します。valueSelectionStrategy を指定しない場合、デフォルトは ORIGINAL_VALUE です。

slotToElicit

dialogStateElicitSlot の場合、Amazon Lex が値を引き出しているスロットの名前を返します。

レスポンスは、HTTP 本文として以下を返します。

audioStream

ユーザーに伝えるメッセージのオーディオバージョン。

エラー

BadGatewayException

Amazon Lex ボットがまだ構築中であるか、依存するサービス (Amazon Polly、AWS Lambda) の 1 つが内部サービスエラーで失敗したかのどちらかです。

HTTP ステータスコード: 502

BadRequestException

リクエストの検証に失敗したか、コンテキストに使用可能なメッセージがないか、ボットの構築が失敗もしくは進行中であるか、または構築されていない変更が含まれています。

HTTP ステータスコード:400

ConflictException

2 つのクライアントが同じ AWS アカウント、Amazon Lex bot、ユーザー ID を使用しています。

HTTP ステータスコード: 409

DependencyFailedException

AWS Lambda や Amazon Polly などの依存関係にあるものが、例外を発生させました。例、

  • Amazon Lex が Lambda 関数を呼び出すのに十分な権限を持っていない場合。

  • Lambda 関数の実行に 30 秒以上かかる場合。

  • フルフィルメントの Lambda 関数が、スロットの値を削除せずに Delegate ダイアログアクションを返す場合。

HTTP ステータスコード: 424

InternalFailureException

内部サービスエラー。呼び出しを再試行します。

HTTP ステータスコード:500

LimitExceededException

制限を超えました。

HTTP ステータスコード: 429

NotAcceptableException

リクエストの accept ヘッダーに有効な値がありません。

HTTP ステータスコード: 406

NotFoundException

参照するリソース (Amazon Lex bot やエイリアスなど) が見つかりません。

HTTP ステータスコード: 404

その他の参照資料

言語固有の AWS SDK でこの API を使用する方法の詳細については、以下を参照してください。