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":"test_user@amazon.com","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 商業版的事件訊息。

列印頁面