PostText - Amazon Lex V1
请求语法URI 请求参数请求体响应语法响应元素错误另请参阅

终止支持通知：2025年9月15日， AWS 我们将停止对Amazon Lex V1的支持。2025 年 9 月 15 日之后，您将无法再访问亚马逊 Lex V1 主机或 Amazon Lex V1 资源。如果您使用的是 Amazon Lex V2，请改为参阅 Amazon Lex V2 指南。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

PostText

将用户输入发送到 Amazon Lex。客户端应用程序可以使用此 API 在运行时向 Amazon Lex 发送请求。Amazon Lex 随后使用其为机器人构建的机器学习模型来解释用户输入。

在响应中，Amazon Lex 会返回要传达给用户的下一个 message 以及要显示的可选 responseCard。考虑以下示例消息：

  • 对于用户输入 “我想要披萨”，Amazon Lex 可能会返回一条回复，其中包含一条引出槽位数据的消息（例如， PizzaSize）：“你想要什么尺寸的披萨？”

  • 在用户提供所有披萨订单信息后，Amazon Lex 可能会返回一条消息以获取用户确认：“是否可以进到下披萨订单这一步？”。

  • 用户对确认提示回答“是”后，Amazon Lex 可能会返回结论语句：“谢谢，已经为您的奶酪披萨下订单。”。

并非所有 Amazon Lex 消息都需要用户响应。例如，结论语句不需要响应。有些消息只需要“是”或“否”用户响应。除了 message 之外，Amazon Lex 还提供了有关响应中消息的其他上下文，您可以使用这些上下文来增强客户行为，例如显示相应的客户端用户界面。这些是响应中的 slotToElicit、dialogState、intentName 和 slots 字段。考虑以下示例：

  • 如果消息是为了引发插槽数据，Amazon Lex 会返回以下上下文信息：

    • dialogState设置为 ElicitSlot

    • intentName 设置为当前上下文中的意图名称

    • slotToElicit 设置为 message 正在引发信息的插槽名称

    • slots 设置为具有当前已知值的为意图配置的插槽映射

  • 如果消息是确认提示，dialogState则设置为 ConfirmIntent SlotToElicit且设置为空。

  • 如果消息是表明用户意图未被理解的澄清提示（为意图配置），dialogState则设置为 ElicitIntent 且slotToElicit设置为空。

此外，Amazon Lex 还会返回您的应用程序特定的 sessionAttributes。有关更多信息，请参阅管理对话上下文。

请求语法

POST /bot/botName/alias/botAlias/user/userId/text HTTP/1.1
Content-type: application/json

{
   "activeContexts": [ 
      { 
         "name": "string",
         "parameters": { 
            "string" : "string" 
         },
         "timeToLive": { 
            "timeToLiveInSeconds": number,
            "turnsToLive": number
         }
      }
   ],
   "inputText": "string",
   "requestAttributes": { 
      "string" : "string" 
   },
   "sessionAttributes": { 
      "string" : "string" 
   }
}

URI 请求参数

请求使用以下 URI 参数。

botAlias

Amazon Lex 机器人的别名。

必需：是

botName

Amazon Lex 机器人的名称。

必需：是

userId

客户端应用程序用户的 ID。Amazon Lex 使用它来识别用户与您的机器人的对话。在运行时，每个请求都必须包含 userID 字段。

要决定用于您的应用程序的用户 ID，请考虑以下因素。

  • userID 字段不得包含用户的任何个人身份信息，例如姓名、个人识别号或其他最终用户的个人信息。

  • 如果您希望用户在一台设备上开始对话，然后在另一台设备上继续对话，请使用用户特定的标识符。

  • 如果您希望同一个用户能够在两台不同的设备上进行两次独立的对话，请选择设备特定的标识符。

  • 用户不能与同一个机器人的两个不同版本进行两个独立的对话。例如，用户无法与同一个机器人的 PROD 和 BETA 版本进行对话。如果您预计用户需要与两个不同的版本进行对话（例如，在测试期间），请在用户 ID 中包含机器人别名以将这两个对话分开。

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

模式：[0-9a-zA-Z._:-]+

必需：是

请求体

请求接受采用 JSON 格式的以下数据。

activeContexts

请求的活动上下文列表。可以在履行先前的意图时激活上下文，也可以通过在请求中包含上下文来激活上下文，

如果您未指定上下文列表，Amazon Lex 将使用会话的上下文的当前列表。如果您指定一个空列表，则会话的所有上下文都将被清除。

类型：ActiveContext 对象数组

数组成员：最少 0 个物品。最多 20 个项目。

必需：否

inputText

用户输入的文本（Amazon Lex 会解释此文本）。

当您使用 AWS CLI 时，您无法在 --input-text 参数中传递 URL。改为使用 --cli-input-json 参数传递 URL。

类型：字符串

长度限制：长度下限为 1。最大长度为 1024。

必需：是

requestAttributes

在 Amazon Lex 和客户端应用程序之间传递的特定于请求的信息。

命名空间 x-amz-lex: 保留供特殊属性使用。请勿创建带有 x-amz-lex: 前缀的任何请求属性。

有关更多信息，请参阅设置请求属性。

类型：字符串到字符串映射

必需：否

sessionAttributes

在 Amazon Lex 和客户端应用程序之间传递的特定于应用程序的信息。

有关更多信息，请参阅设置会话属性。

类型：字符串到字符串映射

必需：否

响应语法

HTTP/1.1 200
Content-type: application/json

{
   "activeContexts": [ 
      { 
         "name": "string",
         "parameters": { 
            "string" : "string" 
         },
         "timeToLive": { 
            "timeToLiveInSeconds": number,
            "turnsToLive": number
         }
      }
   ],
   "alternativeIntents": [ 
      { 
         "intentName": "string",
         "nluIntentConfidence": { 
            "score": number
         },
         "slots": { 
            "string" : "string" 
         }
      }
   ],
   "botVersion": "string",
   "dialogState": "string",
   "intentName": "string",
   "message": "string",
   "messageFormat": "string",
   "nluIntentConfidence": { 
      "score": number
   },
   "responseCard": { 
      "contentType": "string",
      "genericAttachments": [ 
         { 
            "attachmentLinkUrl": "string",
            "buttons": [ 
               { 
                  "text": "string",
                  "value": "string"
               }
            ],
            "imageUrl": "string",
            "subTitle": "string",
            "title": "string"
         }
      ],
      "version": "string"
   },
   "sentimentResponse": { 
      "sentimentLabel": "string",
      "sentimentScore": "string"
   },
   "sessionAttributes": { 
      "string" : "string" 
   },
   "sessionId": "string",
   "slots": { 
      "string" : "string" 
   },
   "slotToElicit": "string"
}

响应元素

如果此操作成功，则该服务将会发送回 HTTP 200 响应。

服务以 JSON 格式返回以下数据。

activeContexts

会话的活动上下文列表。可以在履行意图时设置上下文，也可以通过调用 PostContent、PostText 或 PutSession 操作来设置上下文。

您可以使用上下文来控制可以跟进意图的意图，也可以修改应用程序的操作。

类型：ActiveContext 对象数组

数组成员：最少 0 个物品。最多 20 个项目。

alternativeIntents

一到四个可能适用于用户意图的替代意图。

每个替代意图都包括一个分数，该分数表明 Amazon Lex 对意图与用户意图相匹配的信心程度。意图按置信度分数排序。

类型：PredictedIntent 对象数组

数组成员：最多 4 项。

botVersion

响应对话的机器人的版本。您可以使用此信息来帮助确定机器人的一个版本的性能是否优于另一个版本。

类型：字符串

长度限制：长度下限为 1。长度上限为 64。

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

dialogState

标识用户交互的当前状态。Amazon Lex 返回以下任一值作为 dialogState。客户可以选择使用此信息来自定义用户界面。

  • ElicitIntent — Amazon Lex 想要引发用户意图。

    例如，用户可能会说出意图（“我想点披萨”）。如果 Amazon Lex 无法从此言语中推断出用户的意图，它将返回此对话状态。

  • ConfirmIntent — Amazon Lex 预计会有“是”或“否”响应。

    例如，Amazon Lex 希望用户在履行意图之前进行确认。

    用户可能会响应其他信息，而不是简单的“是”或“否”。例如，“是，但要做个厚皮披萨”或“否，我想点一份饮品”。Amazon Lex 可以处理此类额外信息（在这些示例中，更新外壳类型槽值，或者将意图从更改 OrderPizza 为 OrderDrink）。

  • ElicitSlot — Amazon Lex 期望当前意图的插槽值。

    例如，假设 Amazon Lex 在响应中发送了以下消息：“您想要什么尺寸的披萨？”。用户可能会响应插槽值（例如，“中等”）。用户还可能在响应中提供其他信息（例如，“中厚皮披萨”）。Amazon Lex 可以适当地处理此类额外信息。

  • Fulfilled — 表示为意图配置的 Lambda 函数已成功履行意图。

  • ReadyForFulfillment — 传达客户端必须履行意图。

  • Failed — 表示与用户的对话失败。

    发生这种情况的原因可能多种多样，包括用户没有对服务提示做出适当的响应（您可以配置 Amazon Lex 可以提示用户输入特定信息的次数），或者 Lambda 函数无法履行意图。

类型：字符串

有效值：ElicitIntent | ConfirmIntent | ElicitSlot | Fulfilled | ReadyForFulfillment | Failed

intentName

Amazon Lex 知道的当前用户意图。

类型：字符串

message

要传达给用户的消息。消息可以来自机器人的配置或 Lambda 函数。

如果未使用 Lambda 函数配置意图，或者如果 Lambda 函数在其响应中返回 Delegate 作为 dialogAction.type，则 Amazon Lex 会决定下一步的操作方案，并根据当前的交互上下文从机器人的配置中选择相应的消息。例如，如果 Amazon Lex 无法理解用户输入，则会使用澄清提示消息。

创建意图时，您可以将消息分配给群组。将消息分配给群组后，Amazon Lex 会在响应中返回来自每个群组的一条消息。消息字段是一个包含消息的转义的 JSON 字符串。有关返回的 JSON 字符串结构的更多信息，请参阅受支持的消息格式。

如果 Lambda 函数返回消息，则 Amazon Lex 会在响应中将其传递给客户端。

类型：字符串

长度限制：长度下限为 1。最大长度为 1024。

messageFormat

响应消息的格式。下列值之一：

  • PlainText — 消息包含 UTF-8 纯文本。

  • CustomPayload — 消息是由 Lambda 函数定义的自定义格式。

  • SSML — 消息包含为语音输出设置格式的文本。

  • Composite — 消息包含一个转义的 JSON 对象，其中包含一条或多条来自创建意图时消息分配到的群组中的一条或多条消息。

类型：字符串

有效值：PlainText | CustomPayload | SSML | Composite

nluIntentConfidence

提供一个分数，表示 Amazon Lex 对返回的意图是符合用户的意图的信心程度。分数必须介于 0.0 到 1.0 之间。有关更多信息，请参阅置信度分数。

分数是相对分数，而不是绝对分数。根据对 Amazon Lex 的改进，分数可能会发生变化。

类型：IntentConfidence 对象

responseCard

表示用户响应当前提示时必须使用的选项。响应卡可以来自机器人配置（在 Amazon Lex 控制台中，选择插槽旁边的设置按钮）或代码挂钩（Lambda 函数）。

类型：ResponseCard 对象

sentimentResponse

用言语表达的情绪。

当机器人配置为向 Amazon Comprehend 发送言语以进行情绪分析时，此字段将包含分析结果。

类型：SentimentResponse 对象

sessionAttributes

表示会话特定上下文信息的键值对的映射。

类型：字符串到字符串映射

sessionId

会话的唯一标识符。

类型：字符串

slots

Amazon Lex 从用户在对话中输入的内容中检测到的意图插槽。

Amazon Lex 会创建包含插槽可能值的列表。它返回的值由创建或更新插槽类型时 valueSelectionStrategy 所选的值决定。如果 valueSelectionStrategy 设置为 ORIGINAL_VALUE，并且用户值与插槽值相近，则返回用户提供的值。如果 valueSelectionStrategy 设置为 TOP_RESOLUTION，Amazon Lex 会返回解决方案列表中的第一个值，如果没有解决方案列表，则返回空值。如果不指定 valueSelectionStrategy，则默认值为 ORIGINAL_VALUE。

类型：字符串到字符串映射

slotToElicit

如果 dialogState 值为 ElicitSlot，则返回 Amazon Lex 正在为其获取值的插槽的名称。

类型：字符串

错误

BadGatewayException

要么是 Amazon Lex 机器人仍在构建，要么其中一个依赖服务（Amazon Polly、AWS Lambda）因内部服务错误而失败。

HTTP 状态代码：502

BadRequestException

请求验证失败，上下文中没有可用的消息，或者机器人构建失败、仍在进行中或者包含未构建的更改。

HTTP 状态代码：400

ConflictException

两个客户端使用相同的 AWS 账户、Amazon Lex 机器人和用户 ID。

HTTP 状态代码：409

DependencyFailedException

其中一个依赖项（例如 AWS Lambda 或 Amazon Polly）引发了异常。例如，

  • 如果 Amazon Lex 没有足够的权限来调用 Lambda 函数。

  • 如果 Lambda 函数的执行时间超过 30 秒。

  • 如果履行 Lambda 函数返回 Delegate 对话操作而不删除任何插槽值。

HTTP 状态代码：424

InternalFailureException

内部服务错误。重试调用。

HTTP 状态代码：500

LimitExceededException

已超出限制。

HTTP 状态代码：429

LoopDetectedException

不使用此异常。

HTTP 状态代码：508

NotFoundException

未找到所引用的资源（例如 Amazon Lex 机器人或别名）。

HTTP 状态代码：404

另请参阅

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