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

支援終止通知：在 2025 年 9 月 15 日， AWS 將停止對 Amazon Lex V1 的支援。2025 年 9 月 15 日之後，您將無法再存取 Amazon Lex V1 主控台或 Amazon Lex V1 資源。如果您使用的是 Amazon Lex V2，請改參閱 Amazon Lex V2 指南。

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

PostContent

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

PostContent 操作支援 8kHz 和 16kHz 的音訊輸入。您可以使用 8kHz 音訊，在電話音訊應用程式中實現更高的語音辨識準確度。

為了回應，Amazon Lex 會傳回下一個訊息，以傳達給使用者。請考慮下列範例訊息：

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

  • 使用者提供所有比薩訂單資訊後，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，則傳回的語音audio/pcm為 16 位元、小端點格式。

  • 以下是可接受的值：

    • 音訊/mpeg

    • 音訊/霧

    • 音訊/pcm

    • text/plain； charset=utf-8

    • audio/* （預設為 mpeg)

activeContexts

請求作用中的內容清單。上一個意圖達成時，或將內容包含在請求中，即可啟用內容。

如果您未指定內容清單，Amazon Lex 將使用工作階段的目前內容清單。如果您指定空清單，工作階段的所有內容都會清除。

botAlias

Amazon Lex 機器人的別名。

必要：是

botName

Amazon Lex 機器人的名稱。

必要：是

contentType

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

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

  • PCM 格式的音訊資料必須採用小端位元組順序。

    • audio/l16； 速率 = 16000； 頻道 = 1

    • audio/x-l16； sample-rate=16000； channel-count=1

    • audio/lpcm； sample-rate=8000； sample-size-bits=16； channel-count=1； is-big-endian=false

  • Opus 格式

    • audio/x-cbr-opus-with-preamble；preamble-size=0； 位元速率=256000； frame-size-milliseconds=4

  • 文字格式

    • text/plain； charset=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

工作階段的作用中內容清單。滿足意圖或呼叫 PostContent、 或 PutSession操作時PostText，可以設定內容。

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

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 傳送此訊息：「您想要什麼大小的比薩？」。使用者可能會以槽值 （例如 "medium") 回覆。使用者也可能在回應中提供額外資訊 （例如，「中厚地殼比薩」)。Amazon Lex 可以適當地處理這類額外資訊。

  • Fulfilled - 傳達 Lambda 函數已成功滿足意圖。

  • ReadyForFulfillment - 傳達用戶端必須完成請求。

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

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

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

encodedInputTranscript

用於處理請求的文字。

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

encodedInputTranscript 欄位以 base-64 編碼。您必須解碼 欄位，才能使用 值。

encodedMessage

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

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

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

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

encodedMessage 欄位以 base-64 編碼。您必須解碼 欄位，才能使用 值。

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

inputTranscript

此標頭已棄用。

用於處理請求的文字。

您只能在 de-DE、en-AU、en-GB、en-US、es-419、es-ES、es-US、fr-CA、fr-FR 和 it-IT 區域中使用此欄位。在所有其他地區中， inputTranscript 欄位為 null。您應該改用 encodedInputTranscript 欄位。

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

intentName

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

message

此標頭已棄用。

您只能在 de-DE、en-AU、en-GB、en-US、es-419、es-ES、es-US、fr-CA、fr-FR 和 it-IT 區域中使用此欄位。在所有其他地區中， message 欄位為 null。您應該改用 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 的映射。欄位以 base-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 機器人和使用者 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

NotAcceptableException

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

HTTP 狀態碼：406

NotFoundException

找不到參考的資源 （例如 Amazon Lex 機器人或別名）。

HTTP 狀態碼：404

RequestTimeoutException

輸入語音太長。

HTTP 狀態碼：408

UnsupportedMediaTypeException

Content-Type 標頭 (PostContent API) 的值無效。

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 SDKs中使用此 API 的詳細資訊，請參閱下列內容：