PutSession

使用 Amazon Lex 自动程序创建新会话或修改现有会话。使用此操作使您的应用程序能够设置机器人的状态。

有关更多信息，请参阅管理会话。

请求语法

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

{
   "activeContexts": [ 
      { 
         "name": "string",
         "parameters": { 
            "string" : "string" 
         },
         "timeToLive": { 
            "timeToLiveInSeconds": number,
            "turnsToLive": number
         }
      }
   ],
   "dialogAction": { 
      "fulfillmentState": "string",
      "intentName": "string",
      "message": "string",
      "messageFormat": "string",
      "slots": { 
         "string" : "string" 
      },
      "slotToElicit": "string",
      "type": "string"
   },
   "recentIntentSummaryView": [ 
      { 
         "checkpointLabel": "string",
         "confirmationStatus": "string",
         "dialogActionType": "string",
         "fulfillmentState": "string",
         "intentName": "string",
         "slots": { 
            "string" : "string" 
         },
         "slotToElicit": "string"
      }
   ],
   "sessionAttributes": { 
      "string" : "string" 
   }
}

URI 请求参数

请求使用以下 URI 参数。

accept

Amazon Lex 在响应中返回的消息可以是文本，也可以是语音，取决于此字段的值。

• 如果值为 text/plain; charset=utf-8，则 Amazon Lex 会在响应中返回文本。

• 如果值以 audio/ 开头，则 Amazon Lex 会在响应中返回语音。Amazon Lex 使用 Amazon Polly 按照您指定的配置生成语音。例如，如果您将 audio/mpeg 指定为值，Amazon Lex 将返回 MPEG 格式的语音。

• 如果值为 audio/pcm，则返回的语音采用 16 位小端序格式的 audio/pcm。

• 以下是接受的值：

  • audio/mpeg

  • audio/ogg

  • audio/pcm

  • audio/*（默认值为 mpeg）

  • text/plain; charset=utf-8

botAlias

包含会话数据的机器人的使用中别名。

必需：是

botName

包含会话数据的机器人的名称。

必需：是

userId

客户端应用程序用户的 ID。Amazon Lex 使用它来识别用户与您的机器人的对话。

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

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

必需：是

请求体

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

activeContexts

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

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

类型：ActiveContext 对象数组

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

必需：否

dialogAction

设置机器人为完成对话而应采取的下一个操作。

类型：DialogAction 对象

必需：否

recentIntentSummaryView

该机器人最近的意图摘要。您可以使用意图摘要视图在意图上设置检查点标签并修改意图的属性。您也可以使用它来移除意图摘要对象或向列表中添加意图摘要对象。

您修改或添加到列表中的意图必须对机器人有意义。例如，意图名称对于机器人而言必须有效。您必须为以下项提供值：

• intentName

• 插槽名称

• slotToElict

如果您在 PutSession 请求中发送 recentIntentSummaryView 参数，则新摘要视图的内容将替换旧的摘要视图。例如，如果 GetSession 请求在摘要视图中返回三个意图，而您在摘要视图中使用一个意图呼叫 PutSession，则对 GetSession 的下一个调用将只返回一个意图。

类型：IntentSummary 对象数组

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

必需：否

sessionAttributes

表示会话特定上下文信息的键值对的映射。它包含在 Amazon Lex 与客户端应用程序之间传递的应用程序信息。

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

必需：否

响应语法

HTTP/1.1 200
Content-Type: contentType
x-amz-lex-intent-name: intentName
x-amz-lex-slots: slots
x-amz-lex-session-attributes: sessionAttributes
x-amz-lex-message: message
x-amz-lex-encoded-message: encodedMessage
x-amz-lex-message-format: messageFormat
x-amz-lex-dialog-state: dialogState
x-amz-lex-slot-to-elicit: slotToElicit
x-amz-lex-session-id: sessionId
x-amz-lex-active-contexts: activeContexts

audioStream

响应元素

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

响应将返回以下 HTTP 标头。

activeContexts

会话的活动上下文列表。

contentType

请求的 Accept HTTP 标头中指定的内容类型。

dialogState

• ConfirmIntent — Amazon Lex 预计在履行意图之前会有“是”或“否”响应来确认意图。

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

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

• Failed — 传达与用户的对话失败。发生这种情况的原因可能多种多样，包括用户没有对服务提示做出适当的响应，或者 Lambda 函数无法履行意图。

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

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

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

encodedMessage

应向用户显示的下一条消息。

encodedMessage 字段采用 base-64 编码。必须先解码该字段，然后才能使用该值。

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

intentName

当前意图的名称。

message

此标头已被弃用。

应向用户显示的下一条消息。

您只能在 de-DE、en-AU、en-GB、en-US、es-419、es-ES、es-US、fr-CA、fr-FR 和 it-IT 区域设置中使用此字段。在所有其他区域设置中，message 字段均为空。您应改用 encodedMessage 字段。

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

messageFormat

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

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

• CustomPayload — 消息是客户端的自定义格式。

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

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

有效值：PlainText | CustomPayload | SSML | Composite

sessionAttributes

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

sessionId

会话的唯一标识符。

slots

Amazon Lex 在对话期间从用户输入中检测到的零个或零个以上意图插槽值的映射。

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

slotToElicit

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

响应将以下内容作为 HTTP 正文返回。

audioStream

要传达给用户的消息的音频版本。

错误

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

NotAcceptableException

请求中的接受标头没有有效值。

HTTP 状态代码：406

NotFoundException

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

HTTP 状态代码：404

另请参阅

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

• AWS 命令行界面

• AWS 适用于 .NET 的 SDK

• AWS 适用于 C++ 的 SDK

• AWS 适用于 Go v2 的 SDK

• AWS 适用于 Java 的 SDK V2

• AWS JavaScript V3 版软件开发工具包

• AWS 适用于 PHP 的 SDK V3

• AWS Python 软件开发工具包

• AWS 适用于 Ruby V3 的 SDK