メニュー
Amazon Lex
開発者ガイド

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

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

入力イベントの形式

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

注記

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

{ "currentIntent": { "name": "intent-name", "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" } }

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

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

     

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

     

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

     

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

     

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

     

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

     

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

     

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

     

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

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

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

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

     

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

     

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

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

     

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

     

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

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

       

      初期化および検証のコードフックとして Lambda 関数を呼び出すようにインテントを設定すると、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 – クライアントがリクエストで送信するリクエスト固有の属性。セッション全体を通しては保持する必要がない情報は、リクエスト属性を使用して渡します。詳細については、「リクエスト属性の設定」を参照してください。

     

レスポンスの形式

Amazon Lex は次の形式で Lambda 関数からのレスポンスを予期します。

{ "sessionAttributes": { "key1": "value1", "key2": "value2" ... }, "dialogAction": { "type": "ElicitIntent, ElicitSlot, ConfirmIntent, Delegate, or Close", Full structure based on the type field. See below for details. } }

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

sessionAttributes

オプション。sessionAttributes フィールドを含める場合、このフィールドは空にすることができます。Amazon Lex でクライアントアプリケーションへのレスポンスにセッション属性を含める場合、Lambda 関数はこのフィールドでそれらの属性を返す必要があります。詳細については、PostContent オペレーションと PostText オペレーションを参照してください。

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

dialogAction

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

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

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

     

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

    "dialogAction": { "type": "Close", "fulfillmentState": "Fulfilled or Failed", "message": { "contentType": "PlainText or SSML", "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 フィールドには、指定されたインテントに設定された各スロットのエントリを含める必要があります。スロットの値が不明な場合は、値を null に設定する必要があります。message および responseCard フィールドはオプションです。

    "dialogAction": { "type": "ConfirmIntent", "message": { "contentType": "PlainText or SSML", "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 に指示します。レスポンスには、任意のセッション属性を含める必要があります。slots フィールドには、リクエストされたインテントに指定されたすべてのスロットを含める必要があります。フィールドの値が不明な場合は、値を null に設定する必要があります。フルフィルメント関数がスロットを削除せずに Delegate ダイアログアクションを返した場合は、DependencyFailedException 例外を受け取ります。

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

     

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

    { "dialogAction": { "type": "ElicitIntent", "message": { "contentType": "PlainText or SSML", "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 の各フィールドは必須です。slots フィールドには、リクエストされたインテントに指定されたすべてのスロットを含める必要があります。message および responseCard フィールドはオプションです。メッセージを指定しない場合、Amazon Lex はスロットに設定された、スロットを引き出すプロンプトのいずれかを使用します。

    "dialogAction": { "type": "ElicitSlot", "message": { "contentType": "PlainText or SSML", "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" } ] } ] } }