PutSession

使用 Amazon Lex 機器人建立一個新的工作階段或修改現有的工作階段。使用此作業可讓您的應用程式設定機器人的狀態。

如需詳細資訊，請參閱管理工作階段。

請求語法

POST /bot/botName/alias/botAlias/user/userId/session HTTP/1.1
Accept: accept
Content-type: application/json

{
   "activeContexts": [ 
      { 
         "name": "string",
         "parameters": { 
            "string" : "string" 
         },
         "timeToLive": { 
            "timeToLiveInSeconds": number,
            "turnsToLive": number
         }
      }
   ],
   "dialogAction": { 
      "fulfillmentState": "string",
      "intentName": "string",
      "message": "string",
      "messageFormat": "string",
      "slots": { 
         "string" : "string" 
      },
      "slotToElicit": "string",
      "type": "string"
   },
   "recentIntentSummaryView": [ 
      { 
         "checkpointLabel": "string",
         "confirmationStatus": "string",
         "dialogActionType": "string",
         "fulfillmentState": "string",
         "intentName": "string",
         "slots": { 
            "string" : "string" 
         },
         "slotToElicit": "string"
      }
   ],
   "sessionAttributes": { 
      "string" : "string" 
   }
}

URI 請求參數

請求會使用下列 URI 參數。

accept

Amazon Lex 在回應中傳回的訊息可以是文字或語音，視此欄位的值而定。

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

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

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

• 以下是可接受的值：

  • audio/mpeg

  • audio/ogg

  • audio/pcm

  • audio/*（默認為 MPEG）

  • text/plain; charset=utf-8

botAlias

包含工作階段資料之機器人使用的別名。

必要：是

botName

包含工作階段資料的機器人名稱。

必要：是

userId

用戶端應用程式使用者的識別碼。Amazon Lex 使用此功能來識別使用者與您的機器人的對話。

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

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

必要：是

請求主體

請求接受採用 JSON 格式的下列資料。

activeContexts

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

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

類型：ActiveContext 物件陣列

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

必要：否

dialogAction

設定機器人完成對話時應採取的下一個動作。

類型：DialogAction 物件

必要：否

recentIntentSummaryView

機器人最近意圖的摘要。您可以使用意圖摘要檢視來設定意圖上的檢查點標籤，並修改意圖的屬性。您也可以使用它來移除意圖摘要物件，或將意圖摘要物件新增至清單。

您修改或新增至清單的意圖對於機器人來說必須有意義。例如，意圖名稱必須對機器人有效。您必須提供下列項目的有效值：

• intentName

• 插槽名稱

• slotToElict

如果您在要PutSession求中傳送recentIntentSummaryView參數，則新摘要檢視的內容會取代舊的摘要檢視。例如，如果GetSession請求在摘要視圖中返回三個意圖，並且您在摘要視圖中以一個意圖調PutSession用，則下一次調用GetSession將只返回一個意圖。

類型：IntentSummary 物件陣列

陣列成員：項目數下限為 0。3 個項目的最大數量。

必要：否

sessionAttributes

表示會話特定上下文信息的鍵/值對的映射。它包含 Amazon Lex 和用戶端應用程式之間傳遞的應用程式資訊。

類型：字串到字串映射

必要：否

回應語法

HTTP/1.1 200
Content-Type: contentType
x-amz-lex-intent-name: intentName
x-amz-lex-slots: slots
x-amz-lex-session-attributes: sessionAttributes
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-session-id: sessionId
x-amz-lex-active-contexts: activeContexts

audioStream

回應元素

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

回應會傳回下列 HTTP 標頭。

activeContexts

工作階段的使用中前後關聯清單。

contentType

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

dialogState

• ConfirmIntent-Amazon Lex 預期「是」或「否」回應，以便在完成意圖之前確認意圖。

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

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

• Failed-傳達與使用者的對話失敗。發生這種情況的原因有多種，包括使用者未針對服務的提示提示提供適當的回應，或是 Lambda 函數無法達成意圖。

• Fulfilled-傳達 Lambda 函數已成功實現意圖。

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

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

encodedMessage

應該向用戶顯示的下一條消息。

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

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

intentName

目前意圖的名稱。

message

此標頭已被棄用。

應該向用戶顯示的下一條消息。

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

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

messageFormat

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

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

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

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

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

有效值:PlainText | CustomPayload | SSML | Composite

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 引出值的插槽名稱。

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

audioStream

要傳達給使用者的訊息的音訊版本。

錯誤

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

NotAcceptableException

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

狀態碼：

NotFoundException

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

HTTP 狀態碼：404

另請參閱

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

• AWS 命令列介面

• AWS SDK for .NET

• AWS SDK for C++

• AWS 適用於轉到 V2 的 SDK

• AWS SDK for Java V2 的开发

• AWS 適用於 JavaScript V3 的 SDK

• AWS SDK for PHP

• AWS 適用於 Python 的 SDK

• AWS 適用於紅寶石 V3 的 SDK