终止支持通知：2025年9月15日， AWS 我们将停止对Amazon Lex V1的支持。2025 年 9 月 15 日之后，您将无法再访问 Amazon Lex V1 控制台或 Amazon Lex V1 资源。如果您使用的是 Amazon Lex V2，请改为参阅 [Amazon Lex V2 指南](https://docs.aws.amazon.com/lexv2/latest/dg/what-is.html)。 本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # PutBot 创建 Amazon Lex 对话机器人或替换现有机器人。创建或更新机器人时，您只需要指定名称、区域以及机器人是否针对未满 13 岁的儿童即可。您可以使用它在稍后添加意图，或者从现有机器人中移除意图。当您使用最少的信息创建机器人时，会创建或更新该机器人，但是 Amazon Lex 会返回 `` 响应 `FAILED`。您可以在添加一个或多个意图后构建机器人。有关 Amazon Lex 的更多信息，请参阅[Amazon Lex：工作原理](how-it-works.md)。 如果您指定现有机器人的名称，则请求中的字段将替换机器人 `$LATEST` 版本中的现有值。Amazon Lex 会删除您未在请求中提供值的所有字段，但 `idleTTLInSeconds` 和 `privacySettings` 字段除外，会将它们设置为默认值。如果您没有为必填字段指定值，Amazon Lex 会引发异常。 此操作需要 `lex:PutBot` 操作的权限。有关更多信息，请参阅 [适用于 Amazon Lex 的 Identity and Access Management](security-iam.md)。 ## 请求语法 ``` 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](#API_PutBot_RequestSyntax) ** 机器人的名称。名称*不*区分大小写。 长度限制：最小长度为 2。最大长度为 50。 模式：`^([A-Za-z]_?)+$` 必需：是 ## 请求体 请求接受采用 JSON 格式的以下数据。 ** [abortStatement](#API_PutBot_RequestSyntax) ** 当 Amazon Lex 无法理解用户在上下文中的输入时，它会尝试几次引发信息。之后，Amazon Lex 将在 `abortStatement` 中定义的消息发送给用户，然后取消对话。要设置重试次数，请使用插槽类型的 `valueElicitationPrompt` 字段。 例如，在订购披萨机器人中，Amazon Lex 可能会问用户“您想要什么类型的饼皮？” 如果用户的响应不是预期的响应之一（例如，“薄皮”、“深盘”等），Amazon Lex 会尝试几次引发正确的响应。 例如，在订购披萨应用程序中，`OrderPizza` 可能是意图之一。此意图可能需要 `CrustType` 插槽。您可以在创建 `CrustType` 插槽时指定 `valueElicitationPrompt` 字段。 如果您定义了回退意图，则不会向用户发送取消语句，而是使用回退意图。有关更多信息，请参阅[亚马逊。 FallbackIntent](https://docs.aws.amazon.com/lex/latest/dg/built-in-intent-fallback.html)。 类型：[Statement](API_Statement.md) 对象 必需：否 ** [checksum](#API_PutBot_RequestSyntax) ** 标识 `$LATEST` 版本的特定修订版。 创建新机器人时，请将 `checksum` 字段留空。如果指定校验和，则会出现 `BadRequestException` 异常。 当您想更新机器人时，请将 `checksum` 字段设置为 `$LATEST` 版本最新修订版的校验和。如果您未指定 ` checksum` 字段，或者校验和与 `$LATEST` 版本不匹配，则会出现 `PreconditionFailedException` 异常。 类型：字符串 必需：否 ** [childDirected](#API_PutBot_RequestSyntax) ** 对于使用 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 常见问题解答](https://aws.amazon.com/lex/faqs#data-security)。 类型：布尔值 是否必需：是 ** [clarificationPrompt](#API_PutBot_RequestSyntax) ** 当 Amazon Lex 不了解用户的意图时，它会使用此消息进行澄清。要指定 Amazon Lex 应重复多少次澄清提示，请使用 `maxAttempts` 字段。如果 Amazon Lex 仍然无法理解，它会发送 `abortStatement` 字段中的消息。 当您创建澄清提示时，请确保它建议用户做出正确的响应。例如，对于订购披萨和饮品的机器人，您可以创建这样的澄清提示：“您想做什么？ 您可以说“订一杯饮品”或“订一个披萨”。 如果您定义了回退意图，则如果重复澄清提示的次数达到 `maxAttempts` 字段中定义的次数，则会调用该意图。有关更多信息，请参阅[亚马逊。 FallbackIntent](https://docs.aws.amazon.com/lex/latest/dg/built-in-intent-fallback.html)。 如果您未定义澄清提示，则在运行时，Amazon Lex 将在三种情况下返回“400 错误请求”异常： + 后续提示 — 当用户响应后续提示但不提供意图时。例如，在响应“您今天还想要其他东西吗？”后续提示时，用户回答“是”。由于 Amazon Lex 没有发送给用户以获取用户意图的澄清提示，因此它会返回“400 错误请求”异常。 + Lambda 函数 — 使用 Lambda 函数时，您将返回 `ElicitIntent` 对话类型。由于 Amazon Lex 没有用于获取用户意图的澄清提示，因此它会返回“400 错误请求”异常。 + PutSession 操作-使用`PutSession`操作时，您可以发送`ElicitIntent`对话类型。由于 Amazon Lex 没有用于获取用户意图的澄清提示，因此它会返回“400 错误请求”异常。 类型：[Prompt](API_Prompt.md) 对象 必需：否 ** [createVersion](#API_PutBot_RequestSyntax) ** 当设置为 `true` 时，将创建机器人的新编号版本。这与调用 `CreateBotVersion` 操作相同。如果不指定 `createVersion`，则默认值为 `false`。 类型：布尔值 必需：否 ** [description](#API_PutBot_RequestSyntax) ** 机器人的描述。 类型：字符串 长度限制：最小长度为 0。最大长度为 200。 必需：否 ** [detectSentiment](#API_PutBot_RequestSyntax) ** 当设置为 `true` 时，会将用户言语发送到 Amazon Comprehend 进行情绪分析。如果不指定 `detectSentiment`，则默认值为 `false`。 类型：布尔值 必需：否 ** [enableModelImprovements](#API_PutBot_RequestSyntax) ** 设置为 `true` 以允许访问自然语言理解方面的改进。 当将 `enableModelImprovements` 参数设置为 `true` 时，可以使用 `nluIntentConfidenceThreshold` 参数配置置信度分数。有关更多信息，请参阅[置信度分数](https://docs.aws.amazon.com/lex/latest/dg/confidence-scores.html)。 您只能在某些区域中设置 `enableModelImprovements` 参数。如果将该参数设置为 `true`，则您的机器人可以获得准确性改进。 您可以针对 en-US 区域设置将 `enableModelImprovements` 参数设置为 `false` 的区域有： + 美国东部（弗吉尼亚州北部）(us-east-1) + 美国西部（俄勒冈州）(us-west-2) + 亚太地区（悉尼）(ap-southeast-2) + 欧洲（爱尔兰）(eu-west-1) 在其他区域和区域设置中，`enableModelImprovements` 参数默认设置为 `true`。在这些区域和区域设置中，将参数设置为 `false` 会引发 `ValidationException` 异常。 类型：布尔值 必需：否 ** [idleSessionTTLInSeconds](#API_PutBot_RequestSyntax) ** Amazon Lex 保留对话中收集的数据的最长时间（秒）。 用户交互会话在指定的时间内保持活动状态。如果在此期间未发生任何对话，则会话将过期并且 Amazon Lex 会删除在超时之前提供的所有数据。 例如，假设用户选择了 OrderPizza 意图，但在下单的中途被偏离了方向。如果用户未在指定时间内完成订单，Amazon Lex 会丢弃其收集的插槽信息，用户必须重新开始。 如果您未在 `PutBot` 操作请求中包含 `idleSessionTTLInSeconds` 元素，Amazon Lex 将使用默认值。如果请求替换现有的机器人，也是如此。 默认值为 300 秒（5 分钟）。 类型：整数 有效范围：最小值为 60。最大值为 86400。 必需：否 ** [intents](#API_PutBot_RequestSyntax) ** `Intent` 数据元数组。每个意图都代表一个用户可以表达的命令。例如，披萨订购机器人可能支持某种 OrderPizza 意图。有关更多信息，请参阅 [Amazon Lex：工作原理](how-it-works.md)。 类型：[Intent](API_Intent.md) 对象数组 必需：否 ** [locale](#API_PutBot_RequestSyntax) ** 指定机器人的目标区域设置。机器人中使用的任何意图都必须与机器人的区域设置兼容。 默认值为 `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](#API_PutBot_RequestSyntax) ** 确定在或[PostText](https://docs.aws.amazon.com/lex/latest/dg/API_runtime_PostText.html)响应中返回替代意图时 `AMAZON.FallbackIntent``AMAZON.KendraSearchIntent`，Amazon Lex 将在何处插入、[PostContent](https://docs.aws.amazon.com/lex/latest/dg/API_runtime_PostContent.html)或两者的阈值。 `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` 操作的响应将是： + 亚马逊。 FallbackIntent + IntentA + IntentB + IntentC 类型：双精度 有效范围：最小值为 0。最大值为 1。 必需：否 ** [processBehavior](#API_PutBot_RequestSyntax) ** 如果您将 `processBehavior` 元素设置为 `BUILD`，Amazon Lex 会构建机器人以便它可以运行。如果您将该元素设置为 `SAVE`，Amazon Lex 会保存机器人，但不会构建它。 如果您不指定此值，则默认值为 `BUILD`。 类型：字符串 有效值：`SAVE | BUILD` 必需：否 ** [tags](#API_PutBot_RequestSyntax) ** 要添加到自动程序的标签列表。您只能在创建机器人时添加标签，不能使用 `PutBot` 操作来更新机器人上的标签。要更新标签，请使用 `TagResource` 操作。 类型：[Tag](API_Tag.md) 对象数组 数组成员：最少 0 个物品。最多 200 项。 必需：否 ** [voiceId](#API_PutBot_RequestSyntax) ** 您希望 Amazon Lex 用于与用户进行语音交互的 Amazon Polly 语音 ID。为语音配置的区域设置必须与机器人的区域设置相匹配。有关更多信息，请参阅**《Amazon Polly 开发人员指南》中的 [Amazon Polly 中的语音](https://docs.aws.amazon.com/polly/latest/dg/voicelist.html)。 类型：字符串 必需：否 ## 响应语法 ``` 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](#API_PutBot_ResponseSyntax) ** Amazon Lex 用来取消对话的消息。有关更多信息，请参阅 [PutBot](#API_PutBot)。 类型：[Statement](API_Statement.md) 对象 ** [checksum](#API_PutBot_ResponseSyntax) ** 您创建的机器人的校验和。 类型：字符串 ** [childDirected](#API_PutBot_ResponseSyntax) ** 对于使用 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 常见问题解答](https://aws.amazon.com/lex/faqs#data-security)。 类型：布尔值 ** [clarificationPrompt](#API_PutBot_ResponseSyntax) ** Amazon Lex 在无法理解用户的请求时使用的提示。有关更多信息，请参阅 [PutBot](#API_PutBot)。 类型：[Prompt](API_Prompt.md) 对象 ** [createdDate](#API_PutBot_ResponseSyntax) ** 机器人的创建日期。 类型：时间戳 ** [createVersion](#API_PutBot_ResponseSyntax) ** `True`（如果创建了新版本的机器人）。如果请求中未指定 `createVersion` 字段，则在响应中将 `createVersion` 字段设置为 false。 类型：布尔值 ** [description](#API_PutBot_ResponseSyntax) ** 机器人的描述。 类型：字符串 长度限制：最小长度为 0。最大长度为 200。 ** [detectSentiment](#API_PutBot_ResponseSyntax) ** `true`（如果将机器人配置为将用户言语发送到 Amazon Comprehend 进行情绪分析）。如果请求中未指定 `detectSentiment` 字段，则响应中的 `detectSentiment` 字段为 `false`。 类型：布尔值 ** [enableModelImprovements](#API_PutBot_ResponseSyntax) ** 表示机器人是否使用精度改进。`true` 表示机器人正在使用改进，否则为 `false`。 类型：布尔值 ** [failureReason](#API_PutBot_ResponseSyntax) ** 如果 `status` 是 `FAILED`，则 Amazon Lex 会提供其未能构建机器人的原因。 类型：字符串 ** [idleSessionTTLInSeconds](#API_PutBot_ResponseSyntax) ** Amazon Lex 保留对话中收集的数据的最长时间。有关更多信息，请参阅 [PutBot](#API_PutBot)。 类型：整数 有效范围：最小值为 60。最大值为 86400。 ** [intents](#API_PutBot_ResponseSyntax) ** `Intent` 数据元数组。有关更多信息，请参阅 [PutBot](#API_PutBot)。 类型：[Intent](API_Intent.md) 对象数组 ** [lastUpdatedDate](#API_PutBot_ResponseSyntax) ** 机器人的更新日期。创建资源时，创建日期和上次更新日期相同。 类型：时间戳 ** [locale](#API_PutBot_ResponseSyntax) ** 机器人的目标区域设置。 类型：字符串 有效值：`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](#API_PutBot_ResponseSyntax) ** 机器人的名称。 类型：字符串 长度限制：最小长度为 2。最大长度为 50。 模式：`^([A-Za-z]_?)+$` ** [nluIntentConfidenceThreshold](#API_PutBot_ResponseSyntax) ** 该分数决定 Amazon Lex 在或[PostText](https://docs.aws.amazon.com/lex/latest/dg/API_runtime_PostText.html)响应中返回替代意图时在何处插入`AMAZON.KendraSearchIntent`、[PostContent](https://docs.aws.amazon.com/lex/latest/dg/API_runtime_PostContent.html)或两者。`AMAZON.FallbackIntent` `AMAZON.FallbackIntent`如果实际可信度分数低于此值，则会插入。 `AMAZON.KendraSearchIntent`只有在为机器人配置时才会插入。 类型：双精度 有效范围：最小值为 0。最大值为 1。 ** [status](#API_PutBot_ResponseSyntax) ** 当您发送创建 `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](#API_PutBot_ResponseSyntax) ** 与机器人关联的标签的列表。 类型：[Tag](API_Tag.md) 对象数组 数组成员：最少 0 个物品。最多 200 项。 ** [version](#API_PutBot_ResponseSyntax) ** 自动程序的版本。对于新机器人，版本始终是 `$LATEST`。 类型：字符串 长度限制：最小长度为 1。长度上限为 64。 模式：`\$LATEST|[0-9]+` ** [voiceId](#API_PutBot_ResponseSyntax) ** Amazon Lex 用于和用户进行语音交互的 Amazon Polly 语音 ID。有关更多信息，请参阅 [PutBot](#API_PutBot)。 类型：字符串 ## 错误 ** BadRequestException ** 请求格式不正确。例如，值无效或必填字段未填充。检查字段值，然后重试。 HTTP 状态代码：400 ** ConflictException ** 处理请求时出现冲突。请再次尝试您的请求。 HTTP 状态代码：409 ** InternalFailureException ** 出现内部 Amazon Lex 错误。请再次尝试您的请求。 HTTP 状态代码：500 ** LimitExceededException ** 请求超出了限制。请再次尝试您的请求。 HTTP 状态代码：429 ** PreconditionFailedException ** 您尝试更改的资源的校验和与请求中的校验和不匹配。检查资源的校验和并重试。 HTTP 状态代码：412 ## 另请参阅 有关以特定语言之一使用此 API 的更多信息 AWS SDKs，请参阅以下内容： + [AWS 命令行界面 V2](https://docs.aws.amazon.com/goto/cli2/lex-models-2017-04-19/PutBot) + [AWS 适用于.NET 的 SDK V4](https://docs.aws.amazon.com/goto/DotNetSDKV4/lex-models-2017-04-19/PutBot) + [AWS 适用于 C\$1\$1 的 SDK](https://docs.aws.amazon.com/goto/SdkForCpp/lex-models-2017-04-19/PutBot) + [AWS 适用于 Go v2 的 SDK](https://docs.aws.amazon.com/goto/SdkForGoV2/lex-models-2017-04-19/PutBot) + [AWS 适用于 Java 的 SDK V2](https://docs.aws.amazon.com/goto/SdkForJavaV2/lex-models-2017-04-19/PutBot) + [AWS JavaScript V3 版软件开发工具包](https://docs.aws.amazon.com/goto/SdkForJavaScriptV3/lex-models-2017-04-19/PutBot) + [AWS 适用于 Kotlin 的 SDK](https://docs.aws.amazon.com/goto/SdkForKotlin/lex-models-2017-04-19/PutBot) + [AWS 适用于 PHP 的 SDK V3](https://docs.aws.amazon.com/goto/SdkForPHPV3/lex-models-2017-04-19/PutBot) + [AWS Python 软件开发工具包](https://docs.aws.amazon.com/goto/boto3/lex-models-2017-04-19/PutBot) + [AWS 适用于 Ruby V3 的 SDK](https://docs.aws.amazon.com/goto/SdkForRubyV3/lex-models-2017-04-19/PutBot)