PostContent - Amazon Lex V1
請求語法URI 請求參數請求主體回應語法回應元素錯誤範例另請參閱

如果您使用的是 Amazon Lex V2，請參閱 Amazon Lex V2 指南。

 

如果您使用的是 Amazon Lex V1，我們建議您將機器人升級到 Amazon Lex V2。我們不再向 V1 添加新功能，強烈建議所有新機器人使用 V2。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

PostContent

將使用者輸入 (文字或語音) 傳送至 Amazon Lex。用戶端使用此 API 在執行階段將文字和音訊請求傳送至 Amazon Lex。Amazon Lex 使用專為機器人建立的機器學習模型來解譯使用者輸入。

該PostContent操作支持 8 千赫和 16 千赫的音頻輸入。您可以使用 8kHz 音訊，在電話音訊應用中達到更高的語音辨識準確度。

作為回應，Amazon Lex 會傳回下一則要傳送給使用者的訊息。請考慮下列範例訊息：

  • 對於使用者輸入「我想要披薩」，Amazon Lex 可能會傳回回應，其中包含引出插槽資料的訊息 (例如PizzaSize)：「您想要什麼大小的披薩？」。

  • 使用者提供所有披薩訂單資訊之後，Amazon Lex 可能會傳回回覆訊息，以取得使用者確認：「訂購披薩？」。

  • 使用者在確認提示回覆「是」之後，Amazon Lex 可能會傳回結論聲明：「謝謝您，您的起司披薩已訂購完畢。」

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

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

    • x-amz-lex-dialog-state標頭設定為 ElicitSlot

    • x-amz-lex-intent-name在當前上下文中設置為意圖名稱的標題

    • x-amz-lex-slot-to-elicit標頭設置為引出信息的message插槽名稱

    • x-amz-lex-slots標頭設置為具有當前值的意圖配置的插槽的映射

  • 如果訊息是確認提示，則標x-amz-lex-dialog-state頭會設定為，Confirmation且會省略x-amz-lex-slot-to-elicit標頭。

  • 如果訊息是針對意圖設定的澄清提示，表示使用者意圖未瞭解，則標x-amz-dialog-state頭會設定為，ElicitIntent且會省略x-amz-slot-to-elicit標頭。

此外，Amazon Lex 也會傳回您的應用程式特定sessionAttributes。如需詳細資訊，請參閱管理交談前後關聯。

請求語法

POST /bot/botName/alias/botAlias/user/userId/content HTTP/1.1
x-amz-lex-session-attributes: sessionAttributes
x-amz-lex-request-attributes: requestAttributes
Content-Type: contentType
Accept: accept
x-amz-lex-active-contexts: activeContexts

inputStream

URI 請求參數

請求會使用下列 URI 參數。

accept

您可以將此值當做 Accept HTTP 標頭傳遞。

Amazon Lex 在回應中傳回的訊息可以是文字或語音，以請求中的 Accept HTTP 標頭值為基礎。

  • 如果該值為text/plain; charset=utf-8，Amazon Lex 會在回應中傳回文字。

  • 如果值的開頭為audio/，Amazon Lex 會在回應中傳回語音。Amazon Lex 使用 Amazon Polly 產生語音 (使用您在Accept標頭中指定的組態)。例如，如果您指定audio/mpeg為該值，Amazon Lex 會傳回 MPEG 格式的語音。

  • 如果值是audio/pcm，則返回的語音是 16 audio/pcm 位，小端格式。

  • 以下是可接受的值：

    • 音頻/MPEG

    • 音頻/OGG

    • 音頻/PCM

    • 文本/普通; 字符集 = UTF-8

    • 音頻/*（默認為 MPEG）

activeContexts

請求的使用中前後關聯清單。當滿足以前的意圖時，可以激活上下文，或者通過在請求中包含上下文，

如果您未指定環境清單，Amazon Lex 將使用工作階段的目前環境清單。如果您指定空白清單，則會清除工作階段的所有前後關聯。

botAlias

Amazon Lex 機器人的別名。

必要：是

botName

Amazon Lex 機器人的名稱。

必要：是

contentType

您可以將此值當做 Content-Type HTTP 標頭傳遞。

指示音訊格式或文字。標頭值必須以下列其中一個前置字元開頭：

  • PCM 格式，音頻數據必須是小端字節順序。

    • 音頻/L16; 速率 = 16; 頻道 = 1

    • 音頻/X-L16; 採樣速率 = 16; 通道計數 = 1

    • 音頻/流量厘米; 採樣速率 = 8000; = 16; 通道計數 = 1; = 假 sample-size-bits is-big-endian

  • 作品格式

    • 音訊/x-cbr-opus-with-起頭訊號；序言大小 =0；位元速率 =256000；=4 frame-size-milliseconds

  • 文字格式

    • 文本/普通; 字符集 = UTF-8

必要：是

requestAttributes

您可以將此值當做 x-amz-lex-request-attributes HTTP 標頭傳遞。

Amazon Lex 和用戶端應用程式之間傳遞的請求特定資訊。該值必須是 JSON 序列化和 base64 編碼的對應，其中包含字符串鍵和值。requestAttributes和sessionAttributes標頭的總大小限制為 12 KB。

命名空x-amz-lex:間保留給特殊屬性。不要使用前綴創建任何請求屬性x-amz-lex:。

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

sessionAttributes

您可以將此值當做 x-amz-lex-session-attributes HTTP 標頭傳遞。

Amazon Lex 和用戶端應用程式之間傳遞的應用程式特定資訊。該值必須是 JSON 序列化和 base64 編碼的對應，其中包含字符串鍵和值。sessionAttributes和requestAttributes標頭的總大小限制為 12 KB。

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

userId

用戶端應用程式使用者的 ID。Amazon Lex 使用此功能來識別使用者與您的機器人的對話。在執行階段，每個要求都必須包含userID欄位。

若要決定應用程式使用的使用者 ID，請考量下列因素。

  • 該字userID段不得包含用戶的任何個人身份信息，例如姓名，個人識別號碼或其他最終用戶的個人信息。

  • 如果您希望使用者在一部裝置上開始對話，並在另一部裝置上繼續，請使用使用者特定的識別碼。

  • 如果您希望相同的用戶能夠在兩個不同的設備上進行兩個獨立的對話，請選擇特定於設備的標識符。

  • 用戶不能與同一機器人的兩個不同版本進行兩個獨立的對話。例如，使用者無法與同一機器人的 PROD 和 BETA 版本進行對話。如果您預期使用者需要與兩個不同版本進行對話，例如在測試時，請在使用者 ID 中包含機器人別名以分隔這兩個對話。

長度約束：最小長度為 2。長度上限為 100。

模式：[0-9a-zA-Z._:-]+

必要：是

請求主體

請求接受下列二進位資料。

inputStream

使用者輸入 PCM 或 Opus 音訊格式或文字格式，如 Content-Type HTTP 標頭所述。

您可以將音訊資料串流到 Amazon Lex，也可以建立本機緩衝區，以便在傳送之前擷取所有音訊資料。一般來說，如果您串流音訊資料而不是在本機緩衝資料，則會獲得更好的效能。

必要：是

回應語法

HTTP/1.1 200
Content-Type: contentType
x-amz-lex-intent-name: intentName
x-amz-lex-nlu-intent-confidence: nluIntentConfidence
x-amz-lex-alternative-intents: alternativeIntents
x-amz-lex-slots: slots
x-amz-lex-session-attributes: sessionAttributes
x-amz-lex-sentiment: sentimentResponse
x-amz-lex-message: message
x-amz-lex-encoded-message: encodedMessage
x-amz-lex-message-format: messageFormat
x-amz-lex-dialog-state: dialogState
x-amz-lex-slot-to-elicit: slotToElicit
x-amz-lex-input-transcript: inputTranscript
x-amz-lex-encoded-input-transcript: encodedInputTranscript
x-amz-lex-bot-version: botVersion
x-amz-lex-session-id: sessionId
x-amz-lex-active-contexts: activeContexts

audioStream

回應元素

如果動作成功，則服務傳回 HTTP 200 回應。

回應會傳回下列 HTTP 標頭。

activeContexts

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

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

alternativeIntents

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

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

botVersion

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

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

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

contentType

要求中 Accept HTTP 標頭中指定的內容類型。

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

encodedInputTranscript

用來處理請求的文字。

如果輸入是音訊串流，encodedInputTranscript 欄位會包含從音訊串流擷取的文字。這是實際處理以識別意圖和槽值的文字。您可以使用此資訊判斷 Amazon Lex 是否正確處理您傳送的音訊。

該encodedInputTranscript字段以 64 為基編碼。您必須先解碼欄位，才能使用該值。

encodedMessage

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

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

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

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

該encodedMessage字段以 64 為基編碼。您必須先解碼欄位，才能使用該值。

長度限制：長度下限為 1。最大長度為 1366。

inputTranscript

此標頭已被棄用。

用來處理請求的文字。

您只能在德、恩-歐、EN-GB、EN-US、ES-419、ES-ES、ES-US、FR-CA、FR-FR 和 IT IT 語言環境中使用此欄位。在所有其他地區設定中，此inputTranscript欄位為空值。您應該改用該encodedInputTranscript字段。

如果輸入是音訊串流，inputTranscript 欄位會包含從音訊串流擷取的文字。這是實際處理以識別意圖和槽值的文字。您可以使用此資訊判斷 Amazon Lex 是否正確處理您傳送的音訊。

intentName

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

message

此標頭已被棄用。

您只能在德、EN-AU、EN-GB、EN-US、ES-419、ES-ES、ES-US、FR-CA、FR-FR 和 IT IT 地區設定中使用此欄位。在所有其他地區設定中，此message欄位為空值。您應該改用該encodedMessage字段。

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

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

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

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

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

messageFormat

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

  • PlainText-郵件包含純 UTF-8 文字。

  • CustomPayload-訊息是用戶端的自訂格式。

  • SSML-訊息包含格式化為語音輸出的文字。

  • Composite-訊息包含逸出的 JSON 物件，其中包含一或多個來自建立意圖時所指派訊息之群組的訊息。

有效值:PlainText | CustomPayload | SSML | Composite

nluIntentConfidence

提供一個分數，指出 Amazon Lex 對於傳回的意圖是符合使用者意圖的信心程度。該分數在 0.0 和 1.0 之間。

分數是相對分數，而不是絕對分數。分數可能會根據 Amazon Lex 的改進而改變。

sentimentResponse

在話語中表達的情緒。

當機器人設定為將語音傳送至 Amazon Comprehend 進行情緒分析時，此欄位會包含分析結果。

sessionAttributes

表示會話特定上下文信息的鍵/值對的映射。

sessionId

工作階段的唯一識別碼。

slots

在交談期間從使用者輸入中偵測到零個或多 Amazon Lex 意圖插槽 (名稱/值對) 的地圖。該字段以 64 為基編碼。

Amazon Lex 會建立一個解析度清單，其中包含插槽的可能值。它傳回的值由建立或更新插槽類型時valueSelectionStrategy所選取的值決定。如果設定valueSelectionStrategy為ORIGINAL_VALUE，則傳回使用者提供的值 (如果使用者值與槽值類似)。如果設定valueSelectionStrategy為 TOP_RESOLUTION Amazon Lex，則會傳回解析清單中的第一個值，如果沒有解析度清單，則傳回 null。如果未指定valueSelectionStrategy，則預設值為ORIGINAL_VALUE。

slotToElicit

如果dialogState值為ElicitSlot，則傳回 Amazon Lex 引出值的插槽名稱。

回應傳回以下內容作為 HTTP 主體。

audioStream

要傳達給使用者的提示 (或陳述式)。這是基於機器人配置和上下文。例如，如果 Amazon Lex 不瞭解使用者意圖，就會傳送針對機器人clarificationPrompt設定的設定。如果意圖在執行履行作業之前需要確認，則會傳送confirmationPrompt。另一個範例：假設 Lambda 函數成功完成了意圖，並傳送訊息傳送給使用者。然後 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

未使用此例外狀況。

狀態碼：

NotAcceptableException

請求中的接受標頭沒有有效的值。

狀態碼：

NotFoundException

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

HTTP 狀態碼：404

RequestTimeoutException

輸入語音太長。

HTTP 狀態碼：408

UnsupportedMediaTypeException

內容類型標頭 (PostContentAPI) 具有無效的值。

HTTP 狀態碼：415

範例

範例 1

在此要求中，URI 會識別機器人 (流量)、機器人版本 ($LATEST) 和一般使用者名稱 (某個使用者)。標Content-Type頭標識正文中音頻的格式。Amazon Lex 也支持其他格式。要將音頻從一種格式轉換為另一種格式，如有必要，可以使用 SoX 開源軟件。您可以透過新增 Accept HTTP 標頭來指定要取得回應的格式。

在回應中，標x-amz-lex-message頭會顯示 Amazon Lex 傳回的回應。然後，客戶端可以將此響應發送給用戶。通過分塊編碼（根據要求）以音頻/MPEG 格式發送相同的消息。

請求範例

"POST /bot/Traffic/alias/$LATEST/user/someuser/content HTTP/1.1[\r][\n]"
"x-amz-lex-session-attributes: eyJ1c2VyTmFtZSI6IkJvYiJ9[\r][\n]"
"Content-Type: audio/x-l16; channel-count=1; sample-rate=16000f[\r][\n]"
"Accept: audio/mpeg[\r][\n]"
"Host: runtime.lex.us-east-1.amazonaws.com[\r][\n]"
"Authorization: AWS4-HMAC-SHA256 Credential=BLANKED_OUT/20161230/us-east-1/lex/aws4_request, 
SignedHeaders=accept;content-type;host;x-amz-content-sha256;x-amz-date;x-amz-lex-session-attributes, Signature=78ca5b54ea3f64a17ff7522de02cd90a9acd2365b45a9ce9b96ea105bb1c7ec2[\r][\n]"
"X-Amz-Date: 20161230T181426Z[\r][\n]"
"X-Amz-Content-Sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855[\r][\n]"
"Transfer-Encoding: chunked[\r][\n]"
"Connection: Keep-Alive[\r][\n]"
"User-Agent: Apache-HttpClient/4.5.x (Java/1.8.0_112)[\r][\n]"
"Accept-Encoding: gzip,deflate[\r][\n]"
"[\r][\n]"
"1000[\r][\n]"
"[0x7][0x0][0x7][0x0][\n]"
"[0x0][0x7][0x0][0xfc][0xff][\n]"
"[0x0][\n]"
…

回應範例

"HTTP/1.1 200 OK[\r][\n]"
"x-amzn-RequestId: cc8b34af-cebb-11e6-a35c-55f3a992f28d[\r][\n]"
"x-amz-lex-message: Sorry, can you repeat that?[\r][\n]"
"x-amz-lex-dialog-state: ElicitIntent[\r][\n]"
"x-amz-lex-session-attributes: eyJ1c2VyTmFtZSI6IkJvYiJ9[\r][\n]"
"Content-Type: audio/mpeg[\r][\n]"
"Transfer-Encoding: chunked[\r][\n]"
"Date: Fri, 30 Dec 2016 18:14:28 GMT[\r][\n]"
"[\r][\n]"               
"2000[\r][\n]"
"ID3[0x4][0x0][0x0][0x0][0x0][0x0]#TSSE[0x0][0x0][0x0][0xf][0x0][0x0][0x3]Lavf57.41.100[0x0][0x0][0x0][0x0][0x0][0x0][0x0][0x0][0x0][0x0][0x0][0xff][0xf3]`[0xc4][0x0][0x1b]{[0x8d][0xe8][0x1]C[0x18][0x1][0x0]J[0xe0]`b[0xdd][0xd1][0xb][0xfd][0x11][0xdf][0xfe]";[0xbb][0xbb][0x9f][0xee][0xee][0xee][0xee]|DDD/[0xff][0xff][0xff][0xff]www?D[0xf7]w^?[0xff][0xfa]h[0x88][0x85][0xfe][0x88][0x88][0x88][[0xa2]'[0xff][0xfa]"{[0x9f][0xe8][0x88]]D[0xeb][0xbb][0xbb][0xa2]!u[0xfd][0xdd][0xdf][0x88][0x94][0x0]F[0xef][0xa1]8[0x0][0x82]w[0x88]N[0x0][0x0][0x9b][0xbb][0xe8][0xe
…

另請參閱

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