WebSockets 用于接收消息

您可以使用 Amazon Chime JS 软件开发工具包通过接收消息 WebSockets，也可以使用您选择的 WebSocket 客户端库。

按照列出的顺序遵循以下主题开始使用 WebSockets：

主题

定义 IAM 策略
检索终端节点
建立连接
使用预提取来传送频道详情
处理事件

定义 IAM 策略

首先，定义一个授予您建立 WebSocket 连接权限的 IAM 策略。以下示例策略AppInstanceUser授予建立 WebSocket连接的权限。


"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 返回的网址来构造签名版本 4 的签名 WebSocket 网址。如果您需要帮助，可以按照建立连接中的说明进行操作。

注意
WebSocket URL 的格式如下：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-Amz-Algorithm

标识 S AWS ignature 的版本和用于计算签名的算法。Amazon Chime SDK 仅支持 AWS 签名版本 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

列出用于计算签名的标头。签名计算中需要以下标头：

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 的身份。该值应为 AppInstanceUser 的 ARN。例如，arn:aws:chime:us%2Deast%2D1:123456789012:app%2Dinstance/694d2099%2Dcb1e%2D463e%2D9d64%2D697ff5b8950e/user/johndoe

使用预提取来传送频道详情

建立 WebSocket 连接时，可以在查询prefetch-on=connect中指定传递CHANNEL_DETAILS事件的参数。Connect API 附带了预提取功能，该功能使用户无需额外的 API 调用即可查看丰富的聊天视图。用户可以：

查看上一条频道消息的预览及其时间戳。
查看频道的成员。
查看频道的未读标记。

用户使用指定的预提取参数进行连接后，该用户会收到会话已建立事件，该事件表示连接已建立。然后，用户最多可接收 50 个 CHANNEL_DETAILS 事件。如果用户的频道少于 50 个，则 Connect API 会通过 CHANNEL_DETAILS 事件预提取所有频道。如果用户有超过 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，您必须将其添加到频道中。为此，请使用 CreateChannelMembershipAPI。

注意

AppInstanceUser 始终接收其所属各频道的消息。当 AppInstance 用户断开连接时，消息传递将停止。

除非您使用 CreateChannelMembershipAPI 明确添加消息，否则AppInstanceAdmin和 a ChannelModerator 不会在频道上接收消息。

下面的主题说明了如何处理事件。

了解消息结构

您收到的每 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 账户级别调整该限制。 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-chime-message-type

下表列出了 x-amz-chime-message-type 消息类型。

消息类型	描述
`STANDARD`	在 WebSocket 收到标准频道消息时发送。
`CONTROL`	在 WebSocket 收到控制频道消息时发送。
`SYSTEM`	Amazon Chime SDK 消息传递发送的所有其他 WebSocket 消息。

x-amz-chime-event-reason

这是特定用例支持的可选标头。标头提供有关接收特定事件的原因的信息。

事件原因	描述
subchannel_DELETED	弹性频道监管人收到的 `DELETE_CHANNEL_MEMBERSHIP` 事件。只有在成员资格平衡删除他们所属的子频道后，监管人才能看见。

处理断开连接

WebSocket 可能会因网络连接变化或凭证过期而断开连接。打开后 WebSocket，Amazon Chime 软件开发工具包会定期向消息客户端发送 ping，以确保其仍处于连接状态。如果连接关闭，则客户端会收到 WebSocket 关闭代码。客户端可以尝试也可以不尝试重新连接，具体取决于关闭代码。下表显示了客户端可用于重新连接的关闭代码。

对于关闭代码 1000 至 4000，仅针对以下消息重新连接：

关闭代码	是否可以重新连接	Reason
1001	是	正常关闭
1006	是	异常关闭
1011	是	内部服务器错误
1012	是	服务重新启动
1013	是	请稍后再试
1014	是	服务器充当网关或代理，收到来自上游服务器的无效响应。这与 HTTP 状态代码 502 类似。

对于 4XXX 代码，请务必重新连接，但以下消息除外：

关闭代码	是否可以重新连接	Reason
4002	否	客户端已启动
4003	否	禁止
4401	否	未授权

当应用程序使用关闭代码来重新连接时，应用程序应执行以下操作：

再次调用 GetMessagingSessionEndpointAPI 以获取新的基本网址。
如果 IAM 凭证已过期，请刷新它们。
通过 Connect 连接 WebSocket。

如果您使用该 amazon-chime-sdk-js 库，则在实现 ne edsRefresh () 属性和 refresh () 方法时会为您处理此问题。有关有效示例，请参阅 https://github.com/aws-samples/amazon-chime-sdk/blob/dc11c4c76c78d28f618577706bba2087919a5635/apps/chat/src/providers/ AuthProvider .jsx #L93-L101。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

使用 ExpirationSettings

配置附件