Amazon Q 商业版 - API 概述

该 API 提供各种操作，可用于与 Amazon Q 商业版交互。API 可有效用于创建应用程序、管理对话和上传文档。

Q 商业版

Amazon Q 商业版是一款由 AI 驱动的聊天助手，可帮助员工更高效地工作。它支持各种任务，例如回答问题、查找信息、撰写电子邮件、总结文本、创建文档大纲和生成创意。用户通过提问获得对话式答案，从而简化工作并提高生产力。

有关 Amazon Q 商业版 API 的概述，请参阅Amazon Q 商业版 API 操作概述。

Q 应用

Amazon Q 应用允许 Web 体验用户构建自己的基于生成式 AI 的应用程序。借助 Amazon Q 应用，用户可以轻松地在企业数据上创建、共享和自定义应用程序，以简化任务并提高个人和团队的生产力。例如，您可以创建一个仅生成营销内容的工具，这可以帮助您的营销团队更高效地工作。或者，您可以创建一个以特定风格、语气和品牌声音撰写客户电子邮件和促销内容的工具。

有关 Amazon Q 应用 API 的概述，请参阅 Amazon Q 应用 API 操作概述。

使用 API 设置流式聊天

Amazon Q 商业版提供流式聊天 API，用于以一系列部分结果的形式向用户交付聊天回复。这些回复使用连续的数据包传输。

要配置流式传输，您可以使用 WebSockets 或 AWS SDK。对于 WebSockets，需要通过 8443 端口建立到受支持的 Amazon Q 商业版端点（例如，wss://qbusiness.us-west-2.api.aws:8443/chat）的安全连接。确保此端口已启用且未被您的网络配置阻止。

设置 WebSocket 流

以下部分概述了设置 WebSocket 流的步骤。

将以下策略附加到发出请求的 IAM 角色。

{
    "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "my-qbusiness-websocket-policy",
                    "Effect": "Allow",
                    "Action": "qbusiness:Chat",
                    "Resource": "*"
            }
        ]
}

要启动会话，请创建以下格式的预签名 URL。为提高可读性，已添加换行符。

GET wss://qbusiness.us-west-2.api.aws:8443/chat?
&X-Amz-Algorithm=AWS4-HMAC-SHA256
&X-Amz-Credential=access-key%2FYYYYMMDD%2Fus-west-2%2Fqbusiness%2Faws4_request
&X-Amz-Date=YYYYMMDDTHHMMSSZ
&X-Amz-Expires=300
&X-Amz-Security-Token=security-token
&X-Amz-Signature=string
&X-Amz-SignedHeaders=host
&chat-input={"applicationId":"application_id","userId":"[email protected]","userGroups":null,"clientToken":str(uuid.uuid4())}

创建要签名的字符串，其中包含有关您的请求的元信息。在计算请求签名时，您将在下一步使用此字符串进行签名。

hashed_canonical_request = HashSHA256(canonical_request.Encode("utf-8")).HexDigest()
new_credential_scope = datestamp + '/' + region + '/qbusiness/aws4_request'
string_to_sign=algorithm + "\n"
+ amz_date + "\n"
+ new_credential_scope + "\n"
+ HashSHA256(canonical_request.Encode("utf-8")).HexDigest()

创建要签名的字符串，其中包含有关您的请求的元信息。在计算请求签名时，您将在下一步使用此字符串进行签名。

hashed_canonical_request = HashSHA256(canonical_request.Encode("utf-8")).HexDigest()
new_credential_scope = datestamp + '/' + region + '/qbusiness/aws4_request'
string_to_sign=algorithm + "\n"
+ amz_date + "\n"
+ new_credential_scope + "\n"
+ HashSHA256(canonical_request.Encode("utf-8")).HexDigest()

计算签名。为此，请从您的 AWS 密钥访问密钥派生签名密钥。为了获得更高的保护级别，派生的密钥特定于日期、服务和 AWS 区域。使用此派生密钥对请求进行签名。

#Create the signing key
signing_key = GetSignatureKey(secret_key, datestamp, region, service)
        
# Sign the string_to_sign using the signing key
signature = HMAC.new(signing_key, (string_to_sign).Encode("utf-8"), Sha256()).HexDigest

将签名信息添加到请求并创建请求 URL。
计算签名后，将其添加到查询字符串。

首先，将身份验证信息添加到查询字符串。

canonical_querystring += "&X-Amz-Signature=" + signature

其次，创建请求的 URL。

request_url = endpoint + canonical_uri + "?" + canonical_querystring

使用请求 URL 和您的 WebSocket 库向 Amazon Q 商业版发出请求。

对 Amazon Q 商业版的请求必须包含以下标头。通常，这些标头由您的 WebSocket 客户端库管理。

Host: qbusiness.us-west-2.amazonaws.com:8443 
Connection: Upgrade
Upgrade: websocket
Origin: URI-of-WebSocket-client
Sec-WebSocket-Version: 13
Sec-WebSocket-Key: randomly-generated-string <calculated at runtime>

当 Amazon Q 商业版收到您的 WebSocket 请求时，它将返回 WebSocket 升级响应。通常，您的 WebSocket 库会管理此响应并设置与 Amazon Q 商业版通信的套接字。

以下是 Amazon Q 商业版的响应。为提高可读性，已添加换行符。

HTTP/1.1 101 WebSocket Protocol Handshake
Connection: upgrade
Upgrade: websocket
websocket-origin: wss://qbusiness.us-west-2.amazonaws.com:8443
websocket-location: qbusiness.us-west-2.amazonaws.com:8443/chat?
&X-Amz-Algorithm=AWS4-HMAC-SHA256
&X-Amz-Credential=access-key%2FYYYYMMDD%2Fus-west-2%2Fqbusiness%2Faws4_request
&X-Amz-Date=YYYYMMDDTHHMMSSZ
&X-Amz-Expires=300
&X-Amz-Security-Token=security_token
&X-Amz-SignedHeaders=host
&chat-input=%7B%22applicationId%22%3A%20%22aa419bef-ac4e-4c57-9224-f603e185ac09%22%2C%20%22userId%22%3A%20%testuser%40amazon.com%22%2C%20%22userGroups%22%3A%20null%2C%20%22clientToken%22%3A%20%2283eb07d9-193c-420c-97c6-f2f343d13591%22%2C%20%22conversationId%22%3A%20null%2C%20%22parentMessageId%22%3A%20null%7D
&X-Amz-Signature=Signature Version 4 signature
x-amzn-RequestId: RequestId
sec-websocket-accept: hash-of-the-Sec-WebSocket-Key-header

发出您的 WebSocket 流式请求。
建立 WebSocket 连接后，客户端可以开始发送一系列聊天帧，每个帧都使用事件流编码进行编码。
每个数据帧包含三个标头以及一段原始文本字节；下表描述了这些标头。

标头名称字节长度	标头名称（字符串）	标头值类型	值字符串字节长度	值字符串（UTF-8）
13	:content-type	7	24	application/json
11	:event-type	7	10	textEvent
13	:message-type	7	5	event

要结束数据流，请在事件流编码的消息中发送输入结束事件。

标头名称字节长度	标头名称（字符串）	标头值类型	值字符串字节长度	值字符串（UTF-8）
13	:content-type	7	16	application/json
11	:event-type	7	15	endOfInputEvent
13	:message-type	7	5	event

处理 WebSocket 流式错误

处理您的请求时发生错误时，Amazon Q 商业版会向您发送特殊的响应。此响应包含下表中描述的标头；响应的主体包含描述性错误消息。

标头名称字节长度	标头名称（字符串）	标头值类型	值字符串字节长度	值字符串（UTF-8）
13	:content-type	7	16	application/json
15	:event-type	7	变化	变化，见下文
13	:message-type	7	9	异常

事件流编码

Amazon Q 商业版使用一种名为事件流编码的格式进行流式聊天。

事件流编码允许客户端和服务器之间进行双向通信。当您向 Amazon Q 商业版发送消息时，它会以特殊格式进行编码。您从 Amazon Q 商业版收到的回复也采用相同的格式。

数据帧

每个流式请求包含一个或多个数据帧。创建数据帧有两个步骤

将原始 ChatInput 数据与元数据组合以创建请求的有效负载。
将有效负载与签名组合以形成发送到 Amazon Q 商业版的事件消息。

打印页面