如果您使用的是 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 會移除您在請求中未提供值的任何欄位,但idleTTLInSeconds
和privacySettings
欄位設定為其預設值除外。如果您未指定必要欄位的值,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
式相關。透過true
在childDirected
欄位中指定,即表示您確認您對 Amazon Lex 的使用與針對 13 歲以下兒童且受 COPPA 規範的全部或部分針對網站、程式或其他應用程式有關。透過false
在childDirected
欄位中指定,即表示您確認您對 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.KendraSearchIntent
、PostContent或兩者的閾值。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
必要:否
-
要新增至機器人的標籤清單。您只能在創建機器人時添加標籤,無法使用該
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
式相關。透過true
在childDirected
欄位中指定,即表示您確認您對 Amazon Lex 的使用與針對 13 歲以下兒童且受 COPPA 規範的全部或部分針對網站、程式或其他應用程式有關。透過false
在childDirected
欄位中指定,即表示您確認您對 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
-
如果
status
是FAILED
,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.FallbackIntent
AMAZON.KendraSearchIntent
、或兩者的位置的PostContent分數。AMAZON.FallbackIntent
如果所有意圖的可信度分數低於此值,則會插入。AMAZON.KendraSearchIntent
只有在為機器人配置時才會插入。類型:Double
有效範圍:最小值為 0。最大值為 1。
- status
-
當您傳送建立機器人的請求時
BUILD
,Amazon Lex 會將status
回應元素processBehavior
設定為BUILDING
。在該
READY_BASIC_TESTING
狀態下,您可以使用與插槽類型中機器人意圖和值配置的話語完全匹配的用戶輸入來測試機器人。如果 Amazon Lex 無法構建機器人,Amazon Lex 設置
status
為FAILED
。Amazon Lex 返回failureReason
響應元素失敗的原因。當您設定
processBehavior
為時SAVE
,Amazon Lex 會將狀態碼設定為NOT BUILT
。當機器人處於
READY
狀態時,您可以測試並發佈機器人。類型:字串
有效值:
BUILDING | READY | READY_BASIC_TESTING | FAILED | NOT_BUILT
-
與機器人相關聯的標籤列表。
類型: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 的詳細資訊,請參閱下列內容: