WebSockets 用于在 Amazon Chime 软件开发工具包消息中接收消息 - Amazon Chime SDK
定义 IAM 策略检索终端节点建立连接使用预提取处理事件

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

WebSockets 用于在 Amazon Chime 软件开发工具包消息中接收消息

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

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

定义 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连接中使用的端点。

  1. 使用 GetMessagingSessionEndpoint用于检索 WebSocket 端点的 API。

  2. 使用返回的网址 GetMessagingSessionEndpoint用于构造签名版本 4 签名 WebSocket 网址的 API。如果您需要帮助，可以按照 建立连接 中的说明进行操作。

    注意

    WebSocket URLs 有以下形式：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

标识 AWS 签名的版本和用于计算签名的算法。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 用户断开连接时，消息传递将停止。

除非您使用，否则AppInstanceAdmin和 a 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 收到标准频道消息时发送。

CONTROL

在 WebSocket 收到控制频道消息时发送。

SYSTEM

Amazon Chime SDK 消息传递发送的所有其他 WebSocket 消息。
x-amz-chime-event-原因

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

事件原因 描述

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

否

未授权

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

  1. 致电 GetMessagingSessionEndpoint再次使用 API 获取新的基本网址。

  2. 如果 IAM 凭证已过期，请刷新它们。

  3. 通过 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。