使用 WebSockets 接收訊息 - Amazon Chime SDK
定義IAM政策擷取端點建立連線使用預先擷取處理事件

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

使用 WebSockets 接收訊息

您可以使用 Amazon Chime JS SDK 來接收使用 的訊息 WebSockets，或使用您選擇的 WebSocket 用戶端程式庫。

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

定義IAM政策

若要開始，請定義可讓您建立 WebSocket 連線的 IAM政策。下列範例政策提供建立 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 連線中使用的端點。

  1. 使用 GetMessagingSessionEndpoint API 以擷取 WebSocket 端點。

  2. 使用 URL傳回的 GetMessagingSessionEndpoint API 建構已簽署的 Signature 第 4 版 WebSocket URL。如果您需要協助執行此操作，您可以遵循 中的指示建立連線。

    注意

    WebSocket URLs 具有下列表單： id.region.ws-messaging.chime.aws

建立連線

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

注意

若要擷取端點，您可以叫用 GetMessagingSessionEndpoint API。您可以使用您選擇的 WebSocket 用戶端程式庫來連線至端點。

請求語法


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-演算法

識別 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-已簽署-標頭

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

  • HTTP 主機標頭。

  • 您計劃新增至請求的任何 x-amz-* 標頭。

注意

為了提高安全性，請簽署您計劃包含在請求中的所有請求標頭。

X-Amz-Signatures

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

X-Amz-Security-Token

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

SessionId

指示建立 WebSocket 連線的唯一 ID。

UserArn

指示AppInstanceUser嘗試建立連線的 身分。值應為 ARN的 AppInstanceUser。例如 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 個，連線會透過CHANNEL_DETAILS事件API預先擷取所有頻道。如果使用者有超過 50 個頻道， 會API預先擷取包含未讀取訊息的前 50 個頻道和最新LastMessageTimestamp值。CHANNEL_DETAILS 事件以隨機順序到達，您會收到所有 50 個頻道的事件。

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

  • ChannelMessages – 的清單 ChannelMessageSummary 物件，由 CreatedTimestamp 以遞減順序排序。僅包含使用者可看到的最新 20 則訊息。如果頻道中有目標訊息，但目前使用者看不到，則可能會傳回少於 20 則訊息。ChannelMessagesHasMore 布林值將設定為 true，表示有更多訊息。軟限制，可在 AWS 帳戶層級調整。

  • ChannelMemberships – 清單 ChannelMembershipSummary 物件。包含最多 30 個頻道成員。軟限制，可在 AWS 帳戶層級調整。

此範例示範如何使用 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.

注意

AppInstanceUser 一律會接收其所屬之所有頻道的訊息。當AppInstance使用者中斷連線時，訊息會停止。

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

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

了解訊息結構

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

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

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

  • x-amz-chime-event-type

  • x-amz-chime-message-type

  • x-amz-chime-event-reason

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

承載

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

EventType 承載格式

SESSION_ESTABLISHED

不適用。 此訊息會在使用者連線至 後傳送一次 WebSocket。這表示只要 WebSocket 保持開啟，使用者收到訊息後，頻道上的任何SESSION_ESTABLISHED訊息或事件都會保證交付給使用者。

CREATE_CHANNEL_MESSAGE

ChannelMessage

REDACT_CHANNEL_MESSAGE

UPDATE_CHANNEL_MESSAGE

DELETE_CHANNEL_MESSAGE

PENDING_CREATE_CHANNEL_MESSAGE

PENDING_UPDATE_CHANNEL_MESSAGE

FAILED_CREATE_CHANNEL_MESSAGE

FAILED_UPDATE_CHANNEL_MESSAGE

DENIED_CREATE_CHANNEL_MESSAGE

DENIED_UPDATE_CHANNEL_MESSAGE

CHANNEL_DETAILS
頻道

ChannelSummary 物件。

ChannelMessages

清單ChannelMessageSummary 物件，由 CreatedTimestamp 以遞減順序排序。包含最新的 20 則訊息，但您可以在AWS帳戶層級調整該限制。

ChannelMemberships

清單ChannelMembershipSummary 物件。傳回最多 30 個頻道成員，但您可以在AWS帳戶層級調整該限制。

ReadMarkerTimestamp

AppInstanceUser 上次將頻道標記為已讀取的時間。

UPDATE_CHANNEL

Channel

DELETE_CHANNEL

BATCH_CREATE_CHANNEL_MEMBERSHIP

BatchChannelMembership

CREATE_CHANNEL_MEMBERSHIP

ChannelMembership

DELETE_CHANNEL_MEMBERSHIP

UPDATE_CHANNEL_MEMBERSHIP
x-amz-chime-message-類型

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

訊息類型 描述

STANDARD

當 Websocket 收到STANDARD頻道訊息時傳送。

CONTROL

當 WebSocket 收到CONTROL頻道訊息時傳送。

SYSTEM

Amazon Chime SDK Messaging 傳送的所有其他 Websocket 訊息。
x-amz-chime-event-原因

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

事件原因 描述

子管道_DELETED

DELETE_CHANNEL_MEMBERSHIP 彈性頻道主持人接收的事件。只有在成員平衡之後，版主才會看到 會刪除其所屬的子頻道。

處理中斷連線

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

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

關閉碼

可以重新連線

原因

1001

是

正常關閉

1006

是

異常關閉

1011

是

內部伺服器錯誤

1012

是

服務重新啟動

1013

是

請稍後再試

1014

是

伺服器擔任閘道或代理，並從上游伺服器收到無效的回應。這類似於 502 HTTP 狀態碼。

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

關閉碼

可以重新連線

原因

4002

否

用戶端已啟動

4003

否

禁止

4401

否

未獲授權

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

  1. 呼叫 GetMessagingSessionEndpoint API 以取得新的基礎 URL。

  2. 如果IAM憑證已過期，請重新整理憑證。

  3. 透過 連線 WebSocket。

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