Lambda 関数の入力イベントとレスポンスの形式 - Amazon Lex V1

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

 

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

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

Lambda 関数の入力イベントとレスポンスの形式

このセクションでは、Amazon Lex から Lambda 関数に提供するイベントデータの構造について説明します。この情報は Lambda コードの入力の解析に使用します。また、Lambda 関数から Amazon Lex に返す必要があるレスポンスの形式についても説明します。

入力イベントの形式

以下に、Lambda 関数に渡される一般的な形式の Amazon Lex イベントを示します。この情報は、Lambda 関数の作成時に使用します。

注記

入力形式は変わる場合があり、この変更は対応する messageVersion に反映されないことがあります。新しいフィールドが追加されても、コードでエラーがスローされないようにします。

{ "currentIntent": { "name": "intent-name", "nluIntentConfidenceScore": score, "slots": { "slot name": "value", "slot name": "value" }, "slotDetails": { "slot name": { "resolutions" : [ { "value": "resolved value" }, { "value": "resolved value" } ], "originalValue": "original text" }, "slot name": { "resolutions" : [ { "value": "resolved value" }, { "value": "resolved value" } ], "originalValue": "original text" } }, "confirmationStatus": "None, Confirmed, or Denied (intent confirmation, if configured)" }, "alternativeIntents": [ { "name": "intent-name", "nluIntentConfidenceScore": score, "slots": { "slot name": "value", "slot name": "value" }, "slotDetails": { "slot name": { "resolutions" : [ { "value": "resolved value" }, { "value": "resolved value" } ], "originalValue": "original text" }, "slot name": { "resolutions" : [ { "value": "resolved value" }, { "value": "resolved value" } ], "originalValue": "original text" } }, "confirmationStatus": "None, Confirmed, or Denied (intent confirmation, if configured)" } ], "bot": { "name": "bot name", "alias": "bot alias", "version": "bot version" }, "userId": "User ID specified in the POST request to Amazon Lex.", "inputTranscript": "Text used to process the request", "invocationSource": "FulfillmentCodeHook or DialogCodeHook", "outputDialogMode": "Text or Voice, based on ContentType request header in runtime API request", "messageVersion": "1.0", "sessionAttributes": { "key": "value", "key": "value" }, "requestAttributes": { "key": "value", "key": "value" }, "recentIntentSummaryView": [ { "intentName": "Name", "checkpointLabel": Label, "slots": { "slot name": "value", "slot name": "value" }, "confirmationStatus": "None, Confirmed, or Denied (intent confirmation, if configured)", "dialogActionType": "ElicitIntent, ElicitSlot, ConfirmIntent, Delegate, or Close", "fulfillmentState": "Fulfilled or Failed", "slotToElicit": "Next slot to elicit" } ], "sentimentResponse": { "sentimentLabel": "sentiment", "sentimentScore": "score" }, "kendraResponse": { Complete query response from Amazon Kendra }, "activeContexts": [ { "timeToLive": { "timeToLiveInSeconds": seconds, "turnsToLive": turns }, "name": "name", "parameters": { "key name": "value" } } ] }

イベントフィールドに関して、次の追加情報に注意してください。

  • currentIntent – インテントの nameslotsslotDetailsconfirmationStatus の各フィールドを提供します。

     

    nluIntentConfidenceScore とは、現在のインテントがユーザーの現在のインテントに最も合致するものであると Amazon Lex が確信することです。

     

    slots は、スロット名のマップであり、インテントで Amazon Lex がユーザーとの会話で認識したスロット値に設定されます。スロット値は、ユーザーが値を指定するまで null のままです。

     

    入力イベントのスロット値は、スロットに設定済みの値のいずれとも一致しない場合があります。例えば、「どの色の車が好きですか?」というプロンプトに対して ユーザーが「ピザ」と答えると、Amazon Lex は「ピザ」をスロット値として返します。関数では、値を検証し、値がコンテキストで意味をなすことを確認する必要があります。

     

    slotDetails は、スロット値に関する追加の情報を提供します。resolutions 配列は、スロットで認識される追加の値のリストです。各スロットは、最大 5 個の値を持つことができます。

     

    originalValue フィールドには、スロットのユーザーが入力した値が入ります。スロット値として最初の解決の値を返すようにスロットタイプを設定すると、originalValueslots フィールドの値と異なる場合があります。

     

    confirmationStatus は、確認のプロンプトが発生した場合、それに応じてユーザーレスポンスを提供します。例えば、Amazon Lex が「ラージサイズのチーズピザを注文しますか?」と質問した場合、ユーザーレスポンスに応じて、このフィールドの値は Confirmed または Denied となります。それ以外の場合、このフィールドの値は None になります。

     

    ユーザーがインテントを確認した場合、Amazon Lex はこのフィールドを Confirmed に設定します。ユーザーがインテントを拒否した場合、Amazon Lex はこの値を Denied に設定します。

     

    確認のレスポンスで、ユーザーの発話によりスロットの更新が提供される場合があります。例えば、ユーザーが「はい、サイズを M に変更します。」と言ったとします。この場合、以降の Lambda イベントではスロット値が更新され、PizzaSizemedium に設定されます。Amazon Lex は confirmationStatusNone に設定します。これはユーザーが一部のスロットデータを変更し、Lambda 関数はユーザーデータの検証を実行する必要があるためです。

     

  • 代替インテント — 信頼度スコアを有効にすると、Amazon Lex は最大 4 つの代替インテントを返します。各インテントには、ユーザーの発話に基づくインテントが正しいインテントであるという Amazon Lex の信頼度を示すスコアが含まれます。

     

    代替インテントの内容は、currentIntent フィールドの内容と同じです。詳細については、「信頼スコアの使用」を参照してください。

     

  • bot – リクエストを処理したボットに関する情報です。

    • name – リクエストを処理したボットの名前。

    • alias – リクエストを処理したボットのバージョンのエイリアス。

    • version – リクエストを処理したボットのバージョン。

     

  • userId – この値はクライアントアプリケーションから提供されます。Amazon Lex は、その値を Lambda 関数に渡します。

     

  • inputTranscript – リクエストの処理に使用されるテキストです。

    入力がテキストであった場合、inputTranscript フィールドにはユーザーが入力したテキストが入ります。

     

    入力がオーディオストリームであった場合、inputTranscript フィールドにはオーディオストリームから抽出されたテキストが入ります。これは、インテントとスロット値を認識するために実際に処理されるテキストです。

     

  • invocationSource – Amazon Lex が Lambda 関数を呼び出す理由を示すため、以下のいずれかの値に設定されます。

    • DialogCodeHook – Amazon Lex は、この値を設定することで、Lambda 関数に対して関数の初期化とユーザーが入力したデータの検証を指示します。

       

      初期化および検証のコードフックとして Lambda 関数を呼び出すようにインテントを設定すると、Amazon Lex がインテントを理解した後で、Amazon Lex はユーザー入力 (発話) ごとに指定された Lambda 関数を呼び出します。

      注記

      インテントが明確でない場合、Amazon Lex は Lambda 関数を呼び出すことができません。

       

    • FulfillmentCodeHook – Amazon Lex はこの値を設定することで、Lambda 関数にインテントを達成するよう指示します。

       

      フルフィルメントコードフックとして Lambda 関数を呼び出すようインテントが設定されている場合、Amazon Lex は、インテントを達成するためにすべてのスロットデータが揃った後でのみ、invocationSource をこの値に設定します。

       

    インテントの設定では、2 つの異なる Lambda 関数を使用してユーザーデータを初期化および検証し、インテントを達成できます。1 つの Lambda 関数を使用して両方を行うこともできます。その場合、Lambda 関数は、invocationSource 値を使用して正しいコードパスをたどることができます。

     

  • outputDialogMode – 各ユーザー入力について、クライアントはいずれかのランタイム API オペレーション、PostContent、または PostText を使用して、リクエストを Amazon Lex に送信します。Amazon Lex はリクエストパラメータを使用してクライアントへのレスポンスがテキストまたは音声であるかを判断し、それに応じてこのフィールドを設定します。

     

    Lambda 関数は、この情報を使用して適切なメッセージを生成できます。例えば、クライアントが音声応答を予期している場合、Lambda 関数はテキストの代わりに音声合成マークアップ言語 (SSML) を返すことができます。

     

  • messageVersion – Lambda 関数に渡されるイベントデータの形式と Lambda 関数から返す必要があるレスポンスの形式を識別するメッセージのバージョン。

    注記

    インテントを定義するときに、この値を設定します。現在の実装では、メッセージバージョン 1.0 のみがサポートされています。そのため、コンソールではデフォルト値の 1.0 が想定され、メッセージのバージョンは表示されません。

  • sessionAttributes – クライアントがリクエストで送信するアプリケーション固有のセッション属性。Amazon Lex でこれらの属性をクライアントへのレスポンスに含める場合、Lambda 関数はこれらの属性をレスポンスで Amazon Lex に返す必要があります。詳細については、「セッション属性の設定」を参照してください。

     

  • requestAttributes – クライアントがリクエストで送信するリクエスト固有の属性。セッション全体を通しては保持する必要がない情報は、リクエスト属性を使用して渡します。リクエスト属性がない場合、値は null になります。詳細については、「リクエスト属性の設定」を参照してください。

     

  • recentIntentSummaryView - インテントの状態に関する情報。最後に使用された 3 つのインテントに関する情報を表示できます。この情報を使用して、インテントの値を設定したり、前のインテントに戻ったりできます。詳細については、「Amazon Lex API を使用したセッションの管理」を参照してください。

     

  • sentimentResponse - 最後の発話の Amazon Comprehend センチメント分析の結果。この情報を使用すると、ユーザーが表現したセンチメントに応じたボットの会話フローを管理できます。詳細については、「センチメント分析」を参照してください。

     

  • kendraResponse - Amazon Kendra インデックスへのクエリの結果。フルフィルメントコードフックへの入力にのみ含まれ、インテントが AMAZON.KendraSearchIntent 組み込みインテントを継承する場合にのみ使用されます。このフィールドには、Amazon Kendra 検索からのレスポンス全体が含まれています。詳細については、「AMAZON.KendraSearchIntent」を参照してください。

     

  • ActiveContexts — ユーザーとの会話のこのターン中にアクティブな 1 つ以上のコンテキスト。

    • TimeTime Live — ユーザーとの会話の中で、コンテキストがアクティブのままである時間の長さやターン数。

    • name – コンテキストの名前。

    • parameters – コンテキストを起動したインテントのスロットの名前と値を含む、キーバリューのペアのリスト。

    詳細については、「インテントコンテキストの設定」を参照してください。

レスポンスの形式

Amazon Lex は、以下の形式の Lambda 関数からのレスポンスを想定しています:

{ "sessionAttributes": { "key1": "value1", "key2": "value2" ... }, "recentIntentSummaryView": [ { "intentName": "Name", "checkpointLabel": "Label", "slots": { "slot name": "value", "slot name": "value" }, "confirmationStatus": "None, Confirmed, or Denied (intent confirmation, if configured)", "dialogActionType": "ElicitIntent, ElicitSlot, ConfirmIntent, Delegate, or Close", "fulfillmentState": "Fulfilled or Failed", "slotToElicit": "Next slot to elicit" } ], "activeContexts": [ { "timeToLive": { "timeToLiveInSeconds": seconds, "turnsToLive": turns }, "name": "name", "parameters": { "key name": "value" } } ], "dialogAction": { "type": "ElicitIntent, ElicitSlot, ConfirmIntent, Delegate, or Close", Full structure based on the type field. See below for details. } }

レスポンスは 4 つのフィールドで構成されます。sessionAttributesrecentIntentSummaryViewactiveContexts フィールドはオプションで、dialogAction フィールドは必須です。dialogAction フィールドの内容は、type の値によって異なります。詳細については、「dialogAction」を参照してください。

sessionAttributes

オプション。sessionAttributes フィールドを含める場合、このフィールドは空にすることができます。Lambda 関数でセッション属性が返らない場合は、API または Lambda 関数で渡された最後の既知の sessionAttributes は維持されます。詳細については、「PostContent オペレーション」と「PostText オペレーション」を参照してください。

"sessionAttributes": { "key1": "value1", "key2": "value2" }

recentIntentSummaryView

オプション。含まれている場合、1 つ以上の最近のインテントの値を設定します。最大 3 つのインテントの情報を含めることができます。例えば、現在のインテントによって収集された情報に基づいて、以前のインテントの値を設定できます。概略の情報は、インテントに対して有効である必要があります。例えば、インテント名はボットのインテントでなければなりません。概略ビューにスロット値を含める場合、スロットはインテント内に存在する必要があります。レスポンスに recentIntentSummaryView を含めない場合、最近のインテントのすべての値は変更されません。詳細については、「PutSession オペレーション」または「IntentSummary データ型」を参照してください。

"recentIntentSummaryView": [ { "intentName": "Name", "checkpointLabel": "Label", "slots": { "slot name": "value", "slot name": "value" }, "confirmationStatus": "None, Confirmed, or Denied (intent confirmation, if configured)", "dialogActionType": "ElicitIntent, ElicitSlot, ConfirmIntent, Delegate, or Close", "fulfillmentState": "Fulfilled or Failed", "slotToElicit": "Next slot to elicit" } ]

activeContexts

オプション。含まれている場合は、1 つ以上のコンテクストの値を設定します。例えば、コンテキストを含めて、会話の次のターンでそのコンテキストを認識できる入力として持つ 1 つ以上のインテントを作成できます。

レスポンスに含まれていないアクティブなコンテキストは、有効期限 (TTL)の値が減少し、次のリクエストでもアクティブになる場合があります。

入力イベントに含まれていたコンテキストに対して有効期限 (TTL) を 0 に指定すると、次のリクエストでは非アクティブになります。

詳細については、「インテントコンテキストの設定」を参照してください。

dialogAction

必須。dialogAction フィールドは、次の一連のアクションを Amazon Lex に指示し、Amazon Lex からクライアントにレスポンスが返された後でユーザーから予期されることを示します。

type フィールドは、次の一連のアクションを示します。このフィールドにより、dialogAction 値の一部として Lambda 関数が提供すべき他のフィールドも決まります。

  • Close - ユーザーからのレスポンスを予期しないように Amazon Lex に伝えます。例えば、「ピザのご注文を受け付けました」はレスポンスが不要です。

     

    fulfillmentState フィールドは必須です。Amazon Lex は、この値を使用してクライアントアプリケーションに対する dialogState レスポンスまたは PostContent レスポンスの PostText フィールドを設定します。message および responseCard フィールドはオプションです。メッセージを指定しないと、Amazon Lex はインテント用に設定された終了メッセージまたはフォローアップメッセージを使用します。

    "dialogAction": { "type": "Close", "fulfillmentState": "Fulfilled or Failed", "message": { "contentType": "PlainText or SSML or CustomPayload", "content": "Message to convey to the user. For example, Thanks, your pizza has been ordered." }, "responseCard": { "version": integer-value, "contentType": "application/vnd.amazonaws.card.generic", "genericAttachments": [ { "title":"card-title", "subTitle":"card-sub-title", "imageUrl":"URL of the image to be shown", "attachmentLinkUrl":"URL of the attachment to be associated with the card", "buttons":[ { "text":"button-text", "value":"Value sent to server on button click" } ] } ] } }
  • ConfirmIntent - ユーザーが現在のインテントを確認または拒否するために、「はい」または「いいえ」と答えることが予期されていることを Amazon Lex に知らせます。

     

    intentName フィールドと slots フィールドを含める必要があります。slots フィールドには、指定されたインテントに入力された各スロットのエントリを含める必要があります。入力されていないスロットの slots フィールドにエントリを含める必要はありません。目的の confirmationPrompt フィールドが null の場合は、message フィールドを含める必要があります。Lambda 関数で返る message フィールドの内容は、インテントで指定される confirmationPrompt よりも優先されます。responseCard フィールドはオプションです。

    "dialogAction": { "type": "ConfirmIntent", "message": { "contentType": "PlainText or SSML or CustomPayload", "content": "Message to convey to the user. For example, Are you sure you want a large pizza?" }, "intentName": "intent-name", "slots": { "slot-name": "value", "slot-name": "value", "slot-name": "value" }, "responseCard": { "version": integer-value, "contentType": "application/vnd.amazonaws.card.generic", "genericAttachments": [ { "title":"card-title", "subTitle":"card-sub-title", "imageUrl":"URL of the image to be shown", "attachmentLinkUrl":"URL of the attachment to be associated with the card", "buttons":[ { "text":"button-text", "value":"Value sent to server on button click" } ] } ] } }
  • Delegate - ボットの設定に基づいて次の一連のアクションを選択するよう Amazon Lex に指示します。レスポンスにセッション属性が含まれていない場合は、Amazon Lex で既存の属性が保持されます。スロット値を null にする場合は、スロットフィールドをリクエストに含める必要はありません。フルフィルメント関数がスロットを削除せずに Delegate ダイアログアクションを返した場合は、DependencyFailedException 例外が発生します。

    kendraQueryRequestPayload および kendraQueryFilterString フィールドはオプションであり、インテントが AMAZON.KendraSearchIntent 組み込みインテントを継承する場合にのみ使用されます。詳細については、「AMAZON.KendraSearchIntent」を参照してください。

    "dialogAction": { "type": "Delegate", "slots": { "slot-name": "value", "slot-name": "value", "slot-name": "value" }, "kendraQueryRequestPayload": "Amazon Kendra query", "kendraQueryFilterString": "Amazon Kendra attribute filters" }
  • ElicitIntent - ユーザーはインテントを含む発話で応答することが予期されていることを Amazon Lex に知らせます。例えば、「ラージピザが欲しい」は OrderPizzaIntent を示します。一方、「ラージ」だけの発話は、Amazon Lex がユーザーのインテントを推論するには不十分です。

     

    message および responseCard フィールドはオプションです。メッセージを指定しない場合、Amazon Lex はボットの明確化プロンプトのいずれかを使用します。明確化プロンプトが定義されていない場合、Amazon Lex は 400 Bad Request 例外を返します。

    { "dialogAction": { "type": "ElicitIntent", "message": { "contentType": "PlainText or SSML or CustomPayload", "content": "Message to convey to the user. For example, What can I help you with?" }, "responseCard": { "version": integer-value, "contentType": "application/vnd.amazonaws.card.generic", "genericAttachments": [ { "title":"card-title", "subTitle":"card-sub-title", "imageUrl":"URL of the image to be shown", "attachmentLinkUrl":"URL of the attachment to be associated with the card", "buttons":[ { "text":"button-text", "value":"Value sent to server on button click" } ] } ] } }
  • ElicitSlot - ユーザーがレスポンスでスロット値を提供することが予期されていることを Amazon Lex に知らせます。

     

    intentNameslotToElicitslots の各フィールドは必須です。message および responseCard フィールドはオプションです。メッセージを指定しない場合、Amazon Lex はスロットに設定されているスロットを引き出すプロンプトのいずれかを使用します。

    "dialogAction": { "type": "ElicitSlot", "message": { "contentType": "PlainText or SSML or CustomPayload", "content": "Message to convey to the user. For example, What size pizza would you like?" }, "intentName": "intent-name", "slots": { "slot-name": "value", "slot-name": "value", "slot-name": "value" }, "slotToElicit" : "slot-name", "responseCard": { "version": integer-value, "contentType": "application/vnd.amazonaws.card.generic", "genericAttachments": [ { "title":"card-title", "subTitle":"card-sub-title", "imageUrl":"URL of the image to be shown", "attachmentLinkUrl":"URL of the attachment to be associated with the card", "buttons":[ { "text":"button-text", "value":"Value sent to server on button click" } ] } ] } }