PostText - Amazon Lex V1
請求語法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，Amazon Lex 還在回應中提供有關訊息的其他內容，您可能會用來增強用戶端行為，例如顯示適當的用戶端使用者介面。這些是響應中的slotToElicitdialogStateintentName、、和slots字段。請考量下列範例：

  • 如果訊息是要引發位置資料，Amazon Lex 會傳回下列內容資訊：

    • dialogState設定為 ElicitSlot

    • intentName設定為目前前後關聯中的意圖名稱

    • slotToElicit設定為引出資訊的message插槽名稱

    • slots設置為插槽的映射，為意圖配置，具有當前已知值

  • 如果訊息是確認提示，dialogState則會將設定SlotToElicit為 ConfirmIntent 且設定為 null。

  • 如果訊息是澄清提示 (針對意圖設定)，指出使用者意圖未瞭解，dialogState則會將設定slotToElicit為 ElicitIntent 且設定為 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

工作階段的使用中前後關聯清單。上下文可以在實現意圖時或通過調用PostContentPostText、或PutSession操作來設置。

您可以使用前後關聯來控制可以跟進意圖的意圖，或修改應用程式的作業。

類型：ActiveContext 物件陣列

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

alternativeIntents

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

每個替代方案都包含一個分數，指出 Amazon Lex 對於意圖符合使用者意圖的信心程度。比對方式會依可信度分數排序。

類型：PredictedIntent 物件陣列

陣列成員：4 個項目的上限。

botVersion

回應對話的機器人版本。您可以使用此資訊來協助判斷某個機器人的某個版本是否比另一個版本更好。

類型：字串

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

模式：[0-9]+|\$LATEST

dialogState

識別使用者互動的目前狀態。Amazon Lex 返回以下值之一dialogState。用戶端可以選擇性地使用此資訊來自訂使用者介面。

  • ElicitIntent-Amazon Lex 想要引起用戶的意圖。

    例如，用戶可能會說出意圖（「我想點披薩」）。如果 Amazon Lex 無法從這個話語推斷出使用者意圖，就會傳回此對話方塊狀態。

  • ConfirmIntent-Amazon Lex 期待「是」或「否」的回應。

    例如，Amazon Lex 希望使用者在履行意圖之前確認。

    使用者可能會回應其他資訊，而不是簡單的「是」或「否」。例如，「是的，但要做厚皮披薩」或「不，我想點一杯飲料」。Amazon Lex 可以處理此類額外資訊 (在這些範例中，將外殼類型插槽值更新，或將意圖從變更 OrderPizza 為 OrderDrink)。

  • ElicitSlot-Amazon Lex 預期目前的意圖會有插槽值。

    例如，假設在響應 Amazon Lex 發送此消息：「你想要什麼尺寸的披薩？」。用戶可能會回复插槽值（例如，「中等」）。用戶還可能在響應中提供其他信息（例如，「中厚地殼披薩」）。Amazon Lex 可以適當地處理這類額外資訊。

  • Fulfilled-傳達針對意圖設定的 Lambda 函數已成功完成意圖。

  • ReadyForFulfillment-傳達客戶端必須履行的意圖。

  • Failed-傳達與使用者的對話失敗。

    發生這種情況的原因有多少，包括使用者未對服務提示提供適當的回應 (您可以設定 Amazon Lex 可以提示使用者提供特定資訊的次數)，或 Lambda 函數無法達成意圖。

類型：字串

有效值:ElicitIntent | ConfirmIntent | ElicitSlot | Fulfilled | ReadyForFulfillment | Failed

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 機器人和使用者識別碼。

HTTP 狀態碼：409

DependencyFailedException

其中一個依賴關係，如 AWS Lambda 或 Amazon Polly，拋出了一個異常。例如

  • 如果 Amazon Lex 沒有足夠的許可來呼叫 Lambda 函數。

  • 如果一個 Lambda 函數需要超過 30 秒的時間來執行。

  • 如果履行 Lambda 函數傳回Delegate對話方塊動作，但不移除任何插槽值。

狀態碼：

InternalFailureException

內部服務錯誤。重試通話。

HTTP 狀態碼：500

LimitExceededException

超過限制。

HTTP 狀態碼：429

LoopDetectedException

未使用此例外狀況。

狀態碼：

NotFoundException

找不到所參考的資源 (例如 Amazon Lex 機器人或別名)。

HTTP 狀態碼：404

另請參閱

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