本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 在 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"]
}
}
```