本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

使用 WebSockets 在 Amazon Chime SDK 訊息中接收訊息

您可以使用 Amazon Chime JS 開發套件，透過 WebSockets 接收訊息，或者您可以使用您選擇的 WebSocket 用戶端程式庫。

依照列出的順序遵循這些主題，以開始使用 WebSockets：

定義 IAM 政策

若要開始，請定義 IAM 政策，該政策可讓您建立 WebSocket 連線。下列範例政策提供建立 WebSocket 連線的AppInstanceUser許可。

"Version": "2012-10-17",
"Statement": [
  {
    "Effect": "Allow",
    "Action: [
      "chime:Connect"
    ],
    "Resource": [
      "arn:aws:chime:region:{aws_account_id}:app-instance/{app_instance_id}/user/{app_instance_user_id}"
    ]
 },
 {
    "Effect": "Allow",
    "Action: [
      "chime:GetMessagingSessionEndpoint"
    ],
    "Resource": [
      "*"
    ]
 }
 ]
} 

擷取端點

下列步驟說明如何擷取 WebSocket 連線中使用的端點。

建立連線

擷取端點之後，您可以使用連線 API 建立與 Amazon Chime SDK 後端伺服器的 WebSocket 連線，並接收 的訊息AppInstanceUser。您必須使用 AWS Signature 第 4 版來簽署請求。如需簽署請求的詳細資訊，請參閱使用簽章版本 4 簽署 AWS 請求。

請求語法

GET /connect
?X-Amz-Algorithm=AWS4-HMAC-SHA256
&X-Amz-Credential=AKIARALLEXAMPLE%2F20201214%2Fregion%2Fchime%2Faws4_request
&X-Amz-Date=20201214T171359Z
&X-Amz-Expires=10
&X-Amz-SignedHeaders=host
&sessionId={sessionId}
&userArn={appInstanceUserArn}
&X-Amz-Signature=db75397d79583EXAMPLE

URI 請求參數

所有 URI 請求查詢參數都必須以 URL 編碼。

X-Amz-Algorithm

識別 AWS Signature 的版本，以及您用來計算簽章的演算法。Amazon Chime SDK 僅支援 AWS Signature 第 4 版身分驗證，因此此值為 AWS4-HMAC-SHA256。

X-Amz-Credential

除了您的存取金鑰 ID 之外，此參數也提供簽章有效的 AWS 區域和服務範圍。此值必須符合您在簽章計算中使用的範圍。此參數值的一般格式為：

<yourAccessKeyId>/<date>/<awsRegion>/<awsService >/aws4_request

例如：

AKIAIOSFODNN7EXAMPLE/20201214/us-east-1/chime/aws4_request

X-Amz-Date

日期和時間格式必須遵循 ISO 8601 標準，而且您必須將其格式化為 yyyyMMddTHHmmssZ。例如，您必須將 08/01/2020 15：32：41.982-700 轉換為國際標準時間 (UTC)，並以 提交20200801T083241Z。

X-Amz-Signed-Headers

列出您用來計算簽章的標頭。簽章計算中需要下列標頭：

X-Amz-Signatures

提供簽章以驗證您的請求。此簽章必須符合 Amazon Chime SDK 計算的簽章。如果沒有，Amazon Chime SDK 會拒絕請求。例如：733255ef022bec3f2a8701cd61d4b371f3f28c9f19EXAMPLEd48d5193d7。

X-Amz-Security-Token

如果使用來自 Security Token Service 的登入資料，則為選用的登入資料參數。如需 服務的詳細資訊，請參閱 https：//https://docs.aws.amazon.com/STS/latest/APIReference/。

SessionId

指出要建立之 WebSocket 連線的唯一 ID。

UserArn

指出AppInstanceUser嘗試建立連線的 身分。值應該是 的 ARNAppInstanceUser。例如 arn:aws:chime:us%2Deast%2D1:123456789012:app%2Dinstance/694d2099%2Dcb1e%2D463e%2D9d64%2D697ff5b8950e/user/johndoe

使用預先擷取來交付頻道詳細資訊

當您建立 WebSocket 連線時，您可以在查詢參數prefetch-on=connect中指定 來傳遞CHANNEL_DETAILS事件。預先擷取功能隨附連線 API，而 功能可讓使用者查看豐富的聊天檢視，而無需額外的 API 呼叫。使用者可以：

使用者連線到指定的預先擷取參數後，使用者會收到工作階段建立的事件，這表示已建立連線。然後，使用者會收到最多 50 個CHANNEL_DETAILS事件。如果使用者的頻道少於 50 個，連線 API 會透過CHANNEL_DETAILS事件預先擷取所有頻道。如果使用者有超過 50 個頻道，API 會預先擷取包含未讀取訊息的前 50 個頻道和最新LastMessageTimestamp值。CHANNEL_DETAILS 事件以隨機順序抵達，您會收到所有 50 個頻道的事件。

此外，預先擷取會傳回 ChannelMessages和 的下列項目ChannelMemberships：

此範例示範如何使用 prefetch-on=connect。

GET /connect
?X-Amz-Algorithm=AWS4-HMAC-SHA256
&X-Amz-Credential=AKIARALLEXAMPLE%2F20201214%2Fregion%2Fchime%2Faws4_request
&X-Amz-Date=20201214T171359Z
&X-Amz-Expires=10
&X-Amz-SignedHeaders=host
&sessionId=sessionId
&prefetch-on=connect
&userArn=appInstanceUserArn
&X-Amz-Signature=db75397d79583EXAMPLE

此範例顯示一個頻道的回應。您將會收到所有 50 個頻道的回應。

{
   "Headers": { 
        "x-amz-chime-event-type": "CHANNEL_DETAILS", 
        "x-amz-chime-message-type": "SYSTEM" 
        },
   "Payload": JSON.stringify"({
        Channel: ChannelSummary 
        ChannelMessages: List of ChannelMessageSummary  
        ChannelMemberships: List of ChannelMembershipSummary
        ReadMarkerTimestamp: Timestamp 
        ChannelMessagesHasMore: Boolean 
    })
} 

處理事件

若要AppInstanceUser讓 在訊息建立連線後接收訊息，您必須將其新增至頻道。若要這麼做，請使用 CreateChannelMembership API。

AppInstanceAdmin 和 ChannelModerator不會在頻道上接收訊息，除非您使用 CreateChannelMembership API 明確新增。

下列主題說明如何處理事件。

了解訊息結構

您收到的每個 WebSocket 訊息都遵守此格式：

{
   "Headers": {"key": "value"},
   "Payload": "{\"key\": \"value\"}"
}

標頭

Amazon Chime SDK 訊息使用以下標頭金鑰：

下一節會列出並說明標頭的可能值和承載。

承載

Websocket 訊息會傳回 JSON 字串。JSON 字串的結構取決於x-amz-event-type標頭。下表列出可能x-amz-chime-event-type的值和承載：

x-amz-chime-message-type

下表列出x-amz-chime-message-type訊息類型 。

x-amz-chime-event-reason

這是特定使用案例支援的選用標頭。標頭提供有關為何收到特定事件的資訊。

處理中斷連線

Websocket 可能因網路連線變更或憑證過期而中斷連線。開啟 WebSocket 之後，Amazon Chime SDK 會將一般 ping 傳送至訊息用戶端，以確保其仍保持連線。如果連線關閉，用戶端會收到 WebSocket 關閉碼。用戶端可以嘗試重新連線，也可以不重新連線，具體取決於關閉碼。下表顯示用戶端可用來重新連線的關閉碼。

對於 1000 到 4000 關閉碼，請僅針對下列訊息重新連線：

對於 4XXX 代碼，除了下列訊息之外，一律重新連線：

當應用程式使用關閉程式碼重新連線時，應用程式應該：

如果您使用 amazon-chime-sdk-js 程式庫，如果您實作 needsRefresh() 屬性和 refresh() 方法，則會為您處理。如需工作範例，請參閱 https：//https://github.com/aws-samples/amazon-chime-sdk/blob/dc11c4c76c78d28f618577706bba2087919a5635/apps/chat/src/providers/AuthProvider.jsx#L93-L101。