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 字段。

如果您定义了回退意图，则不会向用户发送取消语句，而是使用回退意图。有关更多信息，请参阅亚马逊。 FallbackIntent。

类型：Statement 对象

必需：否

checksum

标识 $LATEST 版本的特定修订版。

创建新机器人时，请将 checksum 字段留空。如果指定校验和，则会出现 BadRequestException 异常。

当您想更新机器人时，请将 checksum 字段设置为 $LATEST 版本最新修订版的校验和。如果您未指定 checksum 字段，或者校验和与 $LATEST 版本不匹配，则会出现 PreconditionFailedException 异常。

类型：字符串

必需：否

childDirected

对于使用 Amazon Lex 模型构建服务创建的每个 Amazon Lex 机器人，您都必须通过在 childDirected 字段中指定 true 或 false，指定您对 Amazon Lex 的使用是否与全部或部分针对 13 岁以下儿童且受《儿童在线隐私保护法》(COPPA) 约束的网站、程序或其他应用程序有关。在 childDirected 字段中指定 true，即表示您确认您对 Amazon Lex 的使用确实与全部或部分针对 13 岁以下儿童且受 COPPA 约束的网站、计划或其他应用程序有关。在 childDirected 字段中指定 false，即表示您确认您对 Amazon Lex 的使用不与全部或部分针对 13 岁以下儿童且受 COPPA 约束的网站、计划或其他应用程序有关。如果在 childDirected 字段中指定默认值不能正确反映您确认您对 Amazon Lex 的使用不与全部或部分针对 13 岁以下儿童且受 COPPA 约束的网站、计划或其他应用程序有关，则您可以不指定。

如果您对 Amazon Lex 的使用涉及全部或部分针对 13 岁以下儿童的网站、程序或其他应用程序，则必须获得 COPPA 规定的任何必需的可核实的家长同意。有关将 Amazon Lex 用于全部或部分针对 13 岁以下儿童的网站、程序或其他应用程序的信息，请参阅 Amazon Lex 常见问题解答。

类型：布尔值

必需：是

clarificationPrompt

当 Amazon Lex 不了解用户的意图时，它会使用此消息进行澄清。要指定 Amazon Lex 应重复多少次澄清提示，请使用 maxAttempts 字段。如果 Amazon Lex 仍然无法理解，它会发送 abortStatement 字段中的消息。

当您创建澄清提示时，请确保它建议用户做出正确的响应。例如，对于订购披萨和饮品的机器人，您可以创建这样的澄清提示：“您想做什么？您可以说“订一杯饮品”或“订一个披萨”。

如果您定义了回退意图，则如果重复澄清提示的次数达到 maxAttempts 字段中定义的次数，则会调用该意图。有关更多信息，请参阅亚马逊。 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

确定在或PostText响应中返回替代意图时 AMAZON.FallbackIntentAMAZON.KendraSearchIntent，Amazon Lex 将在何处插入、PostContent或两者的阈值。 AMAZON.FallbackIntentAMAZON.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 操作的响应将是：

亚马逊。 FallbackIntent
IntentA
IntentB
IntentC

类型：双精度

有效范围：最小值为 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 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

类型：布尔值

clarificationPrompt

Amazon Lex 在无法理解用户的请求时使用的提示。有关更多信息，请参阅 PutBot。

类型：Prompt 对象

createdDate

机器人的创建日期。

类型：时间戳

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

机器人的更新日期。创建资源时，创建日期和上次更新日期相同。

类型：时间戳

locale

机器人的目标区域设置。

类型：字符串

name

机器人的名称。

类型：字符串

长度限制：最小长度为 2。最大长度为 50。

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

nluIntentConfidenceThreshold

该分数决定 Amazon Lex 在或PostText响应中返回替代意图时在何处插入AMAZON.KendraSearchIntent、PostContent或两者。AMAZON.FallbackIntent AMAZON.FallbackIntent如果实际可信度分数低于此值，则会插入。 AMAZON.KendraSearchIntent只有在为机器人配置时才会插入。

类型：双精度

有效范围：最小值为 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

另请参阅

有关以特定语言之一使用此 API 的更多信息 AWS SDKs，请参阅以下内容：

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

ListTagsForResource

PutBotAlias