本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 使用 Amazon Chime SDK 消息传递
您可以使用《Amazon Chime SDK 开发人员指南》中的这一节来帮助创建在 Amazon Chime SDK 服务上运行的消息传递应用程序。此 SDK 提供了创建基本消息传递应用程序所需的概念和实用信息。
**Topics**
+ [迁移到 Amazon Chime SDK 身份命名空间](identity-namespace-migration.md)
+ [迁移到 Amazon Chime SDK 消息传递命名空间](messaging-namespace-migration.md)
+ [了解 Amazon Chime SDK 消息传递的先决条件。](messaging-prerequisites.md)
+ [了解 Amazon Chime SDK 消息传递的概念](messaging-concepts.md)
+ [了解 Amazon Chime SDK 消息传递的架构](messaging-architecture.md)
+ [了解 Amazon Chime SDK 消息类型](msg-types.md)
+ [开始使用 Amazon Chime SDK 消息传递](getting-started.md)
+ [了解用于 Amazon Chime SDK 消息传递的系统消息](system-messages.md)
+ [用于 Amazon Chime SDK 消息传递的 IAM 角色示例](iam-roles.md)
+ [了解按角色划分的授权](auth-by-role.md)
+ [在 Amazon Chime SDK 消息传递中流式传递消息数据](streaming-export.md)
+ [在 Amazon Chime SDK 消息传递中使用弹性频道举办实时事件](elastic-channels.md)
+ [在 Amazon Chime SDK 消息传递中使用移动推送通知接收消息](using-push-notifications.md)
+ [为 Amazon Chime SDK 消息传递使用服务相关角色](using-roles.md)
+ [在 Amazon Chime SDK 消息传递中使用频道流来处理消息](using-channel-flows.md)
+ [用 AppInstanceBots 作 Amazon Chime SDK 消息传递的智能渠道代理](appinstance-bots.md)
+ [在 Amazon Chime SDK 消息传递中管理消息保留日期](manage-retention.md)
+ [用于 Amazon Chime SDK 消息传递的 UI 组件](ui-components.md)
+ [将 Amazon Chime SDK 消息传递与客户端库集成](integrate-client-library.md)
+ [将 Amazon Chime SDK 消息传递与 JavaScript](use-javascript.md)
# 迁移到 Amazon Chime SDK 身份命名空间
[Amazon Chime SDK 身份](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Identity.html)命名空间是用户创建和管理 Amazon Chime SDK 身份资源（包括和）的专用场所。 APIs AppInstances AppInstanceUsers您可以使用命名空间来寻址 Amazon Chime SDK 身份 API 终端节点 AWS 所在的任何区域。如果您刚开始使用 Amazon Chime SDK，则使用此命名空间。有关“区域”的更多信息，请参阅本指南中的 [Amazon Chime SDK 可用的 AWS 区域](sdk-available-regions.md)。
使用 [Amazon Chime](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime.html) 命名空间的现有应用程序应计划迁移到专用命名空间。
**Topics**
+ [迁移原因](#identity-migration-reasons)
+ [迁移之前](#id-before-migrating)
+ [命名空间之间的差异](#id-namespace-differences)
## 迁移原因
出于以下原因，我们鼓励您迁移到 [Amazon Chime SDK 身份](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Identity.html)命名空间：
**选择 API 终端节点**
Amazon Chime SDK 身份命名空间是唯一可以在任何[提供 API 终端节点的区域](https://docs.aws.amazon.com/chime-sdk/latest/dg/sdk-available-regions.html)中使用 API 终端节点的 API 命名空间。如果您想使用 `us-east-1` 以外的 API 终端节点，则必须使用 Amazon Chime SDK 身份命名空间。有关当前终端节点的更多信息，请参阅本指南中的 [API 映射](migrate-from-chm-namespace.md#name-end-map)。
**更新和新的消息 APIs**
我们只在 Amazon Chime SDK 身份命名空间 APIs 中添加或更新身份。
## 迁移之前
在迁移之前，记下命名空间之间的差异。下表列出并描述了以上差异。
| | Amazon Chime SDK 身份命名空间 | Amazon Chime 命名空间 |
| --- | --- | --- |
| AWS SDK 名称空间 | ChimeSDKIdentity | Chime |
| 区域 | 多个 | 仅限 us-east-1 |
| 服务主体 | https://identity.chime.amazonaws.com | https://chime.amazonaws.com |
| APIs | 仅 APIs 用于身份 | APIs 获取身份信息和 Amazon Chime 的其他部分 |
| 用户过期 | Available | 不可用 |
| 自动程序 | Available | 不可用 |
## 命名空间之间的差异
以下各节解释了 `Chime` 与 `ChimeSDKIdentity` 命名空间之间的差异。
**AWS SDK 名称空间**
Amazon Chime SDK 命名空间使用 `Chime` 正式名称。Amazon Chime SDK 身份命名空间使用 `ChimeSDKIdentity` 正式名称。名称的确切格式因平台而异。
例如，如果您在 Node.js 中使用 AWS SDK 来创建身份，则使用一行代码来寻址命名空间。
```
const chimeIdentity = AWS.Chime();
```
若要迁移到 `ChimeSDKIdentity` 命名空间，请使用新的命名空间和终端节点区域更新这行代码。
```
const chimeIdentity = AWS.ChimeSDKIdentity({ region: "eu-central-1" });
```
**区域**
[Amazon Chime](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime.html) 命名空间只能寻址该 `us-east-1` 地区的 API 终端节点。[Amazon Chime SDK 身份](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Identity.html)命名空间可以在任何可用区域中寻址 Amazon Chime SDK 身份 API 终端节点。有关终端节点区域的最新列表，请参阅本指南中的 [Amazon Chime SDK 可用的 AWS 区域](sdk-available-regions.md)。
**了解如何查看、监控和管理 SageMaker 端点。**
[Amazon Chime SDK 身份](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Identity.html)命名空间使用不同于 [Amazon Chime](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime.html) 命名空间的 API 终端节点。
只有用于创建身份资源的终端节点才能用于更新这些资源。这意味着通过中的端点 AppInstance 创建的`eu-central-1`只能通过进行修改`eu-central-1`。这也意味着你不能在使用 Chime 命名空间的情况下寻址通过 Chime SDKIdentity 命名空间创建的频道`us-east-1`，也不能在创建 AppInstance 和 AppInstanceUser 成员的区域之外的区域中创建频道。 AppInstance 有关当前终端节点的更多信息，请参阅本指南中的 [API 映射](migrate-from-chm-namespace.md#name-end-map)。
**服务主体**
[Amazon Chime SDK 身份](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Messaging.html)命名空间使用了新的服务主体：`Identity.chime.amazonaws.com`。如果您有授予服务访问权限的 SQS、SNS 或其他 IAM 访问策略，则需要更新这些策略以授予新服务主体访问权限。
**APIs**
[Amazon Chime SDK 身份](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Identity.html)命名空间仅包含 APIs 用于创建和管理消息资源以及用于发送和接收消息的内容。A [mazon Chime](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime.html) 命名空间包括 APIs 亚马逊 Chime 服务的其他部分以及消息。
**用户过期**
创建时的过期设置 AppInstanceUsers 允许您创建临时用户。例如，您可以创建仅在大型广播期间存在的聊天用户。只有身份命名空间支持过期设置 AppInstanceUsers。
**自动程序**
你用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_identity-chime_AppInstanceBot.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_identity-chime_AppInstanceBot.html)用于将由 Amazon Lex V2 提供支持的聊天机器人添加到您的应用程序中的 API。您只能在身份命名空间 AppInstanceBots 中使用。有关自动程序的更多信息，请参阅本指南中的 [用 AppInstanceBots 作 Amazon Chime SDK 消息传递的智能渠道代理](appinstance-bots.md)。
**额外 APIs**
Identity 命名空间越来越多了 Chime 命名空间所没有的额外 APIs 内容。如果您刚开始使用 Amazon Chime SDK，请使用身份命名空间来访问所有最新功能。有关当前版本的更多信息 APIs，请参阅《[亚马逊 Chime SDK API 参考》中的 A *mazon Chime* SDK 身份](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Identity.html)。
# 迁移到 Amazon Chime SDK 消息传递命名空间
[Amazon Chime SDK 消息传递](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Messaging.html)命名空间是创建和管理 Amazon Chime SDK 消息资源的专用场所。 APIs 您可以使用命名空间在 Amazon Chime SDK 消息传递 API 端点所在的任何 AWS 区域对其进行寻址。如果您刚开始使用 Amazon Chime SDK，则使用此命名空间。有关“区域”的更多信息，请参阅本指南中的 [Amazon Chime SDK 可用的 AWS 区域](sdk-available-regions.md)。
使用 [Amazon Chime](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime.html) 命名空间的现有应用程序应计划迁移到专用命名空间。
**Topics**
+ [迁移原因](#migration-reasons)
+ [迁移之前](#before-migrating)
+ [命名空间之间的差异](#namespace-differences)
## 迁移原因
出于以下原因，我们鼓励您迁移到 [Amazon Chime SDK 消息传递](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Messaging.html)命名空间：
**选择 API 终端节点**
Amazon Chime SDK 消息传递命名空间是唯一可以在任何[提供 API 端点的区域](https://docs.aws.amazon.com/chime-sdk/latest/dg/sdk-available-regions.html)中使用 API 端点的 API 命名空间。如果您想使用美国东部（弗吉尼亚州北部）以外的 API 端点，则必须使用 Amazon Chime SDK 消息传递命名空间。
有关 Amazon Chime SDK 消息传递如何使用 AWS 区域的更多信息，请参阅本指南中的[可用区域](https://docs.aws.amazon.com/chime-sdk/latest/dg/available-regions.html)。
**更新和新的消息 APIs**
我们只在 Amazon Chime SDK 消息传送命名空间 APIs 中添加或更新消息。
## 迁移之前
在迁移之前，记下命名空间之间的差异。下表列出并描述了以上差异。
| | Amazon Chime SDK 消息传递命名空间 | Amazon Chime 命名空间 |
| --- | --- | --- |
| AWS SDK 名称空间 | ChimeSDKMessaging | Chime |
| 区域 | 多个 | 仅限美国东部（弗吉尼亚州北部） |
| APIs | 仅 APIs 用于发送消息 | APIs 用于消息和 Amazon Chime 的其他部分 |
| 流 | 可用 | 不可用 |
| 弹性频道 | 可用 | 不可用 |
## 命名空间之间的差异
以下各节解释了 `Amazon Chime` 与 `Amazon Chime SDK Messaging` 命名空间之间的差异。
**AWS SDK 名称空间**
Amazon Chime SDK 命名空间使用 `Chime` 正式名称。Amazon Chime SDK 消息传递命名空间使用 `ChimeSDKMessaging` 正式名称。名称的确切格式因平台而异。
例如，如果您在 Node.js 中使用 AWS SDK 来创建消息，则使用一行代码来寻址命名空间。
```
const chimeMessaging = AWS.Chime();
```
要迁移到 Amazon Chime Messaging SDK，请使用新的命名空间和终端节点区域更新这行代码。
```
const chimeMessaging = AWS.ChimeSDKMessaging({ region: "Europe (Frankfurt)" });
```
**Regions**
[Amazon Chime](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime.html) 命名空间只能寻址该 `US East (N. Virginia)` 地区的 API 终端节点。[Amazon Chime SDK 消息传递](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Messaging.html)命名空间可以在任何可用区域中寻址 Amazon Chime SDK 消息传递 API 终端节点。有关最新的消息传递区域列表，请参阅本指南中的 [Amazon Chime SDK 可用的 AWS 区域](sdk-available-regions.md)。
**端点**
[Amazon Chime SDK 消息传递](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Messaging.html)命名空间使用与 [Amazon Chime](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime.html) 命名空间不同的 API 终端节点。
只能使用用于创建消息传递资源的终端节点对其进行修改。这意味着通过 `Europe (Frankfurt)` 中的终端节点创建的消息传递资源只能通过 `Europe (Frankfurt)` 进行修改。这意味着通过欧洲地区（法兰克福）中的端点创建的频道只能通过欧洲地区（法兰克福）进行修改。这也意味着您无法寻址通过 `Chime` 命名空间创建且 `ChimeSDKMessaging` 命名空间位于美国东部（弗吉尼亚州北部）的频道。有关当前终端节点的更多信息，请参阅本指南中的 [API 映射](migrate-from-chm-namespace.md#name-end-map)。
**服务主体**
[Amazon Chime SDK 消息传递](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Messaging.html)命名空间使用了新的服务主体：`messaging.chime.amazonaws.com`。如果您有授予服务访问权限的 SQS、SNS 或其他 IAM 访问策略，则需要更新这些策略以授予新服务主体访问权限。
**APIs**
[Amazon Chime SDK 消息传送](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Messaging.html)命名空间仅包含 APIs 用于创建和管理消息资源以及用于发送和接收消息的内容。[Amazon Chime](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime.html) 命名空间包括 APIs 亚马逊 Chime 服务的其他部分以及消息传递。
**频道流**
频道流允许开发人员在将动态消息传递给消息传递频道成员之前，对这些消息运行业务逻辑。例如，您可以创建流程，在发送消息之前从消息中删除敏感数据，例如身份证号、电话号码或污言秽语。这可以帮助实施企业传播策略或其他沟通准则。
您还可以使用频道流来执行一些功能，例如在将结果发送回给参与者之前汇总对民意调查的回复，或者通过短信发送消息。
频道流仅在 `ChimeSDKMessaging` 命名空间中可用。有关更多信息，请参阅本指南中的 [在 Amazon Chime SDK 消息传递中使用频道流来处理消息](using-channel-flows.md)。
**弹性频道**
弹性频道支持大规模的聊天体验，多达 100 万聊天用户可在指定数量的子频道中自动平衡。弹性频道仅在 `ChimeSDKMessaging` 终端节点中可用。有关弹性频道的更多信息，请参阅本指南中的 [在 Amazon Chime SDK 消息传递中使用弹性频道举办实时事件](elastic-channels.md)。
**额外 APIs**
Messaging 命`Chime`名空间 APIs 中没有的列表越来越多。如果您刚开始使用 Amazon Chime SDK，请使用消息传递命名空间来访问所有最新功能。有关当前版本的更多信息 APIs，请参阅《[亚马逊 Chime SDK API 参考》中的 A *mazon Chime* SDK 消息](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Messaging.html)。
# 了解 Amazon Chime SDK 消息传递的先决条件。
您需要以下内容才能使用 Amazon Chime SDK 消息传递。
+ 编程能力。
+ 一个 AWS 账户。
+ 使用 Amazon Chime SDK 消息传递为应用程序配置 IAM 角色的权限。
在大多数情况下，您还需要：
+ **客户端应用程序** — 显示消息传递用户界面，使用 Amazon Chime 连接网络套接字 SDKs，管理状态。
+ **服务器应用程序**：管理身份和用户。
# 了解 Amazon Chime SDK 消息传递的概念
要有效地使用 Amazon Chime SDK 消息传递，您必须了解以下术语和概念。
**AppInstance**
要使用 Amazon Chime 软件开发工具包消息，您必须先创建一个。 AppInstance AppInstance包含 AppInstanceUsers 和频道。通常，您可以 AppInstance为应用程序创建单曲。一个 AWS 账户可以有多个 AppInstances。你可以在该级别进行应用程序级别的设置，例如消息保留和直播配置。 AppInstance AppInstances 由以下格式的唯一 ARN 标识：。`arn:aws:chime:region:aws_account_id:app-instance/app_instance_id`
**AppInstanceUser**
AppInstanceUsers 是发送消息、创建频道、加入频道等的实体。通常，您可以创建`AppInstanceUser`与应用程序用户的 one-to-one映射。您还可以创建`AppInstanceUser`连接到后端服务，这样用户就可以将消息识别为来自后端服务。 AppInstanceUsers 由 ARN 识别，例如。`arn:aws:chime:region:aws_account_id:app-instance/app_instance_id/user/app_instance_user_id`您可以控制`app_instance_user_id`，作为最佳实践， IDs 可以重复使用您的应用程序已有的。
**频道**
当您向频道添加 `AppInstanceUser` 时，该用户将成为成员并可以发送和接收消息。频道可以是公开的，允许任何用户将自己添加为成员，也可以是私人频道，后者只允许频道监管人添加成员。您也可以隐藏频道成员。隐藏成员可以观察对话但不能发送消息，而且他们不会被添加到频道成员资格中。
**SubChannel**
弹性通道的成员被分成一个名为的逻辑容器 SubChannels。当您 AppInstanceUser 向弹性通道中添加时，用户将成为其成员， SubChannel 并且可以发送和接收该特定通道的消息 SubChannel。频道成员资格和消息处于一定 SubChannel 级别，这意味着其中一个成员发送的消息 SubChannel 不会被另一个 SubChannel成员接收。成员被转移到不同的渠道 SubChannels ，以支持渠道的弹性并促进参与度。
**UserMessage**
属于频道的 `AppInstanceUser` 可以发送和接收用户消息。`AppInstanceUser` 可以发送 `STANDARD` 或 `CONTROL` 消息。`STANDARD` 消息可以包含 4KB 的数据和 1KB 的元数据。`CONTROL` 消息只能包含 30 字节的数据。消息可以是 `PERSISTENT` 或 `NON_PERSISTENT`。您可以从频道历史记录中检索 `PERSISTENT` 消息。`NON_PERSISTENT` 只有当前连接到 Amazon Chime SDK 消息的频道成员才能看到消息。
**系统消息**
Amazon Chime SDK 会生成系统消息，以响应诸如成员加入或离开频道之类的事件。
# 了解 Amazon Chime SDK 消息传递的架构
您可以将 Amazon Chime SDK 消息传递作为服务器端和客户端 SDK 使用。服务器端 APIs 创建`AppInstance`和。`AppInstanceUser`您可以使用各种挂钩和配置来添加特定于应用程序的业务逻辑和验证。有关如何执行该操作的更多信息，请参阅 [在 Amazon Chime SDK 消息传递中流式传递消息数据](streaming-export.md)。此外，服务器端进程可以 APIs 代表调用或控制代表后端进程`AppInstanceUser`的专用进程。`AppInstanceUser`
表示为的客户端应用程序`AppInstanceUser`可以直接调用 Amazon Chime 软件开发工具包 APIs 消息。客户端应用程序在联机时使用该 WebSocket 协议连接到消息传递 SDK。连接后，他们会收到来自他们所属的任何频道的实时消息。断开连接后，`AppInstanceUser`仍属于其添加的频道，它可以使用基于 HTTP 的 SDK 来加载这些频道的消息历史记录 APIs。
客户端应用程序有权将 API 调用作为单个 `AppInstanceUser`。要将 IAM 证书的范围限定为单个`AppInstanceUser`，客户端应用程序通过 Cog AWS nito 身份池或小型自托管后端 API 担任参数化的 IAM 角色。有关身份验证的更多信息，请参阅 [对最终用户客户端应用程序进行身份验证以便进行 Amazon Chime SDK 消息传递](auth-client-apps.md)。相比之下，服务器端应用程序的权限通常与单个应用程序实例用户绑定，例如具有管理权限的用户，或者它们有权代表所有应用程序实例用户进行 API 调用。
# 了解 Amazon Chime SDK 消息类型
您通过频道发送消息。您可以发送 `STANDARD`、`CONTROL` 或 `SYSTEM` 消息。
+ `STANDARD` 消息大小最多可达 4KB，并且包含元数据。元数据是任意的，您可以通过多种方式使用它，例如包含指向附件的链接。
+ `CONTROL` 消息不超过 30 字节，并且不包含元数据。
+ `STANDARD` 和 `CONTROL` 消息可以是永久性消息或非永久性消息。永久性消息保留在频道的历史记录中，并通过 `ListChannelMessages` API 调用进行查看。非永久性消息将发送给每个通过`AppInstanceUser`连接的用户 WebSocket。
+ Amazon Chime SDK 会针对成员加入或离开频道之类的事件自动发送 `SYSTEM` 消息。
# 开始使用 Amazon Chime SDK 消息传递
本节中的主题介绍了如何开始生成 Amazon Chime SDK 消息传递应用程序。
**Topics**
+ [创建用于 Amazon Chime SDK 消息传递的 AppInstance](create-app-instance.md)
+ [如何从后端服务发出 SDK 调用以便进行 Amazon Chime SDK 消息传递](call-from-backend.md)
+ [对最终用户客户端应用程序进行身份验证以便进行 Amazon Chime SDK 消息传递](auth-client-apps.md)
+ [创建用于 Amazon Chime SDK 消息传递的频道](creating-channels.md)
+ [在 Amazon Chime SDK 消息传递中发送消息](send-messages.md)
+ [ExpirationSettings 在 Amazon Chime 软件开发工具包消息中使用](expiration.md)
+ [WebSockets 用于在 Amazon Chime 软件开发工具包消息中接收消息](websockets.md)
+ [在 Amazon Chime SDK 消息传递中配置附件](configure-attachments.md)
# 创建用于 Amazon Chime SDK 消息传递的 AppInstance
要使用 Amazon Chime 软件开发工具包消息，您必须先在账户中创建亚马逊 Chime `AppInstance` 软件开发工具包。 AWS
**Topics**
+ [创建 AppInstance](#app-instance-steps)
+ [创建一个 AppInstanceUser](#create-app-instance-user)
## 创建 AppInstance
**为消息传递创建 `AppInstance`**
1. 在 CLI 中，运行 `aws chime-sdk-identity create-app-instance --name NameOfAppInstance.`
1. 在“创建响应”中，记下 `AppInstanceArn` 和 `arn:aws:chime:region: aws_account_id:app-instance/app_instance_id`。
## 创建一个 AppInstanceUser
一旦您创建了一个 `AppInstance`，您就可以在该 `AppInstance` 中创建一个 `AppInstanceUser`。通常是在用户首次注册或登录应用程序时执行此操作。您也可以创建代表后端服务运行的 `AppInstanceUser`。
以下示例介绍了如何创建一个后端 `AppInstanceUser`。
```
aws chime-sdk-identity create-app-instance-user \
--app-instance-arn "app_instance_arn" \
--app-instance-user-id "back-end-worker" \
--name "back-end-worker"
```
在“创建响应”时，记下 `AppInstanceUserArn`。其形式为：`arn:aws:chime:region: aws_account_id:app-instance/app_instance_id/user/app_instance_user_id`。在本例中，`app_instance_user_id`是 “back-end-worker。”
**注意**
作为最佳实践，在为客户端应用程序创建 `AppInstanceUser` 时，请将 `AppInstanceUserId` 匹配该用户的现有唯一 ID（例如身份提供商的 `sub`）。该名称是附加到某些 API 实体（例如消息发送者）的可选占位符。它允许您在一个地方控制用户的显示名称，而不必从 `AppInstanceUser` ARN 中查找，ARN 也作为消息的发件人附上。
# 如何从后端服务发出 SDK 调用以便进行 Amazon Chime SDK 消息传递
创建代表后端服务的用户后，您就可以创建一个频道，向该频道发送消息，并从该频道读取消息。
运行以下 CLI 命令来创建一个公有通道。
```
aws chime-sdk-messaging create-channel \
--chime-bearer "app_instance_user_arn" \
--app-instance-arn "app_instance_arn" \
--name "firstChannel"
```
该命令生成以下格式的 ARN：`arn:aws:chime:region:aws_account_id:app-instance/app_instance_id/channel/channel_id.`
**Topics**
+ [后端服务的 IAM 授权是如何运作的](#how-iam-works)
+ [了解隐式 API 授权](#api-implicit-auth)
+ [发送和列出频道消息](#send-list-msgs)
## 后端服务的 IAM 授权是如何运作的
在上一节的 CLI 命令中，记下该 `chime-bearer` 参数。它识别创建频道和消息等资源或与之交互的用户。几乎所有 Amazon Chime SDK 消息 APIs 都以参数`chime-bearer`为参数 APIs ，但只能由开发者调用，例如。`CreateAppInstance`
Amazon Chime 软件开发工具包消息的 IAM 权限 APIs 需要与`app-instance-user-arn `参数匹配的。`chime-bearer`根据 API， ARNs可能需要额外的 ARNs（通常是渠道）。对于像上面示例这样的后端服务，这会导致 IAM 策略，如下例所示：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": [
"chime:SendChannelMessage",
"chime:ListChannelMessages",
"chime:CreateChannelMembership",
"chime:ListChannelMemberships",
"chime:DeleteChannelMembership",
"chime:CreateChannel",
"chime:ListChannels",
"chime:DeleteChannel"
],
"Resource": [
"arn:aws:chime:us-east-1:123456789012:app-instance/app_instance_id/user/back-end-worker",
"arn:aws:chime:us-east-1:123456789012:app-instance/app_instance_id/channel/*"
]
}
}
```
------
记下 `Resource` 章节中的 `AppInstanceUser` ARN 和频道 ARN。此 IAM 策略示例向后端服务授予以 ID 为 “” 的用户身份进行 API 调用的权限back-end-worker。 如果您希望您的后端服务能够为使用您的应用程序的用户拨打电话，请将更改`app_instance_user_arn`为`arn:aws:chime:region:aws_account_id:app-instance/app_instance_id/user/*`。
## 了解隐式 API 授权
除了 IAM 策略外，Amazon Chime 软件开发工具包消息还 APIs 具有隐式权限。例如，`AppInstanceUser` 只能发送消息或列出用户所属频道的频道成员资格。其中一个例外情况是提升为 `AppInstanceAdmin` 的 `AppInstanceUser`。默认情况下，管理员有权访问应用程序中的所有频道。对于大多数用例，只有包含重要业务逻辑的后端服务才需要此功能。
以下 CLI 命令将后端用户提升为管理员。
```
aws chime-sdk-identity create-app-instance-admin \
--app-instance-admin-arn "app_instance_user_arn" \
--app-instance-arn "app_instance_arn"
```
## 发送和列出频道消息
以下 CLI 命令发送频道消息。
```
aws chime-sdk-messaging send-channel-message \
--chime-bearer "app_instance_user_arn" \
--channel-arn "channel_arn" \
--content "hello world" \
--type STANDARD \
--persistence PERSISTENT
```
以下 CLI 命令按反向的时间顺序列出频道消息。
+ `aws chime list-channel-messages`
+ `aws chime-sdk-messaging list-channel-messages`
```
aws chime-sdk-messaging list-channel-messages \
--chime-bearer "app_instance_user_arn" \
--channel-arn "channel_arn"
```
# 对最终用户客户端应用程序进行身份验证以便进行 Amazon Chime SDK 消息传递
您还可以通过最终用户客户端应用程序运行 Amazon Chime 软件开发工具包消息。 [如何从后端服务发出 SDK 调用以便进行 Amazon Chime SDK 消息传递](call-from-backend.md)解释了如何进行 API 调用，例如 create-channel send-channel-message、和。 list-channel-messages浏览器和移动应用程序等最终用户客户端应用程序会进行相同的 API 调用。客户端应用程序还可以通过连接 WebSocket ，以接收其所属频道的消息和事件的实时更新。本节介绍如何向限于特定应用程序实例用户的客户端应用程序提供 IAM 凭证。最终用户获得这些凭证后，可以进行 [如何从后端服务发出 SDK 调用以便进行 Amazon Chime SDK 消息传递](call-from-backend.md) 中所示的 API 调用。要查看客户端应用程序的完整演示，请参阅 [ https://github.com/aws-samples/amazon-chime-sdk/tree/main/apps/chat](https://github.com/aws-samples/amazon-chime-sdk/tree/main/apps/chat)。有关接收来自客户端应用程序所属频道的实时消息的更多信息，请参阅 [WebSockets 用于在 Amazon Chime 软件开发工具包消息中接收消息](websockets.md)。
## 向最终用户提供 IAM 凭证
Amazon Chime SDK 消息传递与 AWS 身份和访问管理 (IAM) 策略进行原生集成，用于对传入的请求进行身份验证。IAM 策略定义了个人用户可以做什么。可以制定 IAM 策略来为用例提供范围有限的凭证。有关为 Amazon Chime SDK 消息传递用户创建策略的更多信息，请参阅 [用于 Amazon Chime SDK 消息传递的 IAM 角色示例](iam-roles.md)。
如果您已有身份提供商，则可以使用以下选项将现有身份与 Amazon Chime SDK 消息传递集成。
+ 您可以使用现有的身份提供商对用户进行身份验证，然后将身份验证服务与 AWS 安全令牌服务 (STS) 集成，为客户创建自己的凭证自动售货服务。STS 允许 APIs 担任 IAM 角色。
+ 如果您已经有兼容 SAML 或 OpenID 的身份提供商，我们建议您使用 Amazon [Cognito 身份池](https://docs.aws.amazon.com/cognito/latest/developerguide/identity-pools.html)，以便提取对 AWS STS [https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) 和 [https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) 的调用。Amazon Cognito 集成了 OpenID、SAML 和公共身份提供商，如 Facebook、Login with Amazon、Google 和 Sign in with Apple。
如果您没有身份提供商，则可以开始使用 Amazon Cognito 用户群体。有关如何将 Amazon Cognito 与 Amazon Chime SDK 消息传递功能配合使用的示例，请参阅[使用 Amazon Chime SDK 消息传递在应用程序中构建聊天功能](https://aws.amazon.com/blogs/business-productivity/build-chat-features-into-your-application-with-amazon-chime-sdk-messaging/)。
或者，您可以使用 [AWS STS](https://docs.aws.amazon.com/STS/latest/APIReference/welcome.html) 创建自己的凭证售卖服务或构建自己的身份提供商。
**使用 STS 出售凭证**
[如果您已经拥有 IDP（例如 ActiveDirectory LDAP），并且想要实现自定义凭证自动售卖服务，或者向未经身份验证的会议与会者授予聊天权限，则可以使用 STS API。AWSAssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)为此，您需要首先创建一个 Amazon Chime SDK 消息传递 SDK 角色。有关创建该角色的更多信息，请参阅[创建将权限委派给 IAM 用户的角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html)。
该 IAM 角色将有权访问应用程序将使用的 Amazon Chime SDK 消息传递操作，如下所示：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"chime:GetMessagingSessionEndpoint"
],
"Resource": [
"*"
]
},
{
"Effect": "Allow",
"Action": [
"chime:SendChannelMessage",
"chime:ListChannelMessages",
"chime:CreateChannelMembership",
"chime:ListChannelMemberships",
"chime:DeleteChannelMembership",
"chime:CreateChannelModerator",
"chime:ListChannelModerators",
"chime:DescribeChannelModerator",
"chime:CreateChannel",
"chime:DescribeChannel",
"chime:ListChannels",
"chime:DeleteChannel",
"chime:RedactChannelMessage",
"chime:UpdateChannelMessage",
"chime:Connect",
"chime:ListChannelBans",
"chime:CreateChannelBan",
"chime:DeleteChannelBan",
"chime:ListChannelMembershipsForAppInstanceUser",
"chime:AssociateChannelFlow",
"chime:DisassociateChannelFlow",
"chime:GetChannelMessageStatus"
],
"Resource": [
"arn:aws:chime:us-east-1:123456789012:app-instance/app_instance_id/user/my_applications_user_id",
"arn:aws:chime:us-east-1:123456789012:app-instance/app_instance_id/channel/*"
]
}
]
}
```
------
在本示例中，将此角色称为*ChimeMessagingSampleAppUserRole*。
请注意用户 ARN 资源中*ChimeMessagingSampleAppUserRole*策略`${my_application_user_id}`中的会话标签。此会话标签在 [https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) API 调用中进行了参数化，以将返回的凭证限制为只拥有单个用户的权限。
使用已获得认证[https://docs.aws.amazon.com/STS/latest/APIReference/API_TagSesstion.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_TagSesstion.html) APIs 的 IAM 实体（例如 IAM 用户）调用[https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)和。 APIs 也可以由不同的 IAM 角色调用，例如[AWS Lambda 运行角色](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html)。该 IAM 身份必须具有调用`AssumeRole`和`TagSession`开启的权限*ChimeMessagingSampleAppUserRole*。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"sts:AssumeRole",
"sts:TagSession"
],
"Resource": "arn:aws:iam::123456789012:role/ChimeMessagingSampleAppUserRole"
}
]
}
```
------
在本示例中，将此角色称为*ChimeSampleAppServerRole*。
您需要将 `ChimeMessagingSampleAppUserRole` 的信任策略设置为允许 `ChimeMessagingSampleAppServerRole` 调用其上的 [STS AssumeRole API](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。有关将 IAM 角色与信任策略结合使用的更多信息，请参阅[如何将 IAM 角色与信任策略结合使用](https://aws.amazon.com/blogs/security/how-to-use-trust-policies-with-iam-roles/)。您可以使用 AWS IAM 角色控制台将此策略添加到`ChimeMessagingSampleAppUserRole`。以下示例介绍了一种典型的信任关系。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::123456789012:role/ChimeMessagingSampleAppServerRole"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
在示例部署中，A [mazon EC2](https://aws.amazon.com/ec2/) 实例 AWS Lambda 或使用启动`ChimeMessagingSampleAppServerRole`。然后，服务器：
1. 对客户端接收凭证的请求执行任何特定于应用程序的授权。
1. 在 `ChimeMessagingSampleAppUserRole` 上调用 STS `AssumeRole`，并使用标签来参数化 `${aws:PrincipalTag/my_applications_user_id}`。
1. 将 `AssumeRole` 调用中返回的凭证转发给用户。
以下示例介绍了在步骤 2 中扮演角色的 CLI 命令：
`aws sts assume-role --role-arn arn:aws:iam::my_aws_account_id:role/ChimeMessagingSampleAppUserRole --role-session-name demo --tags Key=my_applications_user_id,Value=123456789 `
# 创建用于 Amazon Chime SDK 消息传递的频道
您和您的最终用户可以创建频道。创建后，您或您的最终用户还需要向频道添加成员。用于创建频道的示例代码可在[上的示例应用程序](https://github.com/aws-samples/amazon-chime-sdk/tree/main/apps/chat)中找到 GitHub。
关于创建频道和添加成员的更多信息，请参阅：
+ [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannel.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannel.html)
+ [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html)
# 在 Amazon Chime SDK 消息传递中发送消息
使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_SendChannelMessage.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_SendChannelMessage.html) API 发送消息。示例代码可在[上的示例应用程序](https://github.com/aws-samples/amazon-chime-sdk/tree/main/apps/chat)中找到 GitHub。
# ExpirationSettings 在 Amazon Chime 软件开发工具包消息中使用
创建`AppInstanceUser`或时`Channel`，您可以使用`ExpirationSettings`将这些资源配置为自动删除。 `ExpirationSettings`有助于降低存储成本并防止出现 resource-limit-exceeded问题。例如，您可以在 7 天后删除未使用的频道，或者删除仅为测试目的调用的 `AppInstanceUser`。
对于 `AppInstanceUser`，您可以根据用户创建时间来指定过期时间。对于 `Channel`，您可以根据频道的创建时间或上次消息时间来指定过期时间。后者允许您使用消息事件来自定义自动删除。
**重要**
资源过期后不久，`ExpirationSettings` 启动后台进程以删除该资源。该过程通常需要 6 个小时，但时间可能会有所不同。
已过期且尚未删除的 `AppInstanceUsers` 和 `Channels` 仍显示为有效且处于活动状态。您可以更新或删除他们的过期设置，系统会接受您的更改。
**Topics**
+ [正在配置 ExpirationSettings](#create-expiration)
+ [AWS CloudTrail 删除过期资源的事件](#ct-events)
## 正在配置 ExpirationSettings
以下各节说明如何配置 `AppInstanceUser` 或 `Channel` 的 `ExpirationSettings`。
### 在创建资源时配置 ExpirationSettings
您可以配置`ExpirationSettings`何时运行[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateAppInstanceUser.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateAppInstanceUser.html)或[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannel.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannel.html) APIs。如果设置 `ExpirationSettings` 参数，您必须授予以下 IAM 权限：
+ 创建 `AppInstanceUser` 时的 `chime:PutAppInstanceUserExpirationSettings`
+ 创建 `Channel` 时的 `chime:PutChannelExpirationSettings`。
以下示例使用 AWS CLI 创建在一天后`AppInstanceUser`过期的。
```
aws chime-sdk-identity create-app-instance-user \
--app-instance-arn "app_instance_arn" \
--app-instance-user-id "backend-worker" \
--name "backend-worker" \
--expiration-settings '{
"ExpirationDays": 1,
"ExpirationCriterion": "CREATED_TIMESTAMP"
}'
```
以下示例使用 AWS CLI 创建在上次收到消息后一天后过期的。`Channel`
```
aws chime-sdk-messaging create-channel \
--chime-bearer "app_instance_user_arn" \
--app-instance-arn "app_instance_arn" \
--name "firstChannel" \
--expiration-settings '{
"ExpirationDays": 1,
"ExpirationCriterion": "LAST_MESSAGE_TIMESTAMP"
}'
```
### 使用 Put APIs 进行配置 ExpirationSettings
您也可以使用[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_PutAppInstanceUserExpirationSettings.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_PutAppInstanceUserExpirationSettings.html)和[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_PutChannelExpirationSettings.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_PutChannelExpirationSettings.html) APIs 来创建、更新和删除`ExpirationSettings`。
以下示例演示如何使用 AWS CLI 更新`AppInstanceUser`的`ExpirationSettings`。
```
aws chime-sdk-identity put-app-instance-user-expiration-settings \
--app-instance-user-arn "app_instance_user_arn" \
--expiration-settings '{
"ExpirationDays": 30,
"ExpirationCriterion": "CREATED_TIMESTAMP"
}'
```
以下示例演示如何使用 AWS CLI 删除频道`ExpirationSettings`。
```
aws chime-sdk-messaging put-channel-expiration-settings \
--chime-bearer "app_instance_user_arn" \
--channel-arn "channel_arn"
```
## AWS CloudTrail 删除过期资源的事件
在系统删除过期的资源后，它会向发送`ExpireAppInstanceUser`或`ExpireChannel`事件 AWS CloudTrail。事件的类型取决于已删除资产的类型。
以下示例介绍了 `AppInstanceUser` 事件。
```
{
"eventVersion": "1.08",
"userIdentity": {
"accountId": "123456789012",
"invokedBy": "chime.amazonaws.com"
},
"eventTime": "2023-03-15T00:00:00Z",
"eventSource": "chime.amazonaws.com",
"eventName": "ExpireAppInstanceUser",
"awsRegion": "us-east-1",
"sourceIPAddress": "chime.amazonaws.com",
"userAgent": "chime.amazonaws.com",
"requestParameters": null,
"responseElements": null,
"eventID": "12345678-1234-1234-1234-123456789012",
"readOnly": false,
"resources": [
{
"accountId": "123456789012",
"type": "AWS::Chime::AppInstanceUser",
"ARN": "arn:aws:chime:us-east-1:123456789012:app-instance/app-instance-id/user/user-id"
}
],
"eventType": "AwsServiceEvent",
"managementEvent": true,
"recipientAccountId": "123456789012",
"serviceEventDetails": {
"reason": "AppInstanceUser deleted due to expiration settings."
},
"eventCategory": "Management"
}
```
# WebSockets 用于在 Amazon Chime 软件开发工具包消息中接收消息
您可以使用 [Amazon Chime JS 软件开发工具包](https://github.com/aws/amazon-chime-sdk-js)通过接收消息 WebSockets，也可以使用您选择的 WebSocket 客户端库。
按照列出的顺序遵循以下主题开始使用 WebSockets：
**Topics**
+ [定义 IAM 策略](#define-iam-policy)
+ [检索终端节点](#retrieve-endpoint)
+ [建立连接](#connect-api)
+ [使用预提取来传送频道详情](#prefetch)
+ [处理事件](#process-events)
## 定义 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. 使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html)API 检索 WebSocket 端点。
1. 使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html)API 返回的网址来构造签名版本 4 的签名 WebSocket 网址。如果您需要帮助，可以按照 [建立连接](#connect-api) 中的说明进行操作。
**注意**
WebSocket URLs 有以下形式：`id.region.ws-messaging.chime.aws`
## 建立连接
检索终端节点后，您可以使用 WebSocket 连接 API 建立与 Amazon Chime SDK 后端服务器的连接并接收消息。`AppInstanceUser`您必须使用 AWS 签名版本 4 来签署请求。有关对请求进行签名的更多信息，请参阅[利用签名版本 4 对 AWS 请求进行签名](https://docs.aws.amazon.com/general/latest/gr/Signature Version 4_signing.html)。
**注意**
要检索端点，您可以调用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html) 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-Algorithm**
标识 S AWS ignature 的版本和用于计算签名的算法。Amazon Chime SDK 仅支持 AWS 签名版本 4 身份验证，因此其值是 `AWS4-HMAC-SHA256`。
**X-Amz-Credential**
除了您的访问密钥 ID 之外，此参数还提供签名有效的 AWS 区域和服务（范围）。该值必须与您在签名计算中使用的范围匹配。该参数值的一般形式为：
`////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-\$1 标头。
**注意**
为了提高安全性，签署计划在请求中包含的所有请求标头。
**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](https://docs.aws.amazon.com/STS/latest/APIReference/welcome.html)。
**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** — [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessageSummary.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessageSummary.html) 对象列表，按 `CreatedTimestamp` 以降序排列。仅包括用户可见的最新 20 条消息。如果频道中存在当前用户看不到的定向消息，则返回的消息可能少于 20 条。`ChannelMessagesHasMore` 布尔值将设置为 true 以表示还有更多消息。软限额，可在 AWS 账户层面进行调整。
+ **ChannelMemberships** — [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembershipSummary.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembershipSummary.html) 对象列表。最多包含 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: [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelSummary.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelSummary.html)
ChannelMessages: List of [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessageSummary.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessageSummary.html)
ChannelMemberships: List of [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembershipSummary.html ](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembershipSummary.html )
ReadMarkerTimestamp: Timestamp
ChannelMessagesHasMore: Boolean
})
}
```
## 处理事件
对于在建立连接后才可接收消息的 `AppInstanceUser`，您必须将其添加到频道中。要执行这一操作，请使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html) API。
**注意**
`AppInstanceUser` 始终接收其所属各频道的消息。当 `AppInstance` 用户断开连接时，消息传递将停止。
除非您使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html) API 明确添加消息，否则 `AppInstanceAdmin` 和 `ChannelModerator` 不会在频道上接收消息。
下面的主题说明了如何处理事件。
**Topics**
+ [了解消息结构](#message-structures)
+ [处理断开连接](#handle-disconnects)
### 了解消息结构
您收到的每 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` 值和有效负载：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/chime-sdk/latest/dg/websockets.html)
**x-amz-chime-message-类型**
下表列出了 `x-amz-chime-message-type` 消息类型。
| 消息类型 | 说明 |
| --- | --- |
| `STANDARD` | 在 WebSocket 收到标准频道消息时发送。 |
| `CONTROL` | 在 WebSocket 收到控制频道消息时发送。 |
| `SYSTEM` | Amazon Chime SDK 消息传递发送的所有其他 WebSocket 消息。 |
**x-amz-chime-event-原因**
这是特定用例支持的可选标头。标头提供有关接收特定事件的原因的信息。
| 事件原因 | 说明 |
| --- | --- |
| subchannel\$1DELETED | 弹性频道监管人收到的 `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. 再次调用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html) API 以获取新的基本 URL。
1. 如果 IAM 凭证已过期，请刷新它们。
1. 通过 Connect 连接 WebSocket。
[如果您使用该 amazon-chime-sdk-js库，则在实现 ne [edsRefresh () 属性和 refresh ()](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Credentials.html#needsRefresh-property) 方法时会为您处理此问题。](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Credentials.html#refresh-property)有关工作示例，请参见 [https://github.com/aws-samples/amazon-chime-sdk/blob/dc11c4c76c78d28f618577706bba2087919a5635/apps/chat/src/providers/AuthProvider.jsx \$1L93](https://github.com/aws-samples/amazon-chime-sdk/blob/dc11c4c76c78d28f618577706bba2087919a5635/apps/chat/src/providers/AuthProvider.jsx#L93-L101)-L101。
# 在 Amazon Chime SDK 消息传递中配置附件
Amazon Chime SDK 允许您将消息附件作为消息元数据存储在自己的存储空间。Amazon Simple Storage Service (S3) 是最简单的附件入门方式。
**使用 S3 处理附件**
1. 创建 S3 存储桶以存储附件。
1. 为存储桶创建 IAM 策略，允许 Amazon Chime SDK 用户从您的 S3 存储桶上传、下载和删除附件。
1. 创建 IAM 角色供您的身份提供商使用，向用户售卖凭证以获取附件。
[示例应用程序](https://github.com/aws-samples/amazon-chime-sdk/tree/main/apps/chat)提供了一个示例，说明如何使用 Amazon S3、Amazon Cognito 和 Amazon Chime SDK 执行此操作。
# 了解用于 Amazon Chime SDK 消息传递的系统消息
Amazon Chime SDK 会向所有连接的客户端发送系统消息，告知频道中发生的事件。事件包括：
+ `UPDATE_CHANNEL`：此事件表示对频道详细信息所做的任何更新，例如名称或元数据。
+ `DELETE_CHANNEL`：此事件表示该频道及其所有数据（包括消息、成员资格、监管人和禁令）将被删除。
+ `CREATE_CHANNEL_MEMBERSHIP`：此事件表示已将特定 `AppInstanceUser` 添加为该频道的成员。该事件还包含新 `AppInstanceUser` 的详细信息。
+ `DELETE_CHANNEL_MEMBERSHIP`：此事件表示 `AppInstanceUser` 已从频道中移除。该事件还包含已删除的 `AppInstanceUser` 详细信息。
+ `UPDATE_CHANNEL_MEMBERSHIP`：此事件仅适用于弹性频道。该事件表示成员资格平衡已将 `AppInstanceUser` 从一个子频道转移到另一个子频道。该事件还包含 `AppInstanceUser` 详细信息，以及有关 `AppInstanceUser` 转移到的子频道的信息。
# 用于 Amazon Chime SDK 消息传递的 IAM 角色示例
要让用户访问 Amazon Chime SDK 消息传递功能，您必须定义一个 IAM 角色和策略，以便在用户登录时向他们提供凭证。IAM 策略定义了用户可以访问的资源。
本节中的示例提供了您可以根据需要进行调整的基本策略。有关策略工作原理的更多信息，请参阅 [如何从后端服务发出 SDK 调用以便进行 Amazon Chime SDK 消息传递](call-from-backend.md)。
此示例介绍了针对使用 Amazon Chime SDK 消息构建应用程序的开发人员的策略。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"chime:CreateAppInstance",
"chime:DescribeAppInstance",
"chime:ListAppInstances",
"chime:UpdateAppInstance",
"chime:DeleteAppInstance",
"chime:CreateAppInstanceUser",
"chime:DeleteAppInstanceUser",
"chime:ListAppInstanceUsers",
"chime:UpdateAppInstanceUser",
"chime:DescribeAppInstanceUser",
"chime:CreateAppInstanceAdmin",
"chime:DescribeAppInstanceAdmin",
"chime:ListAppInstanceAdmins",
"chime:DeleteAppInstanceAdmin",
"chime:PutAppInstanceRetentionSettings",
"chime:GetAppInstanceRetentionSettings",
"chime:PutAppInstanceStreamingConfigurations",
"chime:GetAppInstanceStreamingConfigurations",
"chime:DeleteAppInstanceStreamingConfigurations",
"chime:TagResource",
"chime:UntagResource",
"chime:ListTagsForResource",
"chime:CreateChannelFlow",
"chime:UpdateChannelFlow",
"chime:DescribeChannelFlow",
"chime:DeleteChannelFlow",
"chime:ListChannelFlows",
"chime:ListChannelsAssociatedWithChannelFlow",
"chime:ChannelFlowCallback"
],
"Effect": "Allow",
"Resource": "*"
}
]
}
```
------
此示例介绍了一项允许用户访问 Amazon Chime SDK 用户操作的策略。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": "chime:GetMessagingSessionEndpoint",
"Effect": "Allow",
"Resource": "*"
},
{
"Action": [
"chime:CreateChannel",
"chime:DescribeChannel",
"chime:DeleteChannel",
"chime:UpdateChannel",
"chime:ListChannels",
"chime:Listsubchannels",
"chime:ListChannelMembershipsForAppInstanceUser",
"chime:DescribeChannelMembershipForAppInstanceUser",
"chime:ListChannelsModeratedByAppInstanceUser",
"chime:DescribeChannelModeratedByAppInstanceUser",
"chime:UpdateChannelReadMarker",
"chime:CreateChannelModerator",
"chime:DescribeChannelModerator",
"chime:ListChannelModerators",
"chime:DeleteChannelModerator",
"chime:SendChannelMessage",
"chime:GetChannelMessage",
"chime:DeleteChannelMessage",
"chime:UpdateChannelMessage",
"chime:RedactChannelMessage",
"chime:ListChannelMessages",
"chime:CreateChannelMembership",
"chime:DescribeChannelMembership",
"chime:DeleteChannelMembership",
"chime:ListChannelMemberships",
"chime:CreateChannelBan",
"chime:DeleteChannelBan",
"chime:ListChannelBans",
"chime:DescribeChannelBan",
"chime:Connect",
"chime:AssociateChannelFlow",
"chime:DisassociateChannelFlow",
"chime:GetChannelMessageStatus"
],
"Effect": "Allow",
"Resource": [
"arn:aws:chime:us-east-1:123456789012:app-instance/app_instance_id/user/app_instance_user_id",
"arn:aws:chime:us-east-1:123456789012:app-instance/app_instance_id/channel/*"
]
}
]
}
```
------
此示例介绍了一项策略，该策略允许用户尽量减少对 Amazon Chime SDK 用户操作的访问权限。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": "chime:GetMessagingSessionEndpoint",
"Effect": "Allow",
"Resource": "*"
},
{
"Action": [
"chime:ListChannels",
"chime:DescribeChannel",
"chime:ListChannelMembershipsForAppInstanceUser",
"chime:DescribeChannelMembershipForAppInstanceUser",
"chime:ListChannelsModeratedByAppInstanceUser",
"chime:DescribeChannelModeratedByAppInstanceUser",
"chime:SendChannelMessage",
"chime:GetChannelMessage",
"chime:ListChannelMessages",
"chime:Connect"
],
"Effect": "Allow",
"Resource": [
"arn:aws:chime:us-east-1:123456789012:app-instance/app_instance_id/user/app_instance_user_id",
"arn:aws:chime:us-east-1:123456789012:app-instance/app_instance_id/channel/*"
]
}
]
}
```
------
此示例显示了为建立 WebSocket 连接的策略`AppInstanceUser`。有关 WebSocket 连接的更多信息，请参阅[WebSockets 用于在 Amazon Chime 软件开发工具包消息中接收消息](websockets.md)。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"chime:Connect"
],
"Resource": [
"arn:aws:chime:us-east-1:123456789012:app-instance/app_instance_id/user/app_instance_user_id"
]
}
]
}
```
------
# 了解按角色划分的授权
本主题中的表格列出了应用程序实例用户可以运行的操作，具体取决于他们的角色。
**图例**
+ **已允许**：如果在 IAM policy 中指定了正确的操作/资源上下文，则可以成功运行该上下文。
+ **已允许，但有限制**：如果在 IAM policy 中指定了正确的操作/资源上下文，则必须满足某些条件才能成功运行操作。
+ **已拒绝**：即使在 IAM policy 中指定了正确的操作/资源上下文，它仍会被后端阻止。
**Topics**
+ [AppInstanceAdmin](#appinstanceadmin)
+ [ChannelModerator](#channelmoderator)
+ [成员](#member)
+ [非成员](#non-member)
## AppInstanceAdmin
应用程序实例管理员可以对他们作为管理员的应用程序实例中的频道执行操作。
| API 名称 | 已允许或已拒绝 | 备注 |
| --- | --- | --- |
| `UpdateChannel` | 已允许，但有限制 | 设置 ElasticChannelConfiguration 后无法更新 |
| `DeleteChannel` | 已允许 | |
| `DescribeChannel` | 已允许 | |
| `ListChannel` | 已允许 | |
| `ListChannelMembershipsForAppInstanceUser` | 允许 | 您也可以填充 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_DescribeChannelModeratedByAppInstanceUser.html#API_DescribeChannelModeratedByAppInstanceUser_RequestSyntax](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_DescribeChannelModeratedByAppInstanceUser.html#API_DescribeChannelModeratedByAppInstanceUser_RequestSyntax)和另一个`AppInstanceUser`。 |
| `DescribeChannelMembershipForAppInstanceUser` | 允许 | 你也可以填充 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_DescribeChannelModeratedByAppInstanceUser.html#API_DescribeChannelModeratedByAppInstanceUser_RequestSyntax](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_DescribeChannelModeratedByAppInstanceUser.html#API_DescribeChannelModeratedByAppInstanceUser_RequestSyntax)和另一个`AppInstanceUser`。 |
| `ListChannelsModeratedByAppInstanceUser` | 允许 | 你也可以填充 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_DescribeChannelModeratedByAppInstanceUser.html#API_DescribeChannelModeratedByAppInstanceUser_RequestSyntax](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_DescribeChannelModeratedByAppInstanceUser.html#API_DescribeChannelModeratedByAppInstanceUser_RequestSyntax)和另一个 AppInstanceUser。 |
| `DescribeChannelModeratedByAppInstanceUser` | 允许 | 你也可以填充 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_DescribeChannelModeratedByAppInstanceUser.html#API_DescribeChannelModeratedByAppInstanceUser_RequestSyntax](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_DescribeChannelModeratedByAppInstanceUser.html#API_DescribeChannelModeratedByAppInstanceUser_RequestSyntax)再加`ppInstanceUser`一个 A。不允许使用弹性通道。 |
| `CreateChannelMembership` | 已允许 | |
| `DescribeChannelMembership` | 已允许 | |
| `ListChannelMembership` | 已允许 | |
| `DeleteChannelMembership` | 允许 | |
| `SendChannelMessage` | 已允许，但有限制 | 你首先需要使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateChannelMembership.html)为自己创建成员资格，然后调用 API。 |
| `GetChannelMessage` | 已允许 | |
| `ListChannelMessage` | 已允许 | |
| `DeleteChannelMessage` | 已允许 | |
| `RedactChannelMessage` | 允许 | |
| `UpdateChannelMessage` | 已允许，但有限制 | 您只能编辑自己的消息。 |
| `CreateChannelModerator` | 已允许 | |
| `DeleteChannelModerator` | 已允许 | |
| `DescribeChannelModerator` | 已允许 | |
| `ListChannelModerator` | 允许 | |
| `CreateChannelBan` | 已允许，但有限制 | 您封禁的 `AppInstanceUser` 不能是该频道的 `AppInstanceAdmin` 或监管人。 |
| `DeleteChannelBan` | 已允许，但有限制 | |
| `DescribeChannelBan` | 已允许 | |
| `ListChannelBan` | 允许 | |
| `UpdateChannelReadMarker` | 已允许，但有限制 | 对于非弹性通道，你需要使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html)API，用于先为自己创建成员资格，然后调用 API。 不允许用于弹性频道。 |
| `GetChannelMessage` | 已允许，但有限制 | 仅允许已发送的消息。除非您是消息发送者，否则不允许按频道流处理消息。 |
| `ListChannelMessages` | 允许 | |
| `DeleteChannelMessage` | 已允许，但有限制 | 仅允许已发送的消息。 |
| `RedactChannelMessage` | 已允许，但有限制 | 仅允许已发送的消息。 |
| `UpdateChannelMessage` | 已允许，但有限制 | 您只能编辑自己发送的消息。 |
| `AssociateChannelFlow` | 已允许 | |
| `DisassociateChannelFlow` | 允许 | |
| `GetChannelMessageStatus` | 已允许，但有限制 | 您只能获取自己的消息状态。 |
| `ListSubChannels` | 允许 | |
## ChannelModerator
频道监管人只能在他们拥有监管人角色的频道上执行操作。
**注意**
作为 `AppInstanceAdmin` 的监管人可以在该角色允许的频道上执行操作。
| API 名称 | 已允许或已拒绝 | 备注 |
| --- | --- | --- |
| `UpdateChannel` | 允许 | 设置 ElasticChannelConfiguration 后无法更新 |
| `DeleteChannel` | 允许 | |
| `DescribeChannel` | 已允许，但有限制 | 您只能获取公共频道的详细信息。 |
| `ListChannel` | 已允许，但有限制 | 您只能获取公共频道的详细信息。 |
| `ListChannelMembershipsForAppInstanceUser` | 已允许，但有限制 | 您只能使用您的 ARN 作为 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax) 值。 |
| `DescribeChannelMembershipForAppInstanceUser` | 已允许，但有限制 | 您只能使用您的 ARN 作为 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax) 值。 |
| `ListChannelsModeratedByAppInstanceUser` | 已允许，但有限制 | 您只能使用您的 ARN 作为 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax) 值。 |
| `DescribeChannelModeratedByAppInstanceUser` | 已允许，但有限制 | 您也可以填充 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax)和另一个 AppInstanceUser。 |
| `CreateChannelMembership` | 已允许 | |
| `DescribeChannelMembership` | 已允许 | |
| `ListChannelMembership` | 已允许 | |
| `DeleteChannelMembership` | 允许 | |
| `SendChannelMessage` | 已允许，但有限制 | 你需要使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html)API，用于先为自己创建成员资格，然后调用 `SendChannelMessage` API。 |
| `GetChannelMessage` | 已允许 | |
| `ListChannelMessage` | 允许 | |
| `DeleteChannelMessage` | 已拒绝 | |
| `RedactChannelMessage` | 允许 | |
| `UpdateChannelMessage` | 已允许，但有限制 | 您只能更新自己的消息。 |
| `CreateChannelModerator` | 允许 | 你需要使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html)API，用于先为自己创建成员资格，然后调用 `CreateChannelModerator` API。 |
| `DeleteChannelModerator` | 已允许 | |
| `DescribeChannelModerator` | 已允许 | |
| `ListChannelModerator` | 允许 | |
| `CreateChannelBan` | 已允许，但有限制 | 您封禁的 `AppInstanceUser` 不能是该频道的 `AppInstanceAdmin` 或监管人。 |
| `DeleteChannelBan` | 已允许，但有限制 | |
| `DescribeChannelBan` | 已允许 | |
| `ListChannelBan` | 允许 | |
| `UpdateChannelReadMarker` | 已允许，但有限制 | 对于非弹性通道，你需要使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html)先为自己创建成员资格，然后调用 `UpdateChannelReadMarker` API。 不允许用于弹性频道。 |
| `GetChannelMessage` | 已允许，但有限制 | 仅允许已发送的消息。除非您是消息发送者，否则不允许按频道流处理消息。 |
| `ListChannelMessages` | 允许 | |
| `DeleteChannelMessage` | 已拒绝 | |
| `RedactChannelMessage` | 已允许，但有限制 | 仅允许已发送的消息。 |
| `UpdateChannelMessage` | 已允许，但有限制 | 您只能编辑自己发送的消息。 |
| `AssociateChannelFlow` | 已允许 | |
| `DisassociateChannelFlow` | 允许 | |
| `GetChannelMessageStatus` | 已允许，但有限制 | 您只能获取自己的消息状态。 |
| `ListSubChannels` | 允许 | |
## 成员
如果通过以下方式将他们添加到频道，则他们将`AppInstanceUser`成为该频道的成员 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html)API。
成员只能在他们所属的频道上执行操作。
**注意**
作为 `AppInstanceAdmin` 或 `ChannelModerator` 的成员可以在这两个角色允许的频道上执行操作。
| API 名称 | 已允许或已拒绝 | 备注 |
| --- | --- | --- |
| `UpdateChannel` | 已拒绝 | |
| `DeleteChannel` | 已拒绝 | |
| `DescribeChannel` | 已允许，但有限制 | 您只能获取公共频道的详细信息。 |
| `ListChannel` | 已允许，但有限制 | 您只能获取公共频道的详细信息。 |
| `ListChannelMembershipsForAppInstanceUser` | 已允许，但有限制 | 您只能使用您的 ARN 作为 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax) 值。 |
| `DescribeChannelMembershipForAppInstanceUser` | 已允许，但有限制 | 您只能使用您的 ARN 作为 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax) 值。 |
| `ListChannelsModeratedByAppInstanceUser` | 已允许，但有限制 | 您只能使用您的 ARN 作为 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax) 值。 |
| `DescribeChannelModeratedByAppInstanceUser` | 已允许，但有限制 | 您也可以填充 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_DescribeChannelModeratedByAppInstanceUser.html#API_DescribeChannelModeratedByAppInstanceUser_RequestSyntax](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_DescribeChannelModeratedByAppInstanceUser.html#API_DescribeChannelModeratedByAppInstanceUser_RequestSyntax)和另一个 AppInstanceUser。 不允许用于弹性频道。 |
| `CreateChannelMembership` | 已允许，但有限制 | 您只能为... 添加其他成员 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannel.html#chime-CreateChannel-request-Mode](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannel.html#chime-CreateChannel-request-Mode)频道。 |
| `DescribeChannelMembership` | 已允许 | |
| `ListChannelMembership` | 已允许 | |
| `DeleteChannelMembership` | 已允许 | |
| `SendChannelMessage` | 已允许 | |
| `GetChannelMessage` | 已允许 | |
| `ListChannelMessage` | 允许 | |
| `DeleteChannelMessage` | 已拒绝 | |
| `RedactChannelMessage` | 已允许，但有限制 | 您只能编辑自己的消息。 |
| `UpdateChannelMessage` | 已允许，但有限制 | 您只能更新自己的消息。 |
| `CreateChannelModerator` | 已拒绝 | |
| `DeleteChannelModerator` | 已拒绝 | |
| `DescribeChannelModerator` | 已拒绝 | |
| `ListChannelModerator` | 已拒绝 | |
| `CreateChannelBan` | 已拒绝 | |
| `DeleteChannelBan` | 已拒绝 | |
| `DescribeChannelBan` | 已拒绝 | |
| `ListChannelBan` | 已拒绝 | |
| `UpdateChannelReadMarker` | 已允许，但有限制 | 不允许用于弹性频道。 |
| `GetChannelMessage` | 已允许，但有限制 | 仅允许已发送的消息。除非您是消息发送者，否则不允许按频道流处理消息。 |
| `ListChannelMessages` | 允许 | |
| `DeleteChannelMessage` | 已允许，但有限制 | 仅允许已发送的消息。 |
| `RedactChannelMessage` | 已允许，但有限制 | 仅允许已发送的消息。 |
| `UpdateChannelMessage` | 已允许，但有限制 | 您只能编辑自己发送的消息。 |
| `AssociateChannelFlow` | 已拒绝 | |
| `DisassociateChannelFlow` | 已拒绝 | |
| `GetChannelMessageStatus` | 已允许，但有限制 | 您只能获取自己的消息状态。 |
| `Listsubchannels` | 已拒绝 | |
## 非成员
非会员是常客`AppInstanceUser`，除非您使用，否则他们无法执行任何与频道相关的操作 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html)用于添加它们的 API。
**注意**
作为 `AppInstanceAdmin` 或 `ChannelModerator` 的非成员可以执行这两个角色允许的频道相关操作。
| API 名称 | 已允许或已拒绝 | 备注 |
| --- | --- | --- |
| `UpdateChannel` | 已拒绝 | |
| `DeleteChannel` | 已拒绝 | |
| `DescribeChannel` | 已允许，但有限制 | 您只能获取公共频道的详细信息。 |
| `ListChannel` | 已允许，但有限制 | 您只能获取公共频道的详细信息。 |
| `ListChannelMembershipsForAppInstanceUser` | 已允许，但有限制 | 您只能使用您的 ARN 作为 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax) 值。 |
| `DescribeChannelMembershipForAppInstanceUser` | 已允许，但有限制 | 您也可以填充 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_DescribeChannelModeratedByAppInstanceUser.html#API_DescribeChannelModeratedByAppInstanceUser_RequestSyntax](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_DescribeChannelModeratedByAppInstanceUser.html#API_DescribeChannelModeratedByAppInstanceUser_RequestSyntax)和另一个`AppInstanceUser`。 不允许用于弹性频道。 |
| `ListChannelsModeratedByAppInstanceUser` | 已允许，但有限制 | 您只能使用您的 ARN 作为 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax) 值。 |
| `DescribeChannelModeratedByAppInstanceUser` | 已允许，但有限制 | 您只能使用您的 ARN 作为 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax) 值。 |
| `CreateChannelMembership` | 已拒绝 | |
| `DescribeChannelMembership` | 已允许，但有限制 | 您只能获取公共频道的详细信息。 |
| `ListChannelMembership` | 已允许，但有限制 | 您只能获取公共频道的详细信息。 |
| `DeleteChannelMembership` | 已拒绝 | |
| `SendChannelMessage` | 已拒绝 | |
| `GetChannelMessage` | 已允许，但有限制 | 您只能获取公共频道的详细信息。 |
| `ListChannelMessage` | 已允许，但有限制 | 您只能获取公共频道的详细信息。 |
| `DeleteChannelMessage` | 已拒绝 | |
| `RedactChannelMessage` | 已拒绝 | |
| `UpdateChannelMessage` | 已拒绝 | |
| `CreateChannelModerator` | 已拒绝 | |
| `DeleteChannelModerator` | 已拒绝 | |
| `DescribeChannelModerator` | 已拒绝 | |
| `ListChannelModerator` | 已拒绝 | |
| `CreateChannelBan` | 已拒绝 | |
| `DeleteChannelBan` | 已拒绝 | |
| `DescribeChannelBan` | 已拒绝 | |
| `ListChannelBan` | 已拒绝 | |
| `UpdateChannelReadMarker` | 已拒绝 | |
| `GetChannelMessage` | 已允许，但有限制 | 仅允许已发送的消息。除非您是消息发送者，否则不允许按频道流处理消息。 |
| `ListChannelMessages` | 已允许，但有限制 | |
| `DeleteChannelMessage` | 已拒绝 | 已拒绝 |
| `RedactChannelMessage` | 已拒绝 | |
| `UpdateChannelMessage` | 已拒绝 | |
| `AssociateChannelFlow` | 已拒绝 | |
| `DisassociateChannelFlow` | 已拒绝 | |
| `GetChannelMessageStatus` | 已允许，但有限制 | 您只能获取自己的消息状态。 |
# 在 Amazon Chime SDK 消息传递中流式传递消息数据
您可以配置 `AppInstance`，从而以流的形式接收消息和频道事件等数据。然后，您可以对这些数据做出实时反应。目前，Amazon Chime SDK 消息传递仅接受 Kinesis 流作为流目的地。要使用具有此功能的 Kinesis 流，您必须具备以下先决条件：
+ Kinesis 直播必须与使用相同的 AWS 账户。`AppInstance`
+ 流必须与 `AppInstance` 在同一个区域。
+ 流名称的前缀以 `chime-messaging-` 开头。
+ 您必须配置至少两个分片。每个分片每秒最多可接收 1MB 的数据，因此请相应地扩展您的数据流。
+ 必须启用服务器端加密 (SSE)
**配置 Kinesis 流**
1. 使用上一节中的先决条件创建一个或多个 Kinesis 流，然后获取 ARN。除了 Amazon Chime 权限外，还要确保呼叫者拥有 Kinesis 权限。
以下示例说明如何使用 AWS CLI 创建包含两个分片的 Kinesis 流，以及如何启用 SSE。
`aws kinesis create-stream --stream-name chime-messaging-unique-name --shard-count 2`
`aws kinesis start-stream-encryption --stream-name chime-messaging-unique-name --encryption-type KMS --key-id "alias/aws/kinesis"`
1. 通过调用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_PutMessagingStreamingConfigurations.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_PutMessagingStreamingConfigurations.html) API 来配置流式传输。
您可以配置两种数据类型中的一种或两种，也可以为它们选择相同的流或单独的流。
以下示例说明如何使用 AWS CLI 配置`appinstance`为流式传输`ChannelMessage`和`Channel`数据类型。
```
aws chime-sdk-messaging put-messaging-streaming-configurations --app-instance-arn app_instance_arn \
--streaming-configurations DataType=ChannelMessage,ResourceArn=kinesis_data_stream_arn
```
```
aws chime-sdk-messaging put-messaging-streaming-configurations --app-instance-arn app_instance_arn \
--streaming-configurations DataType=Channel,ResourceArn=kinesis_data_stream_arn
```
数据类型的作用域如下：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/chime-sdk/latest/dg/streaming-export.html)
1. 开始从您配置的 Kinesis 流中读取数据。
**注意**
在配置流之前发送的任何事件都不会发送到您的 Kinesis 流中。
**数据格式**
Kinesis 以 JSON 格式输出包含以下字段的记录：`EventType` 和 `Payload`。有效负载格式取决于 `EventType`。下表列出了事件类型及其对应的负载格式。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/chime-sdk/latest/dg/streaming-export.html)
# 在 Amazon Chime SDK 消息传递中使用弹性频道举办实时事件
弹性频道支持拥有多达 100 万成员的大规模聊天体验。典型用途包括观看体育赛事的各方或政治事件。您只能在美国东部（弗吉尼亚州北部）区域中使用弹性频道。
弹性频道由具有通用配置的单个频道以及不同数量（或*弹性数量*）的子频道组成。该配置还包括子频道中成员的最小和最大阈值。
例如，假设您创建了一个包含 100 个子频道的弹性频道，为子频道设置了 500 个成员的低门槛和 10,000 个成员的高门槛。当用户加入此示例频道时，系统会自动将他们分配到单个子频道，直到成员人数超过 10,000。此时，系统会创建一个新的子频道，并在其中添加所有新成员。当用户离开时，系统会删除子频道，并将成员分配到其余的子频道。
将受众分成子频道可以让参与者更容易关注对话。监管人的工作量也减少了，因为他们只需要观看一些子频道。此外，监管人可以使用弹性频道提供的内置工具。例如，监管人可以[禁止用户](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelBan.html)进入频道，[创建监管人](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelModerator.html)，并使用[频道流](https://docs.aws.amazon.com/chime-sdk/latest/dg/using-channel-flows.html)自动审核频道中的所有消息。
有关 Amazon Chime SDK 消息传递限额的更多信息，请参阅*《Amazon Chime SDK 一般参考》*中的[消息传递限额](https://docs.aws.amazon.com/general/latest/gr/chime-sdk.html)。
**Topics**
+ [先决条件](#elastic-prereqs)
+ [弹性频道概念](#elastic-concepts)
+ [其他支持的功能](#additional-features)
+ [为 Amazon Chime SDK 消息传递创建弹性频道](create-elastic-channel.md)
+ [为 Amazon Chime SDK 消息传递管理弹性频道成员](manage-elastic-members.md)
+ [在 Amazon Chime SDK 消息传递中发送弹性频道消息](send-messages-elastic.md)
+ [了解 Amazon Chime SDK 会议的弹性通道中的 WebSocket 系统消息](websocket-messages-elastic.md)
+ [使用 Kinesis 流接收 Amazon Chime SDK 会议的系统消息](elastic-onboard-streams.md)
+ [在我们的演示应用程序中测试 Amazon Chime SDK 会议的弹性频道](elastic-testing.md)
## 先决条件
您必须具备以下各项条件，才能使用弹性频道。
+ 了解 Amazon Chime SDK 消息传递功能，例如管理频道以及发送和接收消息。
+ 能够调用 Amazon Chime 软件开发工具包消息。 APIs
## 弹性频道概念
要有效地使用弹性频道，您必须了解这些概念。
**子频道**
弹性频道将其成员划分为称为子频道的逻辑容器。当您向弹性频道添加 `AppInstanceUser` 时，用户就会成为子频道的成员。该用户可以发送和接收消息，但只能与该子频道的其他成员发送和接收消息。系统不允许来自一个子频道的消息出现在其他子频道中。
**扩展**
为了支持用户互动，每个子频道都必须满足最低成员资格要求。您在创建弹性频道时提供该值。当用户加入或离开事件时，系统会将成员转移到不同的子频道，这使得整个频道具有“弹性”。子频道运行以下扩缩操作。
+ **SCALE\$1OUT**：当新的弹性频道成员资格申请到来并且所有子频道都已满时，系统会通过创建一个新的子频道，然后将成员资格从现有子频道转移到新的子频道来进行扩展。
+ **SCALE\$1IN**：当子频道的成员人数低于最低要求，而另一个子频道有能力容纳第一个子频道的所有成员时，`SCALE_IN` 事件会转移这些成员资格，然后删除该子频道和所有消息。
如果您需要访问已删除的频道消息，则必须先打开消息流。有关更多信息，请参阅[在 Amazon Chime SDK 消息传递中流式传递消息数据](streaming-export.md)。
**成员传输**
当成员资格平衡将 `AppInstanceUser` 从一个子频道转移到另一个子频道时，就会发生这种情况。传输后 `AppInstanceUser` 仍属于弹性频道。但是，新的子频道包含不同的成员资格和消息，因此转移后由 `AppInstanceUser` 发送的消息会送达上述不同成员。成员资格平衡不会影响监管人成员资格。
**注意**
弹性频道不支持隐藏的成员资格、成员偏好和阅读消息的时间戳。
## 其他支持的功能
弹性频道还支持这些消息传递功能。
+ [预提取](websockets.md#prefetch)
+ [频道流](using-channel-flows.md)
# 为 Amazon Chime SDK 消息传递创建弹性频道
您可以使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannel.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannel.html) API 中的 `ElasticChannelConfiguration` 字段来创建弹性频道。创建弹性频道后，即可创建频道成员资格。
**注意**
对于非弹性频道，创建频道的 `AppInstanceUser` 将作为成员和监管人自动添加到该频道。对于弹性频道，频道创建者仅作为监管人添加。
`ElasticChannelConfiguration` 设置后不可更新。
您不能将频道从弹性频道更新为非弹性频道，反之亦然。
您不能在 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannel.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannel.html)API 请求 ARNs 中包含成员列表。但是，您可以包括主持人列表 ARNs。
您不能创建 `UNRESTRICTED` 类弹性频道。
# 为 Amazon Chime SDK 消息传递管理弹性频道成员
要管理弹性通道中的成员，请使用[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html)、和[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelBan.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelBan.html) APIs。以下信息介绍了其使用方法。
**频道成员资格数**
`CreateChannelMembership` API 创建子频道级别的成员资格。子频道包括监管人和普通成员。
+ **监管人**：您可以将监管人添加到多个子频道。这允许监管人在他们所属的每个子频道上发送消息。向子频道添加监管人时，您必须提供 `SubChannelId`。
如果您想自动为新的子频道分配监管人，则可以[启用消息流](streaming-export.md)，监听子频道创建事件，然后创建监管人成员资格以响应上述事件。
最后，您可以从特定子频道或所有子频道中删除监管人。这两种操作都需要使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_DeleteChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_DeleteChannelMembership.html) API。要从特定子频道中删除监管人，您需要提供 `SubChannelId`。如果您未提供子频道的 ID，系统会将监管人从所有子频道中移除。最后，您可以使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ListSubChannels](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ListSubChannels) API 来列出子频道以及每个子频道中的成员数量。
+ **普通成员**：占频道成员的大多数。您只能向一个子频道添加普通成员。此外，在创建或删除频道成员资格时，您无法通过 `SubChannelId`，因为是由系统来控制创建成员资格所在的子频道。
**频道的监管人数**
`CreateChannelModerator` API 在弹性频道级别创建监管人。监管人可以查看所有子频道中的所有消息。当您将普通成员提升为频道监管人时，系统会删除该成员的所有现有频道成员资格。当您降级监管人时，也会发生同样的情况。
**频道禁令**
`CreateChannelBan` API 在弹性频道级别创建封禁。被封禁的 `AppInstanceUser` 不属于任何子频道。当您封禁某个成员时，系统会删除该成员的所有频道成员资格。
# 在 Amazon Chime SDK 消息传递中发送弹性频道消息
[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_SendChannelMessage.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_SendChannelMessage.html) API 在子频道级别创建消息。要发送消息，您必须要有一个 `subChannelId`。您也可以使用[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_UpdateChannelMessage.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_UpdateChannelMessage.html)、和[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_RedactChannelMessage.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_RedactChannelMessage.html) APIs 来编辑和删除消息，但在所有情况下，都必须有`subChannelId`。
**注意**
只有当消息发件人属于他们向其发送消息的子频道时，他们才能编辑或编写消息。如果成员资格平衡将成员转移到另一个子频道，则该成员只能编辑或编辑他们在新的子频道中发送的消息。
# 了解 Amazon Chime SDK 会议的弹性通道中的 WebSocket 系统消息
Amazon Chime SDK 会向所有连接的客户端发送系统消息，告知频道中发生的事件。下面的列表描述了弹性频道的系统消息。
**消息事件**
弹性频道的事件有效负载包含该 `subChannelId` 字段。非弹性频道的负载保持不变。
**成员事件**
现在，`CREATE_CHANNEL_MEMBERSHIP` 和 `DELETE_CHANNEL_MEMBERSHIP` 事件的有效负载中包含了 `subChannelId` 字段。
弹性频道不支持该 `BATCH_CREATE_CHANNEL_MEMBERHSIP` 事件。当您调用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_BatchCreateChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_BatchCreateChannelMembership.html) API 时，系统会发送单个 `CREATE_CHANNEL_MEMBERSHIP` 事件。
现在，您可以使用 `UPDATE_CHANNEL_MEMBERSHIP` 事件类型来表示成员资格信息的变化。例如，在成员从一个子频道转移到另一个子频道期间，系统会发送一个有效负载中包含新 `SubChannelId` 的 `UPDATE_CHANNEL_MEMBERSHIP` 事件，以表明该成员已被转移。
系统仅将 `UPDATE_CHANNEL_MEMBERSHIP` 事件发送给被转移的成员，而不会发送给子频道的其他成员。因此，我们鼓励您使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ListChannelMemberships.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ListChannelMemberships.html)API，而不是填充频道会员名单。 WebSockets 有关更多信息，请参阅[WebSockets 用于在 Amazon Chime 软件开发工具包消息中接收消息](websockets.md)。
# 使用 Kinesis 流接收 Amazon Chime SDK 会议的系统消息
您可以配置 `AppInstance`，从而以流的形式接收数据。例如，流可以包含消息、子频道事件和频道事件。
作为其中的一部分，我们支持 `CREATE_SUB_CHANNEL` 和 `DELETE_SUB_CHANNEL` 事件。它们表示作为成员资格平衡的一部分何时创建或删除子频道。有关接收数据流的更多信息，请参阅 [在 Amazon Chime SDK 消息传递中流式传递消息数据](streaming-export.md)。
# 在我们的演示应用程序中测试 Amazon Chime SDK 会议的弹性频道
[你可以在/上测试所有 Amazon Chime SDK 消息传递功能 GitHub 。https://github.com/aws-samples/ amazon-chime-sdk tree/main/apps/chat](https://github.com/aws-samples/amazon-chime-sdk/tree/main/apps/chat)
# 在 Amazon Chime SDK 消息传递中使用移动推送通知接收消息
您可以将 Amazon Chime SDK 消息传递配置为向移动推送通知频道发送频道消息。Amazon Chime SDK 需要为推送通知配置 Amazon Pinpoint 应用程序。您的 Amazon Pinpoint 应用程序必须满足以下先决条件：
+ 您的 Amazon Pinpoint 应用程序必须至少配置并启用 FCM 或 APNS 频道。
+ 您的 Amazon Pinpoint 应用程序必须与您的 Amazon Chime 软件开发工具包应用程序实例位于相同的 AWS 账户和区域。
**注意**
默认情况下，推送通知通道的所有成员都会收到推送通知，包括消息发送者。但是，您可以设置过滤规则，防止消息被发送给发送者。有关更多信息，请参阅此部分后面的[在 Amazon Chime SDK 消息传递中使用筛选规则来筛选消息](filter-msgs.md)。
**Topics**
+ [为 Amazon Chime SDK 消息传递创建 Amazon Pinpoint 应用程序](create-pinpoint.md)
+ [为 Amazon Chime SDK 消息传递创建服务角色](create-service-role.md)
+ [为 Amazon Chime SDK 消息传递将移动设备端点注册为应用程序实例用户](register-endpoint.md)
+ [在 Amazon Chime SDK 消息传递中在启用通知的情况下发送频道消息](send-channel-msg-with-notifications.md)
+ [在 Amazon Chime SDK 消息传递中接收推送通知](receive-notifications.md)
+ [为 Amazon Chime SDK 消息传递调试推送通知失败](debug-notifications.md)
+ [在 Amazon Chime SDK 消息传递中使用筛选规则来筛选消息](filter-msgs.md)
# 为 Amazon Chime SDK 消息传递创建 Amazon Pinpoint 应用程序
要发送推送通知，Amazon Chime SDK 需要 Amazon Pinpoint 应用程序配置为向您的移动应用程序发送推送。以下步骤说明了如何使用 AWS 控制台创建 Pinpoint 应用程序。
**创建 Amazon Pinpoint 应用程序**
1. 登录 AWS 管理控制台并打开位于的 Amazon Pinpoint 控制台。[https://console.aws.amazon.com/pinpoint/](https://console.aws.amazon.com/pinpoint/)
如果您是第一次使用 Amazon Pinpoint，您会看到一个介绍服务功能的页面。
1. 在**开始使用**部分，为您的项目输入一个名称，然后选择**创建项目**。
1. 在**配置功能**页面的**推送通知**旁边，选择**配置**。
1. 在**设置推送通知**页面上，切换 **Apple 推送通知服务 (APNs)**、F **irebase 云端消息 (FCM)** 或两者，然后填写必填字段。
**重要**
Amazon Chime 软件开发工具包目前仅支持向 APNs 和 FCM 发送推送通知。
1. 完成后，选择**保存**。
1. 返回亚马逊 Pinpoint 控制台，网址为[https://console.aws.amazon.com/pinpoint/](https://console.aws.amazon.com/pinpoint/)并记下**项目 ID 值。**您可以将其用作 Amazon Pinpoint 应用程序的 ARN。
# 为 Amazon Chime SDK 消息传递创建服务角色
AWS 使用服务角色向 AWS 服务授予权限，使其可以访问 AWS 资源。附加到服务角色的策略将确定服务可访问的资源以及可使用这些资源执行的操作。您为 Amazon Chime SDK 创建的服务角色允许该服务对您的 Amazon Pinpoint 应用程序进行 `SendMessages` 调用。
**创建服务角色**
1. 登录 AWS 管理控制台并打开 IAM 控制台，网址为[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)。
1. 在导航窗格中选择 **Policies**，然后选择 **Create Policy**。
1. 选择 **JSON** 选项卡，然后将以下策略复制到文本框中。请务必`project_id`使用在上一步中创建的 Amazon Pinpoint 应用程序的编号和您的 AWS 账户编号替换。`aws_account_id`
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": {
"Action": "mobiletargeting:SendMessages",
"Resource": "arn:aws:mobiletargeting:us-east-1:123456789012:apps/project_id/messages",
"Effect": "Allow"
}
}
```
------
1. 选择**下一步：标签**。
1. 选择**下一步: 审核**，在**名称**字段中输入 **AmazonChimePushNotificationPolicy**，然后选择**创建策略**。
1. 在导航窗格中，选择**角色**，然后选择**创建角色**。
1. 在**创建角色**页面上，选择**AWS 服务**，打开 **Choose a user case** 列表并选择 **EC2**。
1. 选择 **Next: Permissions**，然后在搜索框中输入 **AmazonChimePushNotificationPolicy** 并选中策略旁边的复选框。
1. 选择**下一步：标签**。
1. 选择**下一步: 审核**，然后在**名称**字段中输入 **ServiceRoleForAmazonChimePushNotification**。
**重要**
您必须使用上面列出的名称。Amazon Chime SDK 只接受该特定名称。
1. 选择**创建角色**，然后在**角色**页面上的搜索框中输入 **ServiceRoleForAmazonChimePushNotification**，然后选择匹配的角色。
1. 选择**信任关系**选项卡，选择**编辑信任关系**，然后将现有策略替换为以下策略。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "messaging.chime.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
1. 选择**更新信任策略**。
**重要**
通过更改名称、权限策略或信任策略来修改角色可能会破坏推送通知功能。
# 为 Amazon Chime SDK 消息传递将移动设备端点注册为应用程序实例用户
要接收推送通知，应用程序实例用户必须首先使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_identity-chime_RegisterAppInstanceUserEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_identity-chime_RegisterAppInstanceUserEndpoint.html) API 注册一台移动设备。他们必须通过能够访问设备操作系统的设备令牌的移动应用程序进行注册。
为确保应用程序实例用户有权访问 ARN 中列出的 Amazon Pinpoint 应用程序，用户必须有权调用 Amazon Pinpoint ARN 上的 `mobiletargeting:GetApp`。否则，Amazon Chime SDK 在调用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_identity-chime_RegisterAppInstanceUserEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_identity-chime_RegisterAppInstanceUserEndpoint.html) 时会引发 403 禁止错误。
此示例介绍了注册终端节点所需的策略。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "PermissionToRegisterEndpoint",
"Effect": "Allow",
"Action": "chime:RegisterAppInstanceUserEndpoint",
"Resource": "arn:aws:chime:us-east-1:123456789012:app-instance/app_instance_id/user/app_instance_user_id"
},
{
"Sid": "PermissionToGetAppOnPinpoint",
"Effect": "Allow",
"Action": "mobiletargeting:GetApp",
"Resource": "arn:aws:mobiletargeting:us-east-1:123456789012:apps/project_id"
}
]
}
```
------
**要注册终端节点**
+ 使用 Amazon Pinpoint ARN 和设备令牌调用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_identity-chime_RegisterAppInstanceUserEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_identity-chime_RegisterAppInstanceUserEndpoint.html) API。
# 在 Amazon Chime SDK 消息传递中在启用通知的情况下发送频道消息
[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_SendChannelMessage.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_SendChannelMessage.html) API 有一个可选 `PushNotification` 属性，Amazon Chime SDK 使用该属性来构建要发送到 Amazon Pinpoint 的推送通知。目前，Amazon Chime SDK 仅支持通知标头和正文字段。
Amazon Chime 软件开发工具包还支持 Vo APNs IP 推送。要将推送通知作为 APNs VoIP 推送发送，请将`PushNotification`属性中的类型设置为 VOIP。
# 在 Amazon Chime SDK 消息传递中接收推送通知
除了频道消息推送通知的标头和正文外，Amazon Chime SDK 还在数据负载中包含频道消息 ID 和频道 ARN。您可以使用该信息来加载完整的频道消息。
以下示例介绍了典型的推送通知负载。
```
{
"pinpoint.openApp=true",
"pinpoint.notification.title=PushNotificationTitle",
"pinpoint.notification.body=PushNotificationBody",
"pinpoint.campaign.campaign_id=_DIRECT",
"pinpoint.notification.silentPush=0",
"pinpoint.jsonBody="{
"chime.message_id":"ChannelMessageId",
"chime.channel_arn":"ChannelARN"
}
}
```
## 禁用或筛选推送通知回执
Amazon Chime SDK 提供了多个选项，允许应用程序实例用户控制他们是否希望接收推送通知。
**禁用所有推送通知**
应用程序实例用户可以调用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_identity-chime_UpdateAppInstanceUserEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_identity-chime_UpdateAppInstanceUserEndpoint.html) 并将 `AllowMessages` 属性设置为 `NONE`，从而完全禁用推送通知。
**禁用频道的推送通知**
应用程序实例用户可以通过在 “**PushNotification 首选项**” 字段`NONE`中调[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_PutChannelMembershipPreferences.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_PutChannelMembershipPreferences.html)用来禁用特定频道的推送通知。
**筛选频道的推送通知**
应用程序实例用户可以设置过滤规则，让自己在使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_PutChannelMembershipPreferences.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_PutChannelMembershipPreferences.html) API 时只能接收特定的推送通知。有关更多信息，请参阅[在 Amazon Chime SDK 消息传递中使用筛选规则来筛选消息](filter-msgs.md)。
# 为 Amazon Chime SDK 消息传递调试推送通知失败
Amazon Chime SDK 与亚马逊集成，以便 EventBridge 在推送消息传送失败时通知您。要进一步调试故障，您还可以查看 Amazon Pinpoint 发送的故障[CloudWatch指标](https://docs.aws.amazon.com/pinpoint/latest/userguide/monitoring-metrics.html)。
下表列出并描述了传送错误消息。
| Message | 说明 |
| --- | --- |
| 由于未知错误、异常或故障，请求处理失败。 | 我们遇到了内部错误。Please try again. |
| 未找到指定的资源。 AppInstanceUserEndpoint将被停用。 | Amazon Pinpoint 应用程序不存在。 |
| 向 Amazon Pinpoint 发送的请求过多。 | Amazon Pinpoint 已限制您的外发消息。 |
| 无法发送消息。请验证 IAM 权限策略已启用 ServiceRoleForAmazonChimePushNotification。 | 为 Amazon Chime SDK 创建的角色无权调用 `mobiletargeting:SendMessages`。请验证角色的 IAM policy。 |
| 无法发送消息。请验证 IAM 信任关系 ServiceRoleForAmazonChimePushNotification。 | Amazon Chime SDK 没有访问推送通知角色的权限。 请验证 IAM 角色的信任策略是否包含服务主体，`messaging.chime.amazonaws.com`。 |
# 在 Amazon Chime SDK 消息传递中使用筛选规则来筛选消息
Amazon Chime SDK 支持对应用程序实例用户的通道成员资格设置筛选规则，以限制他们将收到的消息。筛选规则在通道成员资格上设置，并根据消息属性映射运行。消息属性映射必须是字符串键到字符串值的映射。筛选规则支持包含和专属精确字符串匹配。
**重要**
Amazon Chime SDK 仅支持将转义的 JSON 字符串作为筛选规则。
通知通道的所有成员都会收到推送通知，包括消息发送者。要防止发生这种情况，请参阅下面的第一个示例规则。
要对通道成员资格设置筛选规则，请使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_PutChannelMembershipPreferences.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_PutChannelMembershipPreferences.html) API。您可以在通道消息中包含消息属性，作为 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_SendChannelMessage.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_SendChannelMessage.html) API 调用的一部分。
**Topics**
+ [筛选规则类型](#filter-rule-types)
+ [筛选规则限制](#filter-rule-limits)
+ [筛选规则示例](#example-preference-rule)
## 筛选规则类型
Amazon Chime SDK 支持以下筛选规则类型：
+ 包含精确字符串匹配
+ 专属精确字符串匹配
+ 使用 AND 或 OR 的多重筛选规则
## 筛选规则限制
Amazon Chime SDK 对筛选规则施加了以下限制：
+ 我们只支持精确字符串匹配。
+ 筛选规则的总大小为 2KB。
+ 消息属性的总大小为 1KB。
+ OR 筛选规则中最多有五 (5) 个单独的约束。
+ 整个筛选规则的最大复杂度为 20。*复杂度*是根据筛选规则中键值数量的总和计算得出的：
例如，此筛选规则的复杂度为 4。
```
"FilterRule": "{\"type\":[{\"anything-but\": [\"Room\"]}],\"mention\":[\"Bob\"]}
```
我们按如下方式计算该值：
```
Keys = “type” and “mention” - Complexity 2
Values = "Room" and "Bob" - Complexity 2
Total complexity = 4
```
## 筛选规则示例
以下示例显示了使用通道成员资格首选项和筛选规则的几种方法。
**防止邮件发送给发件人**
此筛选规则会向除消息发送者之外的所有通道成员发送消息。
```
{
"Preferences": {
"PushNotifications": {
"FilterRule": "{\"type\":[{\"anything-but\": [\"USER_ARN\"]}]}",
"AllowNotifications": "FILTERED"
}
}
}
```
具有上述首选项的应用实例用户会收到包含以下属性的通道消息：
```
"MessageAttributes": {
"senderId": {
"StringValues": ["USER_ARN"]
}
}
```
**包含字符串匹配**
此筛选规则允许包含如下消息属性的任何消息：键为“mention”且值为“Bob”。
```
{
"Preferences": {
"PushNotifications": {
"FilterRule": "{\"mention\":[\"Bob\"]}",
"AllowNotifications": "FILTERED"
}
}
}
```
具有上述首选项的应用实例用户会收到包含以下消息属性的通道消息：
```
"MessageAttributes": {
"mention": {
"StringValues": ["Bob", "Alice"]
}
}
```
但是，应用程序实例用户不会收到包含以下属性的通道消息：
```
"MessageAttributes": {
"mention": {
"StringValues": ["Tom"]
}
}
```
**专属字符串匹配**
此筛选规则允许除包含如下属性的消息以外的任何消息：键为“type”且值为“Room”。
```
{
"Preferences": {
"PushNotifications": {
"FilterRule": "{\"type\":[{\"anything-but\": [\"Room\"]}]}",
"AllowNotifications": "FILTERED"
}
}
}
```
具有这些首选项的应用实例用户会收到包含以下消息属性的通道消息：
```
"MessageAttributes": {
"type": {
"StringValues": ["Conversation"]
}
}
```
但是，应用程序实例用户看不到包含以下属性的通道消息：
```
"MessageAttributes": {
"type": {
"StringValues": ["Room"]
}
}
```
**采用 AND 逻辑的多重筛选规则**
当您将筛选规则与 AND 逻辑组合使用时，消息必须满足该筛选的所有筛选条件才能应用。
```
{
"Preferences": {
"PushNotifications": {
"FilterRule": "{\"type\":[{\"anything-but\": [\"Room\"]}],\"mention\":[\"Bob\"]}",
"AllowNotifications": "FILTERED"
}
}
}
```
具有上述首选项的应用实例用户会收到包含以下消息属性的通道消息：
```
"MessageAttributes": {
"mention": {
"StringValues": ["Bob"]
},
"type": {
"StringValues": ["Conversation"]
}
}
```
**采用 OR 逻辑的多重筛选规则**
您可以使用 `$or` 来组合筛选规则与 OR 逻辑。当您使用 OR 逻辑时，消息必须满足筛选条件之一才能应用。
```
{
"Preferences": {
"PushNotifications": {
"FilterRule": "{\"$or\":[{\"mention\":[\"Bob\"]},{\"type\":[{\"anything-but\": [\"Room\"]}]}]}",
"AllowNotifications": "FILTERED"
}
}
}
```
具有上述首选项的应用实例用户会收到包含以下消息属性的通道消息：
```
"MessageAttributes": {
"mention": {
"StringValues": ["Bob"]
}
}
```
具有上述首选项的应用实例用户会收到包含以下消息属性的通道消息：
```
"MessageAttributes": {
"type": {
"StringValues": ["Conversation"]
}
}
```
# 为 Amazon Chime SDK 消息传递使用服务相关角色
Amazon Chime 软件开发工具包使用 AWS Identity and Access Management (IAM) [服务相关](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-linked-role)角色。服务相关角色是一种独特类型的 IAM 角色，它与 Amazon Chime SDK 直接关联。Amazon Chime SDK 预定义了服务相关角色，它们包含该服务代表您调用其他 AWS 服务所需的所有权限。
服务相关角色可更轻松地设置 Amazon Chime SDK，因为您不必手动添加必要权限。Amazon Chime SDK 定义其服务相关角色的权限，除非另外定义，否则只有 Amazon Chime SDK 可以代入该角色。定义的权限包括信任策略和权限策略。不能将该权限策略附加到任何其他 IAM 实体。
只有在首先删除服务相关角色的相关资源后，才能删除该角色。这将保护您的 Amazon Chime SDK 资源，因为您不会无意中删除对资源的访问权限。
有关支持服务关联角色的其他服务的信息，请参阅[与 IAM 配合使用的AWS 服务](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html)。查找在 **Service-Linked Role（服务相关角色）**列中具有 **Yes（是）**值的服务。选择**是**与查看该服务文档的链接。
**Topics**
+ [为 Amazon Chime SDK 消息传递中的数据流使用服务相关角色](stream-service-linked.md)
# 为 Amazon Chime SDK 消息传递中的数据流使用服务相关角色
以下部分说明如何管理数据流的服务相关角色。
**Topics**
+ [服务相关角色权限](#role-permissions)
+ [创建服务相关角色](#create-service-linked-role)
+ [编辑服务相关角色](#editing-roles)
+ [删除服务相关角色使用的资源](#cleaning-up)
+ [删除服务相关角色](#deleting-roles)
## 服务相关角色权限
Amazon Chime SDK 使用名为 **AWSServiceRoleForChimeSDKMessaging** 的服务相关角色。该角色授予访问由 Amazon Chime SDK 使用或托管的 AWS 服务和资源的权限，例如用于数据流的 Kinesis流。
**AWSServiceRoleForChimeSDKMessaging** 服务相关角色信任以下服务来代入角色：
+ messaging.chime.amazonaws.com
角色权限策略允许 Amazon Chime SDK 对指定资源完成以下操作：
+ 仅当使用 `kinesis.*.amazonaws.com` 发出请求时 `kms:GenerateDataKey`。
+ `kinesis:PutRecord`、`kinesis:PutRecords` 或者 `kinesis:DescribeStream` 仅在以下格式的流上显示：`arn:aws:kinesis:*:*:stream/chime-messaging-*`。
以下示例显示了该策略。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"kms:GenerateDataKey"
],
"Resource": "*",
"Condition": {
"StringLike": {
"kms:ViaService": [
"kinesis.*.amazonaws.com"
]
}
}
},
{
"Effect": "Allow",
"Action": [
"kinesis:PutRecord",
"kinesis:PutRecords",
"kinesis:DescribeStream"
],
"Resource": [
"arn:aws:kinesis:*:*:stream/chime-messaging-*"
]
}
]
}
```
------
您必须配置权限，允许 IAM 实体（如用户、组或角色）创建、编辑或删除服务相关角色。有关更多信息，请参阅 *IAM 用户指南*中的[服务相关角色权限](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#service-linked-role-permissions)。
## 创建服务相关角色
您无需手动创建服务关联角色。当您使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_PutMessagingStreamingConfigurations.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_PutMessagingStreamingConfigurations.html) API 创建数据流配置时，Amazon Chime SDK 会为您创建服务相关角色。
您也可以使用 IAM 控制台为 Amazon Chime SDK 使用案例创建服务相关角色。在 AWS CLI 或 AWS API 中，使用服务名称创建`messaging.chime.amazonaws.com`服务相关角色。有关更多信息，请参阅 *IAM 用户指南*中的[创建服务相关角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#create-service-linked-role)。如果您已删除此角色，则可以重复此过程再次创建。
## 编辑服务相关角色
创建服务相关角色后，您只能编辑其描述，且使用 IAM 进行编辑。有关更多信息，请参阅 *IAM 用户指南*中的[编辑服务相关角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#edit-service-linked-role)。
## 删除服务相关角色使用的资源
必须先删除服务相关角色使用的所有资源，然后才能使用 IAM 删除该角色。
**注意**
如果您试图删除 Amazon Chime SDK 正在使用的资源，则删除可能会失败。如果发生这种情况，请等待几分钟后重试。
**删除 AmazonChimeServiceChatStreamingAccess 角色使用的资源的步骤如下：**
运行以下 CLI 命令关闭应用程序实例的数据流式传输：
+ `aws chime-sdk-messaging delete-messaging-streaming-configurations --app-instance-arn app_instance_arn`
此操作会删除您的应用程序实例的所有流配置。
## 删除服务相关角色
如果不再使用某个需要服务相关角色的特征或服务，我们建议您删除该角色。否则，您将拥有一个未使用实体，而该实体未得到主动监控或维护。但是，您必须先删除服务相关角色使用的资源后，才能手动删除该角色。
您可以使用 IAM 控制台或 AWS API 删除**AmazonChimeServiceRoleForChimeSDKMessaging**服务相关角色。 AWS CLI有关更多信息，请参阅《IAM 用户指南》中的[删除服务相关角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#delete-service-linked-role)。
# 在 Amazon Chime SDK 消息传递中使用频道流来处理消息
您可在发送中的消息通过消息频道送达收件人之前，使用频道流在这些消息上运行业务逻辑。频道流可以执行诸如从消息中删除政府身份证号、电话号码或亵渎内容之类的操作。您还可以使用频道流来执行诸如在将结果发回给参与者之前汇总对民意调查的回复之类的功能。
**先决条件**
+ 了解 Amazon Chime SDK 的基本功能，例如管理频道以及发送和接收消息。
+ 能够调用 Amazon Chime 软件开发工具包消息。 APIs
**频道流概念**
要有效地使用频道流，您必须了解以下概念：
**频道处理器数**
对频道消息运行预处理逻辑的 AWS Lambda 函数。当您将频道与频道流关联时，系统会为频道中的每条消息调用流程中的处理器。为了减少延迟，单个处理器最适合大多数用例。最后，处理完成后，每个处理器都必须回调 Amazon Chime SDK 服务。
目前，每个频道流仅支持一个处理器。如果您需要多个处理器，请提交支持工单以增加处理器。
**频道流**
频道流是最多可容纳三个频道处理器的容器，外加一个运行序列。您将流量与频道相关联，处理器会对发送到该频道的所有消息采取行动。
**调用频道流**
以下项目调用频道流：
+ 新的永久性标准消息
+ 新的非永久性标准消息
+ 更新了永久性标准消息
**注意**
频道流不处理控制或系统消息。有关 Amazon Chime SDK 消息传递提供的消息类型的更多信息，请参阅 [了解 Amazon Chime SDK 消息类型](msg-types.md)。
**Topics**
+ [为 Amazon Chime SDK 消息传递设置频道处理器](processor-setup.md)
+ [为 Amazon Chime SDK 消息传递创建频道流](create-channel-flow.md)
+ [为 Amazon Chime SDK 消息传递关联和取消关联频道流](associate-channel-flow.md)
+ [在 Amazon Chime SDK 消息传递中发送消息](sending-msgs.md)
+ [通过 Amazon Chime 软件开发工具包 EventBridge 消息自动生成故障警报](event-bridge-events.md)
# 为 Amazon Chime SDK 消息传递设置频道处理器
要开始使用频道流，您需要先创建一个处理器 Lambda 函数来处理您的用例的预处理。例如，您可以更新消息内容或元数据、拒绝消息并阻止发送消息，或者允许原始消息通过。
**先决条件**
+ Lambda 函数必须与位于同一个 AWS 账户和相同 AWS 区域中。 AppInstance
**授予调用权限**
您必须向 Amazon Chime SDK 消息收发服务授予权限才能调用 Lambda 资源。有关权限的更多信息，请参阅[将基于资源的策略用于 AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/access-control-resource-based.html)。例如：
**主体**：“messaging.chime.amazonaws.com”
**动作**：lambda：InvokeFunction
**效果**：允许
**AWSSourceAccount:**: *Your AWS AccountId*。
**AWS: SourceArn**: `"arn:aws:chime:region:AWS AccountId: appInstance/"`
**注意**
您可以提供特定的应用程序实例 ID 来调用您的处理器，也可以使用通配符允许账户中的所有 Amazon Chime SDK 应用程序实例调用您的处理器。
**授予回调权限**
您还需要允许您的处理器 Lambda 函数调用 `ChannelFlowCallback` API。有关执行此操作的信息，请参阅 *AWS Lambda 开发人员指南*中的 [AWS Lambda 执行角色](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html)。
您可以向 Lambda 函数的执行角色添加内联策略。此示例允许处理器调用 `ChannelFlowCallback API`。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"chime:ChannelFlowCallback"
],
"Resource": [
"arn:aws:chime:us-east-1:111122223333:appInstance/*"
]
}
]
}
```
------
**注意**
遵循 Lambda 函数的最佳实践。有关更多信息，请参阅以下主题：
[性能效率最佳实践](https://docs.aws.amazon.com/whitepapers/latest/serverless-architectures-lambda/performance-efficiency-best-practices.html)
[使用的最佳实践 AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/best-practices.html)
[配置预留并发](https://docs.aws.amazon.com/lambda/latest/dg/configuration-concurrency.html#configuration-concurrency-reserved)
[异步调用](https://docs.aws.amazon.com/lambda/latest/dg/invocation-async.html)
**调用处理器 Lambda 函数**
当用户发送消息时，以下输入请求会调用处理器 Lambda 函数。
```
{
"EventType": "string"
"CallbackId": "string"
"ChannelMessage": {
"MessageId": "string",
"ChannelArn": "string",
"Content": "string",
"Metadata": "string",
"Sender":{
"Arn": "string",
"Name": "string"
},
"Persistence": "string",
"LastEditedTimestamp": "string",
"Type": "string",
"CreatedTimestamp": "string",
}
}
```
EventType
正在发送到处理器的事件。该值是一个 `CHANNEL_MESSAGE_EVENT` 常数。
CallbackId
从处理器调用 `ChannelFlowCallback` API 时使用的令牌。
ChannelMessage
*ChannelArn*该频道的 ARN
*Content*：待处理的消息内容
*CreatedTimestamp*消息的创建时间
*LastEditedTimestamp*编辑消息的时间
*MessageId*消息标识符
*Metadata*：待处理的消息元数据
*Persistence*：布尔值，用于控制消息是否保留在后端。有效值：`PERSISTENT | NON_PERSISTENT`
*Sender*：消息发件人。Type：一个 [identity 对象](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_Identity.html)。
*Type*：消息类型。ChannelFlow 仅支持 `STANDARD` 消息类型。有效值：`STANDARD`
处理器函数决定每条消息的以下内容。
+ 是更新消息内容、元数据还是两者兼而有之
+ 是否拒绝消息
+ 是否保留消息不变
处理完成后，处理器 Lambda 函数会将结果发送回 Amazon Chime SDK 消息传递服务，这样就可以将消息发送给所有收件人。消息状态一直处于 `PENDING` 标记状态，直到处理器 Lambda 函数发回结果。处理器 Lambda 函数有 48 小时的时间来发送结果。在此之后，我们无法保证消息传递，[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelFlowCallback.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelFlowCallback.html) API 会引发“Forbidden Exception”错误消息。要发回结果，请调用 `ChannelFlowCallback` API。
# 为 Amazon Chime SDK 消息传递创建频道流
设置好处理器后，即可使用 Amazon Chime SDK 消息传送 APIs 来创建渠道流。您可以使用 `Fallback` 操作来定义在频道流无法连接到处理器 Lambda 函数时是停止还是继续处理。如果处理器的回退操作为 `ABORT`，则处理器会将消息状态设置为 `FAILED`，并且不会发送消息。请注意，如果频道流序列中的最后一个处理器的回退操作为 `CONTINUE`，则消息被视为已处理并已发送给频道中的收件人。创建频道流后，您可以将其与各个频道相关联。有关更多信息，请参阅 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelFlow.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelFlow.html) API 文档。
# 为 Amazon Chime SDK 消息传递关联和取消关联频道流
当您将频道与频道流关联时，频道流中的处理器会对发送到该频道的所有消息进行预处理。您必须是频道版主或管理员才能调用频道流关联和取消关联 APIs。边走边记住这些事实。
+ 在任何给定时间，您最多可以将 1 个频道流与一个频道相关联。要关联渠道流，请调用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_AssociateChannelFlow.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_AssociateChannelFlow.html) API。
+ 要取消关联频道流并停止对频道消息的预处理，请调用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_DisassociateChannelFlow.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_DisassociateChannelFlow.html) API。
# 在 Amazon Chime SDK 消息传递中发送消息
您可以使用 `SendChannelMessage` API 向频道发送消息。对于与频道流关联的频道，处理器会分配以下状态值之一。
| 消息状态 | 说明 |
| --- | --- |
| `SENT` | 消息已成功处理。 |
| `PENDING` | 正在处理中。 |
| `FAILED` | 处理失败，因为无法访问处理器 Lambda 函数。 |
| `DENIED` | 将不会发送该消息。 |
**接收中间状态事件**
**WebSocket 事件**
WebSocket 事件将在成功建立连接后发送到频道。有关更多信息，请参阅[WebSockets 用于在 Amazon Chime 软件开发工具包消息中接收消息](websockets.md)。
| 事件类型 | Status | 收件人 | 注意 |
| --- | --- | --- | --- |
| `CREATE_CHANNEL_MESSAGE` | `SENT` | 所有频道成员 | 预处理成功的 `SendChannelMessage` API |
| `UPDATE_CHANNEL_MESSAGE` | `SENT` | 所有频道成员 | 预处理成功的 `UpdateChannelMessage` API |
| `PENDING_CREATE_CHANNEL_MESSAGE` | `PENDING` | 仅限消息发件人 | 正在进行预处理的 `SendChannelMessage` API |
| `PENDING_UPDATE_CHANNEL_MESSAGE` | `PENDING` | 仅限消息发件人 | 正在进行预处理的 `UpdateChannelMessage` API |
| `FAILED_CREATE_CHANNEL_MESSAGE` | `FAILED` | 仅限消息发件人 | 预处理失败的 `SendChannelMessage` API |
| `FAILED_UPDATE_CHANNEL_MESSAGE` | `FAILED` | 仅限消息发件人 | 预处理失败的 `UpdateChannelMessage` API |
| `DENIED_CREATE_CHANNEL_MESSAGE` | `DENIED` | 仅限消息发件人 | 处理器拒绝该消息的 `SendChannelMessage` API |
| `DENIED_UPDATE_CHANNEL_MESSAGE` | `DENIED` | 仅限消息发件人 | 处理器拒绝该消息的 `UpdateChannelMessage` API |
**GetChannelMessageStatus API**
如果由于 WebSocket 连接不良而未收到事件，此 API 提供了另一种检索消息状态的方法。有关更多信息，请参阅 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetChannelMessageStatus.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetChannelMessageStatus.html) API 文档。
**注意**
此 API 不会返回被拒消息的状态，因为我们不存储此类消息。
# 通过 Amazon Chime 软件开发工具包 EventBridge 消息自动生成故障警报
当调用处理器 Lambda 函数出现错误时，Amazon Chime SDK 会发送事件。创建频道流时，无论为处理器指定了什么 `Fallback` 操作，都会发送事件。您可以编写指定此类事件的简单规则，以及当其中任何事件与规则匹配时要执行的自动操作。有关更多信息，请参阅 [Amazon EventBridge 用户指南](https://docs.aws.amazon.com/eventbridge/latest/userguide/)。当出现此类错误时，根据您配置的 `Fallback` 操作，频道中的成员无法发送消息，或者消息将在不经过处理的情况下流经频道。有关 `Fallback` 操作的更多信息，请参阅《Amazon Chime SDK API 参考》中的 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_Processor.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_Processor.html)。
此示例显示了一个典型的故障事件。
```
{
"version": "0",
"id": "12345678-1234-1234-1234-111122223333",
"detail-type": "Chime ChannelFlow Processing Status",
"source": "aws.chime",
"account": "111122223333",
"time": "yyyy-mm-ddThh:mm:ssZ",
"region": "region",
"resources": [],
"detail": {
"eventType": "ProcessorInvocationFailure",
"appInstanceArn": "arn:aws:chime:region:AWSAccountId:app-instance/AppInstanceId",
"channelArn": "arn:aws:chime:region:AWSAccountId:app-instance/AppInstanceId/channel/ChannelId",
"messageId": "298efac7298efac7298efac7298efac7298efac7298efac7298efac7298efac7",
"processorResourceArn": "arn:aws:lambda:region:AWSAccountId:function:ChannelFlowLambda",
"failureReason": "User is not authorized to perform: lambda:InvokeFunction on resource: arn:aws:lambda:region:AppInstanceId:function:ChannelFlowLambda because no resource-based policy allows the lambda:InvokeFunction action"
}
}
```
# 用 AppInstanceBots 作 Amazon Chime SDK 消息传递的智能渠道代理
您可以将 `AppInstanceBots` 用作智能频道座席。座席可以识别频道成员通过 `ChannelMessages` 发送的关键短语。机器人的自然语言理解模型可以解析消息。反过来，这允许一个或多个频道成员参与由机器人模型定义的自然语言对话。您提供机器人，这样您就可以控制对话的深度以及与企业系统的集成。
**先决条件**
+ 了解 Amazon Chime SDK 的基本功能，例如创建 `AppInstanceUsers`、管理频道以及发送和接收消息。
+ 能够调用 Amazon Chime 软件开发工具包消息。 APIs
+ 了解 Amazon Lex V2 的基本功能，例如创建 Amazon Lex V2 机器人、建模意图和插槽、创建机器人版本、别名、使用会话状态以及 Lambda 钩子集成。
**重要**
使用 Amazon Lex V2 需遵守 [AWS 服务条款](https://aws.amazon.com/service-terms/)，包括 AWS Machine Learning 和 Artificial Intelligence Services 的特定条款。
**Topics**
+ [创建用于 Amazon Chime SDK 消息传递的 Amazon Lex V2 机器人](create-lex-bot.md)
+ [为 Amazon Chime SDK 消息传递设置 AppInstance 机器人](appinstance-bot-setup.md)
+ [为适用于 Amazon 的 Chime 软件 AppInstanceBot 开发工具包消息创建频道成员资格](channel-membership.md)
+ [向 AppInstanceBot 适用于 Amazon 的 Chime 软件开发工具包消息发送消息](message-appinstancebot.md)
+ [在 Amazon Chime SDK 消息传递中处理来自 Amazon Lex 的消息](process-from-lexv2.md)
+ [正在处理来自 For Amazon Chime 软件开发工具包消息 AppInstanceBot 的响应](process-response.md)
+ [使用规则将事件发送到亚马逊以进行 Amazon EventBridge Chime SDK 消息传递](event-bridge-alerts.md)
+ [使用 Amazon Lex V2 机器人为亚马逊 Chime SDK 消息传递 AppInstanceBots 配置故障排除](troubleshoot-lex-bots.md)
# 创建用于 Amazon Chime SDK 消息传递的 Amazon Lex V2 机器人
要使用 AppInstance 机器人作为代理，您首先需要创建一个 Amazon Lex V2 机器人来管理智能代理场景的对话交互。要开始构建 Amazon Lex V2 机器人，请参阅*《Amazon Lex V2 开发人员指南》*中的 [Amazon Lex V2 入门](https://docs.aws.amazon.com/lexv2/latest/dg/getting-started.html)。有关将 Amazon Lex V1 机器人迁移到 Amazon Lex V2 的信息，请参阅 [Amazon Lex V1 至 V2 迁移指南](https://docs.aws.amazon.com/lexv2/latest/dg/migration.html)。
**Topics**
+ [先决条件](#lex-prereqs)
+ [授予调用权限](#invocation-perms)
+ [创建用于 Amazon Chime SDK 消息传递的欢迎意图](welcome-intent.md)
+ [创建用于 Amazon Chime SDK 消息传递的 Amazon Lex V2 机器人版本](lex-versions.md)
+ [创建用于 Amazon Chime SDK 消息传递的 Amazon Lex V2 机器人别名](lex-aliases.md)
## 先决条件
您的 Amazon Lex V2 机器人必须具有以下先决条件。
+ 您必须在支持 Amazon Lex V2 运行时终端节点的 AWS 区域中创建该机器人。
+ 您必须在与和相同的 AWS 账户和区域中创建机器人`AppInstanceBot`。`AppInstance`
+ 机器人必须通过基于资源的策略向 `messaging.chime.amazonaws.com` 服务主体授予调用权限。
+ 机器人可以建模欢迎意图。这允许 `AppInstanceBot` 在加入频道后显示自己及其功能。
+ 机器人应具有生产版本与别名功能才能配置 `AppInstanceBot`。
+ 机器人必须使用支持的语言和区域设置。有关语言和区域设置的更多信息，请参阅《Amazon Lex V2 开发人员指南》**中的 [Amazon Lex V2 支持的语言和区域设置](https://docs.aws.amazon.com/lexv2/latest/dg/how-languages.html)。
## 授予调用权限
对于要调用 Amazon Lex V2 机器人的 `AppInstanceBot`，Amazon Chime SDK 消息传递服务主体必须有权调用 Amazon Lex 机器人资源。有关 Amazon Lex V2 基于资源的策略权限的更多信息，请参阅*《Amazon Lex V2 开发人员指南》*中的 [Amazon Lex V2 基于资源的策略示例](https://docs.aws.amazon.com/lexv2/latest/dg/security_iam_resource-based-policy-examples.html)。
以下示例介绍了基于资源的策略。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "messaging.chime.amazonaws.com"
},
"Action": [
"lex:PutSession",
"lex:DeleteSession",
"lex:RecognizeText"
],
"Resource": "arn:aws:lex:us-east-1:111122223333:bot-alias/lex-bot-id/lex-bot-alias-id",
"Condition": {
"StringEquals": {
"AWS:SourceAccount": "111122223333"
},
"ArnEquals": {
"AWS:SourceArn": "arn:aws:chime:us-east-1:111122223333:app-instance/app-instance-id/bot/app-instance-bot-id"
}
}
}
]
}
```
------
**注意**
要允许用户调用 Amazon Lex V2 机器人，请使用 AppInstanceBot的 ID。`AppInstanceBot`要允许 `AppInstance` 中的所有 `AppInstanceBots` 调用 Amazon Lex V2 机器人，请使用通配符。例如：
`arn:aws:chime:region:aws-account-id:app-instance/app-instance-id/bot/*`
# 创建用于 Amazon Chime SDK 消息传递的欢迎意图
如果您在 Amazon Lex V2 机器人模型中添加了可选的欢迎意图，则 `AppInstanceBot` 可以在它加入频道时显示自己及其功能。欢迎意图可以显示消息，也可以发起与频道成员的对话。欢迎意图的名称可能有所不同，您可以在 AppInstanceBot的配置中对其进行定义。
有关意图的更多信息，请参阅*《Amazon Lex V2 开发人员指南》*中的[添加意图](https://docs.aws.amazon.com/lexv2/latest/dg/build-intents.html)。
# 创建用于 Amazon Chime SDK 消息传递的 Amazon Lex V2 机器人版本
创建 Amazon Lex V2 机器人时，您只能创建*草稿*版本。草稿是您可以更新的机器人的工作副本。默认情况下，草稿版本与名为 `TestBotAlias` 的别名相关联，您只能使用草稿版机器人进行手动测试。
完成对话建模并构建草稿版机器人后，您可创建一个或多个*版本*，即草稿版 Lex 机器人的带编号快照。版本允许您控制客户端应用程序使用的实现。例如，您可以发布版本以用于您的工作流的不同阶段，如开发、测试部署和生产。
有关 Lex 机器人版本控制的更多信息，请参阅*《Amazon Lex V2 开发人员指南》*中的[创建版本](https://docs.aws.amazon.com/lexv2/latest/dg/versions.html)。
# 创建用于 Amazon Chime SDK 消息传递的 Amazon Lex V2 机器人别名
一旦您创建了一个或多个版本的 Amazon Lex V2 机器人，就可以创建*别名*。别名充当指向 Amazon Lex V2 机器人版本的命名指针。例如，您一次只能将别名与一个版本关联。
有关 Lex 机器人别名的更多信息，请参阅*《Lex V2 开发人员指南》*中的[创建别名](https://docs.aws.amazon.com/lexv2/latest/dg/aliases.html)。
# 为 Amazon Chime SDK 消息传递设置 AppInstance 机器人
在你拥有带有型号、版本和别名的 Amazon Lex V2 机器人之后，你可以使用 Amazon Chime SDK APIs 消息或 CLI 来创建。 AppInstanceBot有关使用的更多信息 APIs，请参阅 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_identity-chime_CreateAppInstanceBot.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_identity-chime_CreateAppInstanceBot.html)API 文档。
**注意**
您可以使用 `InvokedBy` 属性来配置 `AppInstanceBot` 的对话框交互行为。您可以配置触发机器人的消息类型，例如标准消息或定向消息。
以下示例说明如何使用 AWS CLI 创建所有 AppInstanceBot 包含的标准消息和目标消息都可以调用的。`MENTIONS`
```
aws chime-sdk-identity create-app-instance-bot \
--app-instance-arn app-instance-arn \
--name app-instance-bot-name \
--configuration '{
"Lex": {
"LexBotAliasArn": "lex-bot-alias-arn",
"LocaleId": "lex_bot_alias_locale_id",
"InvokedBy": {
"StandardMessages": "MENTIONS",
"TargetedMessages": "ALL"
}
"WelcomeIntent": "welcome-intent-name"
}
}
```
# 为适用于 Amazon 的 Chime 软件 AppInstanceBot 开发工具包消息创建频道成员资格
创建后 AppInstanceBot，即可将其作为成员添加到新频道或现有频道。有关更多信息，请参阅 *Amazon Chime 软件开发工具包消息 API* 文档[ CreateChannelMembership](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html)中的[CreateChannel](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannel.html)和。
以下示例说明如何使用 AWS CLI 创建频道并将添加`AppInstanceBot`为成员。
```
aws chime-sdk-messaging create-channel \
--chime-bearer caller_app_instance_user_arn \
--app-instance-arn app_instance_arn \
--name channel_name \
--member-arns '[
"app_instance_bot_arn"
]'
```
以下示例说明如何使用 AWS CLI `AppInstanceBot` 向现有频道添加。
```
aws chime-sdk-messaging create-channel-membership \
--chime-bearer caller_app_instance_user_arn \
--channel-arn channel_arn \
--member-arn app_instance_bot_arn
```
# 向 AppInstanceBot 适用于 Amazon 的 Chime 软件开发工具包消息发送消息
您可以使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_SendChannelMessage.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_SendChannelMessage.html)API 向发送消息 AppInstanceBot。您将消息发送到该 AppInstanceBot 成员所在的频道。如果[自然语言理解模型](https://docs.aws.amazon.com/lexv2/latest/dg/what-is.html)识别出消息内容并引发 Amazon Lex 意图，则会使用频道消息进行 AppInstanceBot 响应并启动对话。
您还可以向频道成员发送目标消息，该成员可以是 AppInstanceUser 或 AppInstanceBot。只有目标和发件人可以查看定向消息。只有能够看到定向消息的用户才能对其采取行动。但是，管理员可以删除他们看不到的定向消息。
以下示例说明如何使用 AWS CLI 发送频道消息。
```
aws chime-sdk-messaging send-channel-message \
--chime-bearer caller_app_instance_user_arn \
--channel-arn channel_arn \
--content content \
--type STANDARD \
--persistence PERSISTENT
```
# 在 Amazon Chime SDK 消息传递中处理来自 Amazon Lex 的消息
向 Amazon Lex 发送消息时，Amazon Chime SDK 消息传递会将频道和发件人的 ARN 信息作为请求属性填充 `CHIME.channel.arn` 和 `CHIME.sender.arn`。您可以使用这些属性来确定谁发送了消息以及发件人所属的频道。有关更多信息，请参阅 *Amazon Lex 开发者*指南中的[使用 AWS Lambda 函数启用自定义逻辑](https://docs.aws.amazon.com/lexv2/latest/dg/lambda.html)。
# 正在处理来自 For Amazon Chime 软件开发工具包消息 AppInstanceBot 的响应
当用户发送消息时，用户会使用频道消息进行 AppInstanceBot 响应。您可以列出频道消息以获取机器人的回复。
以下示例介绍了如何使用 CLI 列出频道消息。
```
aws chime-sdk-messaging list-channel-messages \
--chime-bearer caller_app_instance_user_arn \
--channel-arn channel_arn
```
来自的成功响应 AppInstanceBot 采用以下格式。
```
{
"MessageId": "messageId",
"Content": "*{\"Messages\":[{\"...\"}]}*",
"ContentType": "application/amz-chime-lex-msgs",
"MessageAttributes": {
"CHIME.LEX.sessionState.intent.name": {
"StringValues": [
"lex_bot_intent_name"
]
},
"CHIME.LEX.sessionState.intent.state": {
"StringValues": [
"lex_bot_intent_fullfilment_status"
]
},
"CHIME.LEX.sessionState.originatingRequestId": {
"StringValues": [
"lex_bot_originating_request_id"
]
},
"CHIME.LEX.sessionState.sessionId": {
"StringValues": [
"lex_bot_session_id"
]
}
},
"Sender": {
"Arn": "app_instance_bot_arn",
"Name": "app_instance_bot_name"
},
"Type": "STANDARD",
}
```
**Content**
该 `Content` 字段包含源自 Amazon Lex V2 机器人的消息列表。有关这些消息的更多信息，请参阅 Amazon Lex V2 `RecognizeText` API 中的[消息](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_runtime_RecognizeText.html#lexv2-runtime_RecognizeText-response-messages)。
以下示例说明如何在欢迎消息中使用 `Content` 字段。
```
{
"Messages":
[
{
"Content": "Hello!",
"ContentType": "PlainText"
},
{
"ContentType": "ImageResponseCard",
"ImageResponseCard":
{
"Title": "Hello! I'm BB, the Bank Bot.",
"Subtitle": "I can help you with the following transactions",
"Buttons":
[
{
"Text": "Check balance",
"Value": "Check balance"
},
{
"Text": "Escalate to agent",
"Value": "Escalate to agent"
}
]
}
}
]
}
```
对于失败响应，“内容”字段包含以下格式的错误消息和代码：
```
{
"Code": error_code
}
```
**ContentType**
`ContentType` 是指该 `Content` 字段包含的负载类型，必须选中才能解析该 `Content` 字段。
Lex V2 机器人使用的是不同的 `ContentType`。
`ContentType` 设置为 `application/amz-chime-lex-msgs`（对于成功响应）或者 `application/amz-chime-lex-error`（对于失败响应）。
**MessageAttribute**
A *MessageAttribute*是字符串键到字符串值的映射。来自 `AppInstanceBot` 的响应包含以下消息属性，这些属性映射到来自 Amazon Lex 机器人的响应。
+ **CHIME.LEX.sessionState.intent.name**：请求尝试实现的 Lex 机器人意图名称。
+ **CHIME.LEX.sessionState.intent.state**：意图的当前状态。可能的值包括：`Fulfilled`、`InProgress` 和 `Failed`。
+ **chime.lex.sessionState。 originatingRequestId**— 向 Amazon Lex 机器人发出的特定请求的唯一标识符。该值设置为触发`MessageId`的原始用户消息的 AppInstanceBot。
+ **CHIME.LEX.sessionState.sessionId**：用户与机器人之间对话的唯一标识符。用户启动与机器人的聊天时，Amazon Lex 将创建一个会话。
有关 Amazon Lex 会话和会话状态的更多信息，请参阅《Amazon Lex API 参考》**中的 [https://docs.aws.amazon.com/lexv2/latest/APIReference/API_runtime_SessionState.html](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_runtime_SessionState.html) 和《Amazon Lex V2 开发人员指南》**中的[管理会话](https://docs.aws.amazon.com/lexv2/latest/dg/using-sessions.html)
有关 Amazon Lex V2 返回的属性的更多信息，请参阅亚马[逊 Lex Runtime V](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_Operations_Amazon_Lex_Runtime_V2.html) APIs 2。
# 使用规则将事件发送到亚马逊以进行 Amazon EventBridge Chime SDK 消息传递
当错误阻止其调用 Amazon Lex V2 机器人时，Amazon Chime SDK 会发送 EventBridge 事件。您可以创建识别这些事件的 EventBridge 规则，并在匹配规则时自动采取行动。有关更多信息，请参阅[ EventBridge 《亚马逊* EventBridge 用户指南》中的亚马逊*规则](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-rules.html)。
以下示例显示了典型故障事件。
```
{
version: '0',
id: '12345678-1234-1234-1234-111122223333',
'detail-type': 'Chime Messaging AppInstanceBot Lex Failure',
source: 'aws.chime',
account: 'aws-account-id',
time: 'yyyy-mm-ddThh:mm:ssZ',
region: "region",
resources: [],
detail: {
resourceArn: 'arn:aws:chime:region:aws-account-id:app-instance/app-instance-id/bot/app-instance-bot-id',
failureReason: "1 validation error detected: Value at 'text' failed to satisfy constraint: Member must have length less than or equal to 1024 (Service: LexRuntimeV2, Status Code: 400, Request ID: request-id)"
}
}
```
# 使用 Amazon Lex V2 机器人为亚马逊 Chime SDK 消息传递 AppInstanceBots 配置故障排除
以下主题说明了如何解决常见问题 AppInstanceBots。
## 调查发现 Amazon Lex V2 故障
当错误阻止亚马逊调用 Amazon Lex V2 机器人时，[Amazon Chime SDK 消息传递会传送亚马逊 EventBridge 事件](https://docs.aws.amazon.com/chime-sdk/latest/dg/event-bridge-alerts.html)。有关设置规则和配置通知目标的更多信息，请参阅亚马逊* EventBridge 用户指南 EventBridge中的亚马逊*[入门](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-get-started.html)。
如果您在 AWS CloudWatch 日志中收到 EventBridge 事件，则可以使用 AWS CloudWatch Logs Insights 根据 Amazon Chime SDK 消息详细信息类型查询 EventBridge 事件。`failureReason` 列出了失败的原因。
以下示例介绍了典型查询。
```
fields @timestamp, @message
| filter `detail-type` = "Chime Messaging AppInstanceBot Lex Failure"
| sort @timestamp desc
```
如果 Amazon Chime SDK 消息传递可以调用您的 Amazon Lex V2 机器人，则 SDK 会发送带有错误消息的 `CONTROL` 消息。
## 排除 Amazon Lex V2 机器人权限错误故障
AppInstanceBot 要调用 Amazon Lex V2 机器人，Amazon Chime SDK 消息服务委托人必须有权调用 Amazon Lex V2 Bot 资源。此外，请确保资源策略条件与的 ARN 相匹配。`AWS:SourceArn` AppInstanceBot
有关配置为调用 Amazon Lex V2 机器人的更多信息，请参阅本节前面部分。 AppInstanceBot [创建用于 Amazon Chime SDK 消息传递的 Amazon Lex V2 机器人](create-lex-bot.md)
## 排除 Amazon Lex V2 机器人节流故障
每个机器人别名的最大并发文本模式对话数 Amazon Lex 都有服务限额。如需增加限额，您可以联系 Amazon Lex 服务团队。有关更多信息，请参阅《Amazon Lex 开发者指南》**中的 [Amazon Lex 指南和限额](https://docs.aws.amazon.com/lexv2/latest/dg/quotas.html)。
# 在 Amazon Chime SDK 消息传递中管理消息保留日期
账户所有者可以使用 Amazon Chime SDK APIs 开启消息保留功能。根据管理员设置的时间段自动删除消息。保留期可以持续一天到十五年。您也可以随时使用 APIs 来更新留言保留期或关闭留言保留期。
**Topics**
+ [CLI 保留命令示例](#retention-examples)
+ [启用消息保留日期](#enable-retention)
+ [恢复和删除消息](#restore-and-delete)
## CLI 保留命令示例
以下示例介绍了用于保留的典型 CLI 命令：
**正在启用**
`aws chime-sdk-identity put-app-instance-retention-settings --app-instance-arn {appInstanceArn} --app-instance-retention-settings ChannelRetentionSettings={RetentionDays=60}`
**正在更新**
`aws chime-sdk-identity put-app-instance-retention-settings --app-instance-arn {appInstanceArn} --app-instance-retention-settings ChannelRetentionSettings={RetentionDays=30}`
**正在禁用**
`aws chime-sdk-identity put-app-instance-retention-settings --app-instance-arn {appInstanceArn} --app-instance-retention-settings ChannelRetentionSettings={}`
## 启用消息保留日期
您可以使用 Amazon Chime 软件开发工具包 APIs 开启消息保留功能。您也可以随时使用 APIs 来更新留言保留期或关闭留言保留期。如需了解有关配置消息保留的更多信息，请参阅 [Amazon Chime SDK API 参考](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/Welcome.html)。
## 恢复和删除消息
您可以在设置或更新消息保留期后 30 天内将消息还原给用户。但是，在该 30 天宽限期之后，保留期内的所有消息都将永久删除，新消息在保留期过后也会永久删除。
**注意**
在 30 天宽限期内，如果您延长保留策略期限或将其关闭，那么尚未超过新保留期的消息将再次对账户中的用户可见。
`AppInstanceUser` 删除频道或消息时，消息也会被永久删除。
# 用于 Amazon Chime SDK 消息传递的 UI 组件
您可以使用组件库来减少为聊天消息传递构建 UI 所需的工作量。有关更多信息，请参阅 [Amazon Chime React 组件库](https://github.com/aws/amazon-chime-sdk-component-library-react) GitHub 。
# 将 Amazon Chime SDK 消息传递与客户端库集成
要使用 Amazon Chime SDK 的消息传递功能，您必须将您的客户端应用程序与以下客户端库集成：
+ **AWS SDK**-包含 APIs 用于发送消息和管理资源。
+ 适用于 ** JavaScript (NPM) 的 Amazon Chime SDK 客户端库** — 一个包含 TypeScript 类型定义的 JavaScript 库，可帮助您将客户端与 Amazon Chime SDK 消息传送网络套接字集成以接收消息。
要将您的客户端应用程序与 Amazon Chime SDK 集成，请参阅客户端库 README.md 中的说明，并使用演示来学习如何构建消息传递功能。
# 将 Amazon Chime SDK 消息传递与 JavaScript
您可以使用 JavaScript 管理 Amazon Chime 软件开发工具包资源和发送消息。有关更多信息，请参阅 S [AWS JavaScript DK](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Chime.html)。
您还可以在客户端应用程序中创建消息传递会话，以接收来自 Amazon Chime SDK 消息传递的消息。有关更多信息，请参阅[使用上的 Amazon Chime 软件开发工具包客户端库。 JavaScript ](https://github.com/aws/amazon-chime-sdk-js/blob/master/README.md) GitHub