リクエストの構文 URI リクエストパラメータリクエストボディレスポンスの構文レスポンス要素エラーその他の参照資料

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

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

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

PostText

ユーザー入力を Amazon Lex に送信します。クライアントアプリケーションは、この API を使用して、実行時に Amazon Lex にリクエストを送信できます。そして、Amazon Lex は、ボットのために構築した機械学習モデルを使って、ユーザーの入力を解釈します。

これに対して Amazon Lex は、次の message を返してユーザーに任意の responseCard を表示するように伝えます。次のメッセージ例を考えます。

ユーザーが「ピザが欲しい」と入力すると、Amazon Lex は「どのサイズのピザがいいですか?」というスロットデータを引き出すメッセージを含むレスポンスを返す場合があります (例: PizzaSize)。
ユーザーがピザの注文情報をすべて提供した後、Amazon Lex はユーザーに確認のメッセージを含むレスポンスを返すかもしれません。「ピザの注文を続けますか？」
ユーザーが確認のプロンプトに「はい」と答えた後、Amazon Lex は結果ステートメントを返します。「ありがとうございます。チーズピザが注文されました」

すべての Amazon Lex メッセージにユーザーの反応を必要なわけではありません。例えば、結果ステートメントはレスポンスが不要です。メッセージの中には、「はい」か「いいえ」のどちらかのレスポンスしか必要ないものもあります。Amazon Lex は、message に加えて、レスポンス内のメッセージに関する追加のコンテキストを提供します。例えば、適切なクライアントのユーザーインターフェースを表示するなど、クライアントの動作を強化するために使用することができます。これがレスポンスのslotToElicit、dialogState、intentName、slots の各フィールドです。次の例を考えます。

メッセージがスロットデータを引き出すものであれば、Amazon Lex は次のようなコンテキスト情報を返します。
- dialogStateに設定 ElicitSlot
- intentName が現在のコンテキストのインテント名に設定されました
- message が情報を取得するスロット名に slotToElicit が設定されました
- slots がインテントに応じて設定された既知の値を持つスロットのマップに設定されました
メッセージが確認プロンプトの場合、dialogStateは null ConfirmIntent に設定されSlotToElicit、null に設定されます。
メッセージがユーザーの意図が理解できないことを示す明確化プロンプト（その意図に合わせて設定された）である場合、は null ElicitIntent に設定され、null slotToElicit に設定されます。dialogState

さらに、Amazon Lex はまた、お客様の用途に合わせた sessionAttributes も返します。詳細については、「Managing Conversation Context」(会話コンテキストの管理) を参照してください。

リクエストの構文


POST /bot/botName/alias/botAlias/user/userId/text HTTP/1.1
Content-type: application/json

{
   "activeContexts": [ 
      { 
         "name": "string",
         "parameters": { 
            "string" : "string" 
         },
         "timeToLive": { 
            "timeToLiveInSeconds": number,
            "turnsToLive": number
         }
      }
   ],
   "inputText": "string",
   "requestAttributes": { 
      "string" : "string" 
   },
   "sessionAttributes": { 
      "string" : "string" 
   }
}

URI リクエストパラメータ

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

botAlias

Amazon Lex ボットのエイリアス。

必須: はい

botName

Amazon Lex ボットの名前。

必須: はい

userId

クライアントアプリケーションユーザーの ID。Amazon Lex は、ユーザーとボットとの会話を識別するために使用します。実行時には、各リクエストに userID フィールドを含める必要があります。

アプリケーションに使用するユーザー ID を決定するには、以下の点を考慮してください。

userID フィールドには、ユーザーの個人識別情報 (氏名、個人識別番号、その他のエンドユーザーの個人情報など) を含めることはできません。
ユーザーがあるデバイスで会話を始め、別のデバイスで会話を続けたい場合は、ユーザー固有の識別子を使用します。
同じユーザーが 2 つの異なるデバイスで別々の会話ができるようにする場合は、デバイス固有の識別子を選択します。
ユーザーは、同じボットの 2 つの異なるバージョンと、2 つの独立した会話をすることはできません。例えば、ユーザーは同じボットの PROD バージョンとベータ版と会話することはできません。例えば、テスト中に、ユーザーが 2 つの異なるバージョンと会話する必要があることが予想される場合は、ユーザー ID にボットエイリアスを含めて、2 つの会話を区切ります。

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

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

必須: はい

リクエストボディ

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

activeContexts

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

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

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

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

必須: いいえ

inputText

ユーザーが入力したテキスト (Amazon Lex はこのテキストを解釈します)。

AWS CLI を使用している場合、--input-text パラメータに URL を渡すことはできません。代わりに --cli-input-json パラメータを使って URL を渡します。

型: 文字列

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

必須: はい

requestAttributes

クライアントアプリケーションと Amazon Lex の間で受け渡しされるリクエスト固有の情報。

名前空間 x-amz-lex: は、特別な属性のために予約されています。プレフィックス x-amz-lex: を持つリクエスト属性を作成しないでください。

リクエスト属性の詳細については、「Setting Requests Attributes」(リクエスト属性の設定) を参照してください。

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

必須: いいえ

sessionAttributes

Amazon Lex とクライアントアプリケーションの間で渡されるアプリケーション固有の情報。

詳細については、「Setting Session Attributes」(リクエスト属性の設定) を参照してください。

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

必須: いいえ

レスポンスの構文


HTTP/1.1 200
Content-type: application/json

{
   "activeContexts": [ 
      { 
         "name": "string",
         "parameters": { 
            "string" : "string" 
         },
         "timeToLive": { 
            "timeToLiveInSeconds": number,
            "turnsToLive": number
         }
      }
   ],
   "alternativeIntents": [ 
      { 
         "intentName": "string",
         "nluIntentConfidence": { 
            "score": number
         },
         "slots": { 
            "string" : "string" 
         }
      }
   ],
   "botVersion": "string",
   "dialogState": "string",
   "intentName": "string",
   "message": "string",
   "messageFormat": "string",
   "nluIntentConfidence": { 
      "score": number
   },
   "responseCard": { 
      "contentType": "string",
      "genericAttachments": [ 
         { 
            "attachmentLinkUrl": "string",
            "buttons": [ 
               { 
                  "text": "string",
                  "value": "string"
               }
            ],
            "imageUrl": "string",
            "subTitle": "string",
            "title": "string"
         }
      ],
      "version": "string"
   },
   "sentimentResponse": { 
      "sentimentLabel": "string",
      "sentimentScore": "string"
   },
   "sessionAttributes": { 
      "string" : "string" 
   },
   "sessionId": "string",
   "slots": { 
      "string" : "string" 
   },
   "slotToElicit": "string"
}

レスポンス要素

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

サービスから以下のデータが JSON 形式で返されます。

activeContexts

セッションのアクティブコンテキストのリスト。コンテキストは、インテントが達成されたとき、または PostContent、PostText、PutSession のオペレーションを呼び出したときに設定できます。

コンテキストを使用して、あるインテントをフォローできるインテントを制御したり、アプリケーションの動作を変更したりすることができます。

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

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

alternativeIntents

ユーザーのインテントに該当する可能性のある 1～4 つの代替インテント。

各選択肢には、そのインテントがユーザーのインテントがどれだけ一致しているかを示す Amazon Lex のスコアが含まれます。インテントは信頼スコアでソートされます。

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

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

botVersion

会話にレスポンスしたボットのバージョンです。この情報を使用して、あるバージョンのボットのパフォーマンスが別のバージョンよりも優れているかどうかを判断できます。

型: 文字列

長さの制限：最小長は 1 です。最大長は 64 文字です。

パターン: [0-9]+|\$LATEST

dialogState

ユーザーインタラクションの現在の状態を示します。Amazon Lex から、dialogState のような以下のいずれかの値が返されます。クライアントはオプションで、この情報を使用してユーザーインターフェイスをカスタマイズできます。

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

例: ユーザーがインテントを発話します (「ピザを注文します」)。Amazon Lex がこの発話からユーザーインテントを推測できない場合、この DialogState を返します。
ConfirmIntent - Amazon Lex は、「はい」か「いいえ」のレスポンスを待機しています。

例えば、Amazon Lex は、インテントを達成する前にユーザーの確認を求めます。

単純な「はい」または「いいえ」ではなく、ユーザーは追加情報で応答する場合があります。例えば、「はい、でも厚い生地のピザにします」や「いいえ、飲み物を注文したいです」などです。Amazon Lex はこのような追加情報を処理できます (この例では、クラストタイプのスロット値を更新するか、 OrderPizza OrderDrinkインテントをからに変更します)。
ElicitSlot - Amazon Lex は、現在のインテントのスロット値を待機しています。

例えば、レスポンスで Amazon Lex が「ピザのサイズを教えてください」というメッセージが送信するとします。ユーザーは、スロットの値 (例:「ミディアム」) と答えるかもしれません。また、ユーザーはレスポンスの中で追加情報を提供することもできます (例:「ミディアムサイズの厚い生地のピザ」)。Amazon Lex は、このような追加情報を適切に処理できます。
Fulfilled - インテントに設定された Lambda 関数が、正常にインテントを達成したことを伝えます。
ReadyForFulfillment - クライアントがインテントを達成するために必要なことを伝えます。
Failed - ユーザーとの会話が失敗したことを伝えます。

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

型: 文字列

intentName

Amazon Lex が認識している現在のユーザーインテントです。

型: 文字列

message

ユーザーに伝えるメッセージ。メッセージは、ボットの設定または Lambda 関数から送信できます。

インテントに Lambda 関数が設定されていない場合、または Lambda 関数が dialogAction.type のその応答として Delegate を返した場合、Amazon Lex は次の行動を決定し、現在のインタラクションコンテキストに基づいてボットの構成から適切なメッセージを選択します。例えば、Amazon Lex がユーザー入力を理解できない場合、明確化プロンプトメッセージを使用します。

インテントを作成するときに、グループにメッセージを割り当てることができます。メッセージがグループに割り当てられている場合、Amazon Lex は各グループから 1 つのメッセージをレスポンスに返します。メッセージフィールドは、メッセージを含むエスケープされた JSON 文字列です。返される JSON 文字列の構造の詳細については、「サポートされているメッセージ形式」を参照してください。

Lambda 関数がメッセージを返した場合、Amazon Lex はそれをレスポンスでクライアントに渡します。

型: 文字列

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

messageFormat

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

PlainText - メッセージには UTF-8 形式テキストが含まれています。
CustomPayload - メッセージは Lambda 関数で定義されるカスタム形式です。
SSML - メッセージには音声出力のテキスト形式が含まれています。
Composite - メッセージには、インテントの作成時にメッセージが割り当てられたグループからの 1 つ以上のメッセージを含むエスケープされた JSON オブジェクトが含まれています。

型: 文字列

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

nluIntentConfidence

返されたインテントがユーザーのインテントに合致するものであると Amazon Lex がどれだけ確信しているかを示すスコアを提供します。スコアは 0.0～1.0 の間です。詳細については、「Confidence Scores」(信頼スコア) を参照してください。

スコアは相対的なものであり、絶対的なものではありません。スコアは、Amazon Lex の改善により変更されることがあります。

型: IntentConfidence オブジェクト

responseCard

ユーザーが現在のプロンプトに応答するためのオプションを表します。レスポンスカードは、ボットの設定 (Amazon Lex コンソールで、スロットの横にある設定ボタンを選択) からも、コードフック (Lambda 関数) からもアクセスすることができます。

型: ResponseCard オブジェクト

sentimentResponse

ある発話で表現されたセンチメント。

ボットがセンチメント分析のために Amazon Comprehend に発話を送信するように設定されている場合、このフィールドには分析の結果が含まれます。

型: SentimentResponse オブジェクト

sessionAttributes

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

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

sessionId

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

型: 文字列

slots

会話中のユーザーの入力内容から Amazon Lex が検出したインテントスロット。

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

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

slotToElicit

dialogState の値が ElicitSlot の場合、Amazon Lex が値を引き出すスロットの名前を返します。

型: 文字列

エラー

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

LoopDetectedException

この例外は使われません。

HTTP ステータスコード: 508

NotFoundException

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

HTTP ステータスコード: 404

その他の参照資料

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

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

PostContent

PutSession