PostText

將使用者輸入傳送至 Amazon Lex。用戶端應用程式可以使用此 API 在執行時間傳送請求至 Amazon Lex。然後，Amazon Lex 會使用為機器人建置的機器學習模型來解譯使用者輸入。

為了回應，Amazon Lex 會傳回下一個 message，將選用responseCard的顯示傳達給使用者。請考慮下列範例訊息：

對於使用者輸入「我想要比薩」，Amazon Lex 可能會傳回包含訊息引發槽資料的回應（例如 PizzaSize)：「您想要什麼大小的比薩？」
使用者提供所有比薩訂單資訊後，Amazon Lex 可能會傳回包含訊息的回應，以取得使用者確認「使用比薩訂單繼續？」。
使用者以「是」回應確認提示後，Amazon Lex 可能會傳回結論陳述式：「謝謝，您的起司比薩已訂購。」。

並非所有 Amazon Lex 訊息都需要使用者回應。例如，結論陳述式不需要回應。有些訊息只需要「是」或「否」使用者回應。除了之外message，Amazon Lex 還提供回應中訊息的其他內容，例如，您可以用來增強用戶端行為，以顯示適當的用戶端使用者介面。這些是回應中的 slotToElicit、intentName、 dialogState和 slots 欄位。請考量下列範例：

如果訊息是要引出槽資料，Amazon Lex 會傳回下列內容資訊：
- dialogState 設定為 ElicitSlot
- intentName 設定為目前內容中的意圖名稱
- slotToElicit 設定為 message 要為其引出資訊的插槽名稱
- slots 設定為針對意圖設定的插槽映射，具有目前已知值
如果訊息是確認提示，dialogState則會設為 ConfirmIntent，並將 SlotToElicit 設為 null。
如果訊息是說明提示（針對意圖設定），指出不了解使用者意圖，dialogState則會設為 ElicitIntent，而 slotToElicit 會設為 null。

此外，Amazon Lex 也會傳回應用程式特定的 sessionAttributes。如需詳細資訊，請參閱管理對話內容。

請求語法


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 欄位不得包含使用者的任何個人識別資訊，例如姓名、個人識別號碼或其他最終使用者個人資訊。
如果您希望使用者在一個裝置上開始對話，並在另一個裝置上繼續對話，請使用使用者特定的識別符。
如果您希望相同的使用者能夠在兩個不同的裝置上進行兩個獨立的對話，請選擇裝置特定的識別符。
使用者無法與相同機器人的兩個不同版本進行兩個獨立對話。例如，使用者無法與相同機器人的 PROD 和 BETA 版本進行對話。如果您預期使用者需要與兩個不同版本進行對話，例如在測試時，請在使用者 ID 中包含機器人別名，以分隔兩個對話。

長度限制：長度下限為 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。長度上限為 1024。

必要：是

requestAttributes

Amazon Lex 與用戶端應用程式之間傳遞的請求特定資訊。

命名空間x-amz-lex:會保留給特殊屬性。請勿建立任何字首為的請求屬性x-amz-lex:。

如需詳細資訊，請參閱設定請求屬性。

類型：字串到字串映射

必要：否

sessionAttributes

Amazon Lex 與用戶端應用程式之間傳遞的應用程式特定資訊。

如需詳細資訊，請參閱設定工作階段屬性。

類型：字串到字串映射

必要：否

回應語法


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、或 PutSession操作時PostText，可以設定內容。

您可以使用內容來控制可追蹤意圖的意圖，或修改應用程式的操作。

類型：ActiveContext 物件陣列

陣列成員：項目數下限為 0。項目數上限為 20。

alternativeIntents

一到四個可能適用於使用者意圖的替代意圖。

每個替代方案都包含一個分數，指出 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 傳送此訊息：「您想要什麼大小的比薩？」。使用者可能會以槽值（例如 "medium") 回覆。使用者也可以在回應中提供額外資訊（例如，「中厚地殼比薩」)。Amazon Lex 可以適當地處理這類額外資訊。
Fulfilled - 傳達為意圖設定的 Lambda 函數已成功滿足意圖。
ReadyForFulfillment - 傳達用戶端必須滿足意圖。
Failed - 傳達與使用者的對話失敗。

這可能有多種原因，包括使用者未提供適當的回應給來自服務的提示（您可以設定 Amazon Lex 可提示使用者提供特定資訊的次數），或 Lambda 函數無法滿足意圖。

類型：字串

intentName

Amazon Lex 目前知道的使用者意圖。

類型：字串

message

要傳達給使用者的訊息。訊息可能來自機器人的組態或 Lambda 函數。

如果意圖未使用 Lambda 函數設定，或 Lambda 函數傳回Delegate為dialogAction.type回應，Amazon Lex 會決定下一個動作步驟，並根據目前的互動內容從機器人的組態中選取適當的訊息。例如，如果 Amazon Lex 無法了解使用者輸入，則會使用釐清提示訊息。

當您建立意圖時，您可以將訊息指派給群組。當訊息指派給群組時，Amazon Lex 會從回應中的每個群組傳回一則訊息。訊息欄位是包含訊息的逸出 JSON 字串。如需傳回之 JSON 字串結構的詳細資訊，請參閱支援的訊息格式。

如果 Lambda 函數傳回訊息，Amazon Lex 會在回應中將其傳遞給用戶端。

類型：字串

長度限制：長度下限為 1。長度上限為 1024。

messageFormat

回應訊息的格式。下列其中一值：

PlainText - 訊息包含純 UTF-8 文字。
CustomPayload - 訊息是由 Lambda 函數定義的自訂格式。
SSML - 訊息包含語音輸出的文字格式。
Composite - 訊息包含逸出的 JSON 物件，其中包含訊息在建立意圖時指派給群組的一或多個訊息。

類型：字串

有效值:PlainText | CustomPayload | SSML | Composite

nluIntentConfidence

提供分數，指出 Amazon Lex 對傳回意圖是符合使用者意圖的意圖的可信度。分數介於 0.0 和 1.0 之間。如需詳細資訊，請參閱可信度分數。

分數是相對分數，而不是絕對分數。分數可能會根據 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) 失敗並發生內部服務錯誤。

HTTP 狀態碼：502

BadRequestException

請求驗證失敗、內容中沒有可用的訊息，或機器人建置失敗、仍在進行中，或包含未建置的變更。

HTTP 狀態碼：400

ConflictException

兩個用戶端使用相同的 AWS 帳戶、Amazon Lex 機器人和使用者 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 機器人或別名）。

HTTP 狀態碼：404

另請參閱

如需在其中一種語言特定 AWS SDKs中使用此 API 的詳細資訊，請參閱以下內容：

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

PostContent

PutSession