用 WebSockets 來接收訊息

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

請依照列出的順序執行下列主題以開始使用 WebSockets：

主題

定義 IAM 政策
擷取端點
建立連接
使用預先擷取來傳送頻道詳細資訊
處理事件

定義 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 連線中使用的端點。

使用 GetMessagingSessionEndpointAPI 擷取 WebSocket 端點。
使用 GetMessagingSessionEndpointAPI 傳回的 URL 建構「簽名版本 4 已簽署的 WebSocket URL」。如果您需要協助，可以按照中的指示操作建立連接。

注意
WebSocket 網址的格式如下：id.region.ws-messaging.chime.aws

建立連接

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

注意

若要擷取端點，您可以呼叫 GetMessagingSessionEndpointAPI。您可以使用您選擇的用 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-阿姆斯算法

識別 AWS 簽名的版本，以及您用來計算簽章的演算法。Amazon Chime 開發套件僅支援 AWS 簽名版本 4 身份驗證，因此其價值為AWS4-HMAC-SHA256。

X-阿姆斯特丹证书

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

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

例如：

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

X-日期

日期和時間格式必須遵循 ISO 8601 標準，並且您必須將其格式化為yyyyMMddTHHmmssZ。例如，您必須將 2020 年 8 月 1 日 15:32：41.982-700 轉換為協調世界時（世界標準時間），並將其提交為。20200801T083241Z

X-AMZ 簽名頭

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

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

注意

為了增加安全性，請簽署您打算包含在請求中的所有請求標頭。

X-同步簽名

提供簽章以驗證您的請求。此簽名必須與 Amazon Chime 開發套件所計算的簽章相符。如果沒有，Amazon Chime SDK 會拒絕該請求。例如 733255ef022bec3f2a8701cd61d4b371f3f28c9f19EXAMPLEd48d5193d7。

X-安全令牌

如果使用來自安全性權杖服務的認證，則為選用憑證參數。如需有關此服務的詳細資訊，請參閱 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 調用即可查看豐富的聊天視圖。使用者可以：

查看最後一個通道消息以及其時間戳記的預覽。
查看頻道的成員。
查看頻道的未讀標記。

使用者使用指定的 prefetch 參數連線後，使用者會收到工作階段建立的事件，這表示連線已建立。然後，用戶最多會收到 50 個CHANNEL_DETAILS事件。如果使用者的通道少於 50 個，則連接 API 會透過事件預先擷取所有通CHANNEL_DETAILS道。如果使用者擁有 50 個以上的通道，API 會預先擷取包含未讀訊息和最新值的前 50 個頻道。LastMessageTimestampCHANNEL_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若要在建立連線後接收訊息，您必須將它們新增至通道。若要這麼做，請使用 CreateChannelMembershipAPI。

注意

A AppInstanceUser 永遠會接收所屬的所有頻道的訊息。當AppInstance使用者中斷連線時，訊息會停止。

a AppInstanceAdmin 和 a ChannelModerator 不會在通道上接收消息，除非您使用 CreateChannelMembershipAPI 明確添加它們。

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

了解訊息結構

您收到的每 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

下一節列出並說明標頭的可能值和有效載荷。

承載

網絡通訊端消息返回 JSON 字符串。JSON 字串的結構取決於標x-amz-event-type頭。下表列出了可能的x-amz-chime-event-type值和有效載荷：

EventType	裝載格式
`SESSION_ESTABLISHED`	N/A。此訊息會在使用者連線至之後傳送一次 WebSocket。這表示在使用者收到訊息之後到達的通道上的任何`SESSION_ESTABLISHED`訊息或事件，只要保 WebSocket 持開啟狀態，就能保證傳遞給使用者。
`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 帳戶層級調整該限制。 ReadMarker時間戳 `AppInstanceUser`最後一次將頻道標示為已讀取的時間。
`UPDATE_CHANNEL`	Channel
`DELETE_CHANNEL`	Channel
`BATCH_CREATE_CHANNEL_MEMBERSHIP`	BatchChannelMembership
`CREATE_CHANNEL_MEMBERSHIP`	ChannelMembership
`DELETE_CHANNEL_MEMBERSHIP`
`UPDATE_CHANNEL_MEMBERSHIP`

X-AMZ-鐘聲消息類型

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

訊息類型	描述
`STANDARD`	當網絡套接字收到一個標準的通道消息發送。
`CONTROL`	當 WebSocket 接收到控制通道消息發送。
`SYSTEM`	Amazon Chime SDK 消息發送的所有其他網絡通訊端消息。

X-阿姆斯-鐘聲事件原因

這是特定使用案例支援的選用標頭。標頭提供有關為什麼收到特定事件的信息。

事件原因	描述
子頻道已刪除 (_D)	`DELETE_CHANNEL_MEMBERSHIP`彈性通道管理員收到的事件。只有在成員資格平衡刪除了他們所屬的子頻道後，版主才能看到。

處理斷開

Websockets 可以斷開由於網絡連接的變化，或當憑據到期時斷開。在您開啟之後 WebSocket，Amazon Chime SDK 會將定期偵測傳送至簡訊用戶端，以確保它仍然保持連線狀態。如果連接關閉，客戶端會收到關 WebSocket 閉代碼。客戶端可以嘗試重新連接，或不重新連接，具體取決於關閉代碼。下表顯示用戶端可用來重新連線的結算代碼。

對於 1000 到 4000 的閉合代碼，請僅針對以下消息重新連接：

閉合代碼	可重新連線	原因
1001	是	正常關閉
1006	是	異常閉合
1011	是	內部伺服器錯誤
1012	是	服務重啟
1013	是	請稍後再試
1014	是	該服務器充當網關或代理，並收到來自上游服務器的無效響應。這類似於 502 HTTP 狀態碼。

對於 4XXX 代碼，除了以下消息之外，請始終重新連接：

閉合代碼	可重新連線	原因
4002	否	用戶端啟動
4003	否	禁止
4401	否	未獲授權

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

再次呼叫 GetMessagingSessionEndpointAPI 以取得新的基本網址。
如果 IAM 登入資料已過期，請重新整理。
透過連線 WebSocket。

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

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

使用 ExpirationSettings

配置附件