PutBot - Amazon Lex V1

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

 

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

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

PutBot

建立 Amazon Lex 交談機器人或取代現有的機器人。當您建立或更新機器人時,您只需要指定名稱、地區設定,以及是否將機器人導向 13 歲以下的兒童。您可以使用此功能稍後新增意圖,或從現有機器人中移除意圖。當您使用最少的資訊建立機器人時,系統會建立或更新機器人,但 Amazon Lex 會傳回回FAILED。您可以在新增一或多個意圖之後建立機器人。如需 Amazon Lex 機器人的詳細資訊,請參閱Amazon Lex 運作方式

如果您指定現有機器人的名稱,請求中的欄位會取代機器人$LATEST版本中的現有值。Amazon Lex 會移除您在請求中未提供值的任何欄位,但idleTTLInSecondsprivacySettings欄位設定為其預設值除外。如果您未指定必要欄位的值,Amazon Lex 會擲回例外狀況。

這項操作需要 lex:PutBot 動作的許可。如需詳細資訊,請參閱 Amazon Lex 的 Identity and Access Management

請求語法

PUT /bots/name/versions/$LATEST HTTP/1.1 Content-type: application/json { "abortStatement": { "messages": [ { "content": "string", "contentType": "string", "groupNumber": number } ], "responseCard": "string" }, "checksum": "string", "childDirected": boolean, "clarificationPrompt": { "maxAttempts": number, "messages": [ { "content": "string", "contentType": "string", "groupNumber": number } ], "responseCard": "string" }, "createVersion": boolean, "description": "string", "detectSentiment": boolean, "enableModelImprovements": boolean, "idleSessionTTLInSeconds": number, "intents": [ { "intentName": "string", "intentVersion": "string" } ], "locale": "string", "nluIntentConfidenceThreshold": number, "processBehavior": "string", "tags": [ { "key": "string", "value": "string" } ], "voiceId": "string" }

URI 請求參數

請求會使用下列 URI 參數。

name

機器人的名稱。名稱區分大小寫。

長度約束:最小長度為 2。長度上限為 50。

模式:^([A-Za-z]_?)+$

必要:是

請求主體

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

abortStatement

當 Amazon Lex 無法瞭解使用者在內容中的輸入時,它會嘗試幾次引出資訊。之後,Amazon Lex 會將中abortStatement定義的訊息傳送給使用者,然後取消對話。若要設定重試次數,請使用插槽類型的valueElicitationPrompt欄位。

例如,在披薩訂購機器人中,Amazon Lex 可能會詢問使用者「您想要什麼類型的外殼?」 如果使用者的回應不是預期的回應之一 (例如,「薄殼」、「深盤」等),Amazon Lex 會嘗試再次引出正確的回應。

例如,在比薩餅訂購應用程序中,OrderPizza可能是意圖之一。此意圖可能需要CrustType插槽。您可以在建立CrustType插槽時指定valueElicitationPrompt欄位。

如果您已定義後援意圖,則不會將 cancel 陳述式傳送給使用者,則會改用後援意圖。如需詳細資訊,請參閱 AMAZON。 FallbackIntent

類型:Statement 物件

必要:否

checksum

識別版本的特定修訂$LATEST版本。

當您建立新的機器人時,請將checksum欄位留空。如果你指定一個校驗和,你會得到一個BadRequestException異常。

當您想要更新機器人時,請將checksum欄位設定為該版本最新修訂$LATEST版的總和檢查碼。如果您未指定 checksum欄位,或者總和檢查碼與$LATEST版本不相符,則會出現PreconditionFailedException例外狀況。

類型:字串

必要:否

childDirected

對於使用 Amazon Lex 模型建置服務建立的每個 Amazon Lex 機器人,您必須在childDirected欄位中指定或全部或部分針對 13 歲以下兒童並遵守《兒童線上隱私保護法》(COPPA) 的網站、程式或其他應用程式是否與全部或部分導向或鎖定目標的網站、程式true或其他應用程false式相關。透過truechildDirected欄位中指定,即表示您確認您對 Amazon Lex 的使用與針對 13 歲以下兒童且受 COPPA 規範的全部或部分針對網站、程式或其他應用程式有關。透過falsechildDirected欄位中指定,即表示您確認您對 Amazon Lex 的使用與針對 13 歲以下兒童且受 COPPA 規範的全部或部分針對網站、程式或其他應用程式關。您不得為欄位指定預設值,該childDirected欄位無法準確反映您對 Amazon Lex 的使用情況是否與針對 13 歲以下兒童的網站、程式或其他應用程式全部或部分針對 13 歲以下且受 COPPA 規限的網站、程式或其他應用程式有關。

如果您對 Amazon Lex 的使用涉及全部或部分針對 13 歲以下兒童的網站、程式或其他應用程式,您必須根據 COPPA 取得任何必要的可驗證父母同意。如需針對全部或部分針對 13 歲以下兒童的網站、程式或其他應用程式使用 Amazon Lex 的相關資訊,請參閱 Amazon Lex 常見問題集。

類型:布林值

必要:是

clarificationPrompt

當 Amazon Lex 不瞭解使用者的意圖時,會使用此訊息來取得說明。若要指定 Amazon Lex 應重複說明提示的次數,請使用此maxAttempts欄位。如果 Amazon Lex 仍然無法理解,它會在abortStatement欄位中傳送訊息。

當您創建澄清提示時,請確保它建議用戶的正確響應。例如,對於訂購比薩餅和飲料的機器人,您可能會創建此澄清提示:「您想要做什麼? 您可以說「點一份比薩餅」或「點一杯飲料」。

如果您已經定義了一個後備意圖,如果澄清提示重複了maxAttempts字段中定義的次數,則會調用它。如需詳細資訊,請參閱 AMAZON。 FallbackIntent

如果您未定義澄清提示,在執行階段 Amazon Lex 會在下列三種情況下傳回 400 錯誤請求例外狀況:

  • 後續提示-當用戶響應後續提示但不提供意圖時。例如,回應後續提示:「您今天還想要什麼嗎?」 用戶說「是」。Amazon Lex 將傳回 400 錯誤請求例外狀況,因為它沒有要傳送給使用者以取得意圖的澄清提示。

  • Lambda 函數-使用 Lambda 函數時,您會返回一個ElicitIntent對話框類型。由於 Amazon Lex 沒有向使用者取得意圖的澄清提示,因此會傳回 400 個錯誤請求例外狀況。

  • PutSession 操作-使用PutSession操作時,您會發送對ElicitIntent話框類型。由於 Amazon Lex 沒有向使用者取得意圖的澄清提示,因此會傳回 400 個錯誤請求例外狀況。

類型:Prompt 物件

必要:否

createVersion

當設置為true一個新的編號版本的機器人被創建。這與呼叫作CreateBotVersion業相同。如果未指定createVersion,則預設值為false

類型:布林值

必要:否

description

機器人的描述。

類型:字串

長度限制:長度下限為 0。長度上限為 200。

必要:否

detectSentiment

設定為true使用者的話語時,會傳送至 Amazon Comprehend 進行情緒分析。如果未指定detectSentiment,則預設值為false

類型:布林值

必要:否

enableModelImprovements

設定為true以啟用存取自然語言理解改進功能。

enableModelImprovements參數設定為時,true您可以使用nluIntentConfidenceThreshold參數來設定可信度分數。如需詳細資訊,請參閱可信度分數

您只能在特定區域中設定enableModelImprovements參數。如果您將參數設定為true,您的機器人可以存取精確度改進。

您可以將 en-US 地區設定enableModelImprovements參數設定false為的區域包括:

  • 美國東部 (維吉尼亞北部) (us-east-1)

  • 美國西部 (奧勒岡) (us-west-2)

  • 亞太區域 (雪梨) (ap-southeast-2)

  • 歐洲 (愛爾蘭) (eu-west-1)

在其他區域和地區設定中,enableModelImprovements參數預設會設true定為。在這些區域和語言環境中設置參數false拋出ValidationException異常。

類型:布林值

必要:否

idleSessionTTLInSeconds

Amazon Lex 保留交談中收集之資料的時間上限 (以秒為單位)。

使用者互動工作階段會在指定的時間內保持作用中狀態。若在此期間沒有發生任何對話,則工作階段會過期,且 Amazon Lex 會刪除逾時之前提供的任何資料。

例如,假設用戶選擇了 OrderPizza 意圖,但通過下訂單而被側面跟踪。如果使用者未在指定的時間內完成訂單,Amazon Lex 會捨棄收集的插槽資訊,使用者必須重新開始。

如果您沒有在PutBot操作請求中包含idleSessionTTLInSeconds元素,Amazon Lex 會使用預設值。如果要求取代現有的機器人,這也是如此。

預設值為 300 秒 (5 分鐘)。

類型:整數

有效範圍:最小值為 60。最大值為 86400。

必要:否

intents

Intent 物件的陣列。每個意圖代表一個用戶可以表達的命令。例如,披薩訂購機器人可能支持 OrderPizza 意圖。如需詳細資訊,請參閱 Amazon Lex 運作方式

類型:Intent 物件陣列

必要:否

locale

指定機器人的目標地區設定。機器人中使用的任何意圖都必須與機器人的語言環境相容。

預設值為 en-US

類型:字串

有效值:de-DE | en-AU | en-GB | en-IN | en-US | es-419 | es-ES | es-US | fr-FR | fr-CA | it-IT | ja-JP | ko-KR

必要:是

nluIntentConfidenceThreshold

決定 Amazon Lex 在或回PostText應中傳回替代意圖時插入AMAZON.KendraSearchIntentPostContent或兩者的閾值。AMAZON.FallbackIntent AMAZON.FallbackIntent並且僅AMAZON.KendraSearchIntent在為機器人配置了它們時才會插入。

您必須將enableModelImprovements參數設定為,才true能在下列區域中使用可信度分數。

  • 美國東部 (維吉尼亞北部) (us-east-1)

  • 美國西部 (奧勒岡) (us-west-2)

  • 亞太區域 (雪梨) (ap-southeast-2)

  • 歐洲 (愛爾蘭) (eu-west-1)

在其他區域中,true依預設會將enableModelImprovements參數設定為。

例如,假設機器人的信賴度閾值設定為 0.80 和. AMAZON.FallbackIntent Amazon Lex 返回三個具有以下置信度分數的替代意圖:意圖(0.70),意圖 TB(0.60),意圖等(0.50)。來自PostText操作的響應將是:

  • 亞馬遜。 FallbackIntent

  • 意圖

  • IntenTB

  • IntenTC

類型:Double

有效範圍:最小值為 0。最大值為 1。

必要:否

processBehavior

如果將processBehavior元素設定為BUILD,Amazon Lex 會建立機器人以便執行該機器人。如果將元素設置為 SAVE Amazon Lex,則可以保存機器人,但不構建它。

如果未指定此值,則預設值為BUILD

類型:字串

有效值:SAVE | BUILD

必要:否

tags

要新增至機器人的標籤清單。您只能在創建機器人時添加標籤,無法使用該PutBot操作更新機器人上的標籤。若要更新標籤,請使用 TagResource 操作。

類型:Tag 物件陣列

陣列成員:項目數下限為 0。項目數上限為 200。

必要:否

voiceId

您希望 Amazon Lex 用於與使用者進行語音互動的 Amazon Polly 語音識別碼。為語音設定的語言環境必須與機器人的地區設定相符。如需詳細資訊,請參閱 Amazon Polly 開發人員指南中的 Amazon Polly 中的聲音

類型:字串

必要:否

回應語法

HTTP/1.1 200 Content-type: application/json { "abortStatement": { "messages": [ { "content": "string", "contentType": "string", "groupNumber": number } ], "responseCard": "string" }, "checksum": "string", "childDirected": boolean, "clarificationPrompt": { "maxAttempts": number, "messages": [ { "content": "string", "contentType": "string", "groupNumber": number } ], "responseCard": "string" }, "createdDate": number, "createVersion": boolean, "description": "string", "detectSentiment": boolean, "enableModelImprovements": boolean, "failureReason": "string", "idleSessionTTLInSeconds": number, "intents": [ { "intentName": "string", "intentVersion": "string" } ], "lastUpdatedDate": number, "locale": "string", "name": "string", "nluIntentConfidenceThreshold": number, "status": "string", "tags": [ { "key": "string", "value": "string" } ], "version": "string", "voiceId": "string" }

回應元素

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

服務會傳回下列 JSON 格式的資料。

abortStatement

Amazon Lex 用來取消對話的訊息。如需詳細資訊,請參閱 PutBot

類型:Statement 物件

checksum

您建立的機器人的總和檢查碼。

類型:字串

childDirected

對於使用 Amazon Lex 模型建置服務建立的每個 Amazon Lex 機器人,您必須在childDirected欄位中指定或全部或部分針對 13 歲以下兒童並遵守《兒童線上隱私保護法》(COPPA) 的網站、程式或其他應用程式是否與全部或部分導向或鎖定目標的網站、程式true或其他應用程false式相關。透過truechildDirected欄位中指定,即表示您確認您對 Amazon Lex 的使用與針對 13 歲以下兒童且受 COPPA 規範的全部或部分針對網站、程式或其他應用程式有關。透過falsechildDirected欄位中指定,即表示您確認您對 Amazon Lex 的使用與針對 13 歲以下兒童且受 COPPA 規範的全部或部分針對網站、程式或其他應用程式關。您不得為欄位指定預設值,該childDirected欄位無法準確反映您對 Amazon Lex 的使用情況是否與針對 13 歲以下兒童的網站、程式或其他應用程式全部或部分針對 13 歲以下且受 COPPA 規限的網站、程式或其他應用程式有關。

如果您對 Amazon Lex 的使用涉及全部或部分針對 13 歲以下兒童的網站、程式或其他應用程式,您必須根據 COPPA 取得任何必要的可驗證父母同意。如需針對全部或部分針對 13 歲以下兒童的網站、程式或其他應用程式使用 Amazon Lex 的相關資訊,請參閱 Amazon Lex 常見問題集。

類型:布林值

clarificationPrompt

Amazon Lex 在不了解使用者意圖時所使用的提示。如需詳細資訊,請參閱 PutBot

類型:Prompt 物件

createdDate

建立機器人的日期。

類型:Timestamp

createVersion

True如果創建了新版本的機器人。如果未在請求中指定該字createVersion段,則該createVersion字段在響應中設置為 false。

類型:布林值

description

機器人的描述。

類型:字串

長度限制:長度下限為 0。長度上限為 200。

detectSentiment

true如果機器人設定為將使用者話語傳送至 Amazon Comprehend 進行情緒分析。如果未在請求中指定該字detectSentiment段,則該detectSentiment字段false在響應中。

類型:布林值

enableModelImprovements

指出機器人是否使用精確度改進。 true表示機器人正在使用改進,否則,false

類型:布林值

failureReason

如果statusFAILED,Amazon Lex 會提供無法建置機器人的原因。

類型:字串

idleSessionTTLInSeconds

Amazon Lex 保留交談中收集之資料的最長時間長度。如需詳細資訊,請參閱 PutBot

類型:整數

有效範圍:最小值為 60。最大值為 86400。

intents

Intent 物件的陣列。如需詳細資訊,請參閱 PutBot

類型:Intent 物件陣列

lastUpdatedDate

機器人更新的日期。建立資源時,建立日期和上次更新日期相同。

類型:Timestamp

locale

機器人的目標地區設定。

類型:字串

有效值:de-DE | en-AU | en-GB | en-IN | en-US | es-419 | es-ES | es-US | fr-FR | fr-CA | it-IT | ja-JP | ko-KR

name

機器人的名稱。

類型:字串

長度約束:最小長度為 2。長度上限為 50。

模式:^([A-Za-z]_?)+$

nluIntentConfidenceThreshold

決定 Amazon Lex 在或回PostText應中傳回替代意圖時插入AMAZON.FallbackIntentAMAZON.KendraSearchIntent、或兩者的位置的PostContent分數。 AMAZON.FallbackIntent如果所有意圖的可信度分數低於此值,則會插入。 AMAZON.KendraSearchIntent只有在為機器人配置時才會插入。

類型:Double

有效範圍:最小值為 0。最大值為 1。

status

當您傳送建立機器人的請求時BUILD,Amazon Lex 會將status回應元素processBehavior設定為BUILDING

在該READY_BASIC_TESTING狀態下,您可以使用與插槽類型中機器人意圖和值配置的話語完全匹配的用戶輸入來測試機器人。

如果 Amazon Lex 無法構建機器人,Amazon Lex 設置statusFAILED。Amazon Lex 返回failureReason響應元素失敗的原因。

當您設定processBehavior為時SAVE,Amazon Lex 會將狀態碼設定為NOT BUILT

當機器人處於READY狀態時,您可以測試並發佈機器人。

類型:字串

有效值:BUILDING | READY | READY_BASIC_TESTING | FAILED | NOT_BUILT

tags

與機器人相關聯的標籤列表。

類型:Tag 物件陣列

陣列成員:項目數下限為 0。項目數上限為 200。

version

機器人的版本。對於新的機器人,版本始終是$LATEST

類型:字串

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

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

voiceId

亞馬遜 Lex 用於與用戶進行語音交互的 Amazon Polly 語音 ID。如需詳細資訊,請參閱 PutBot

類型:字串

錯誤

BadRequestException

請求的格式不正確。例如,值無效或缺少必填欄位。請檢查欄位值,然後再試一次。

HTTP 狀態碼:400

ConflictException

處理要求時發生衝突。請再次嘗試您的請求。

HTTP 狀態碼:409

InternalFailureException

發生內部 Amazon Lex 錯誤。請再次嘗試您的請求。

HTTP 狀態碼:500

LimitExceededException

請求超過限制。請再次嘗試您的請求。

HTTP 狀態碼:429

PreconditionFailedException

您嘗試變更之資源的總和檢查碼與要求中的總和檢查碼不符。檢查資源的總和檢查碼,然後再試一次。

HTTP 狀態碼:412

另請參閱

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