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 欄位。

如果您已定義備用意圖，則不會將取消陳述式傳送給使用者，而是改用備用意圖。如需詳細資訊，請參閱 AMAZON.FallbackIntent。

類型：Statement 物件

必要：否

checksum

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

當您建立新的機器人時，請將 checksum 欄位保留空白。如果您指定檢查總和，您會收到BadRequestException例外狀況。

當您想要更新機器人時，請將 checksum 欄位設定為$LATEST最新版本的檢查總和。如果您未指定 checksum 欄位，或檢查總和與$LATEST版本不相符，您會收到PreconditionFailedException例外狀況。

類型：字串

必要：否

childDirected

對於使用 Amazon Lex Model Building Service 建立的每個 Amazon Lex 機器人，您必須指定您對 Amazon Lex 的使用是否與網站、程式或其他應用程式相關，而該網站、程式或其他應用程式全部或部分針對 13 以下兒童，並在 false childDirected 欄位中指定 true 或以遵守兒童線上隱私權保護法 (COPPA)。透過true在 childDirected 欄位中指定，您確認使用 Amazon Lex 與網站、程式或其他應用程式相關，而該網站、程式或其他應用程式全部或部分以未滿 13 歲且受 COPPA 規範。透過false在 childDirected 欄位中指定，您確認 Amazon Lex 的使用與網站、程式或其他應用程式無關，該網站、程式或其他應用程式全部或部分以未滿 13 歲且受 COPPA 規範。您不能為 childDirected 欄位指定預設值，該值無法準確反映您對 Amazon Lex 的使用是否與網站、程式或其他應用程式相關，而該網站、程式或其他應用程式是針對或部分針對未滿 13 歲且受 COPPA 規範的 13 歲兒童。

如果您使用 Amazon Lex 與全部或部分導向的網站、程式或其他應用程式有關，且與未滿 13 歲兒童有關，則必須根據 COPPA 取得任何必要的可驗證父系同意。如需將 Amazon Lex 與網站、程式或其他應用程式搭配使用的相關資訊，而這些網站、程式或其他應用程式全部或部分針對未滿 13 歲的孩童，請參閱 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。

類型：字串

必要：是

nluIntentConfidenceThreshold

決定在 PostContent 或 PostText 回應中傳回替代意圖時AMAZON.FallbackIntent，Amazon Lex 將插入 AMAZON.KendraSearchIntent、或兩者的閾值。 AMAZON.FallbackIntent和 AMAZON.KendraSearchIntent 只有在為機器人設定時才插入。

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

美國東部 (維吉尼亞北部) (us-east-1)
美國西部 (奧勒岡) (us-west-2)
亞太區域 (雪梨) (ap-southeast-2)
歐洲 (愛爾蘭) (eu-west-1)

在其他區域中， enableModelImprovements 參數true預設為。

例如，假設機器人的可信度閾值設定為 0.80 和 AMAZON.FallbackIntent。Amazon Lex 傳回具有下列可信度分數的三種替代意圖：IntentA (0.70)、IntentB (0.60)、IntentC (0.50)。PostText 操作的回應將是：

AMAZON.FallbackIntent
IntentA
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 語音 ID。 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 Model Building Service 建立的每個 Amazon Lex 機器人，您必須指定您對 Amazon Lex 的使用是否與網站、程式或其他應用程式相關，而該網站、程式或其他應用程式全部或部分針對 13 以下兒童，並在 false childDirected 欄位中指定 true 或以遵守兒童線上隱私權保護法 (COPPA)。透過true在 childDirected 欄位中指定，您確認使用 Amazon Lex 與網站、程式或其他應用程式相關，而該網站、程式或其他應用程式全部或部分以 13 以下兒童為目標，並受 COPPA 約束。透過false在 childDirected 欄位中指定，您確認 Amazon Lex 的使用與網站、程式或其他應用程式無關，而該網站、程式或其他應用程式全部或部分針對 13 以下且受 COPPA 約束的兒童。您不能為 childDirected 欄位指定預設值，該值無法準確反映您對 Amazon Lex 的使用是否與網站、程式或其他應用程式相關，而該網站、程式或其他應用程式是針對或部分針對未滿 13 歲且受 COPPA 規範的 13 歲兒童。

如果您使用 Amazon Lex 與全部或部分導向的網站、程式或其他應用程式有關，且與未滿 13 歲兒童有關，則必須根據 COPPA 取得任何必要的可驗證父系同意。如需有關使用 Amazon Lex 與網站、程式或其他應用程式相關的資訊，而這些應用程式是針對或部分針對 13 以下兒童，請參閱 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

機器人的目標地區設定。

類型：字串

name

機器人的名稱。

類型：字串

長度限制：長度下限為 2。長度上限為 50。

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

nluIntentConfidenceThreshold

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

類型：Double

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

status

當您傳送建立將 processBehavior設定為之機器人的請求時BUILD，Amazon Lex 會將status回應元素設定為 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

tags

與機器人相關聯的標籤清單。

類型：Tag 物件陣列

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

version

機器人的版本。對於新的機器人，版本一律為 $LATEST。

類型：字串

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

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

voiceId

Amazon Lex 用來與使用者進行語音互動的 Amazon Polly 語音 ID。如需詳細資訊，請參閱PutBot。

類型：字串

錯誤

BadRequestException

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

HTTP 狀態碼：400

ConflictException

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

HTTP 狀態碼：409

InternalFailureException

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

HTTP 狀態碼：500

LimitExceededException

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

HTTP 狀態碼：429

PreconditionFailedException

您嘗試變更的資源檢查總和與請求中的檢查總和不相符。請檢查資源的檢查總和，然後再試一次。

HTTP 狀態碼：412

另請參閱

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

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

ListTagsForResource

PutBotAlias