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

# 接收入站 RCS 媒体
<a name="rcs-inbound-media"></a>

用户可以在与您的代理的 RCS 对话中发送媒体（图像、视频、音频文件和文档）。配置入站媒体存储时，“AWS最终用户消息” 会从 RCS 提供商处下载媒体，将其上传到您的 Amazon S3 存储桶，然后向您的双向 Amazon SNS 主题发布一条包含 S3 位置和文件元数据的通知。

有关接收入站 RCS 消息（文本、位置和建议回复）的一般信息，请参阅[接收入站 RCS 消息](rcs-inbound.md)。有关向用户发送富媒体的信息，请参阅[发送丰富的 RCS 消息](rcs-rich-messaging.md)。

## 入站媒体的工作原理
<a name="rcs-inbound-media-how-it-works"></a>

当用户在 RCS 对话中发送媒体文件时，“AWS最终用户消息” 将通过以下步骤处理该消息：

1. 用户从其 RCS 消息应用程序发送图像、视频、音频文件或文档。

1. AWS最终用户消息从 RCS 提供商处下载媒体。

1. AWS最终用户消息使用您指定的 IAM 角色将媒体上传到您配置的 S3 存储桶。

1. AWS“最终用户消息” 会向您的双向 SNS 主题发布通知。通知包括 S3 存储桶、密钥、MIME 类型和消息元数据。

对于`LOCATION`和`SUGGESTION`消息类型，不会进行 S3 上传。内容直接在 SNS 通知正文中传送。有关这些消息类型的详细信息，请参阅[接收入站 RCS 消息](rcs-inbound.md)。

## 配置入站媒体存储
<a name="rcs-inbound-media-config"></a>

要接收入站媒体，请使用 `UpdateRcsAgent` API 在 RCS 代理上配置以下字段。 Two-way 在配置媒体存储之前，必须在代理上启用消息传递。


**入站媒体配置字段**  

| 字段 | 必填 | 描述 | 
| --- | --- | --- | 
| TwoWayMediaS3BucketName | 是 | AWS最终用户消息存储入站媒体文件的 S3 存储桶的名称。 | 
| TwoWayMediaS3KeyPrefix | 否 | S3 对象密钥的可选前缀。如果指定，则媒体对象将以此前缀存储在存储桶中。 | 
| TwoWayMediaS3Role | 是 | AWS最终用户消息传递将媒体文件上传到您的 S3 存储桶的 IAM 角色的 ARN。 | 

S3 存储桶和 IAM 角色是必需的。如果指定一个，则必须同时指定两个。

### S3 密钥格式
<a name="rcs-inbound-media-s3-key-format"></a>

媒体对象采用以下密钥格式存储，其中原始文件名附加在`#`分隔符之后：

```
{prefix}/rcs/{messageId}#{fileName}
```

例如，如果您将 key prefix 设置为`inbound-media`，则媒体文件可能会存储为：

```
inbound-media/rcs/msg-abc123def456#photo_2026.jpg
```

## 为入站媒体创建 IAM 角色
<a name="rcs-inbound-media-iam-role"></a>

创建一个 IAM 角色以允许AWS最终用户消息服务将媒体文件上传到您的 S3 存储桶。该角色需要一个允许服务担任该角色的信任策略和一个允许`s3:PutObject`访问您的存储桶的权限策略。

### 信任策略
<a name="rcs-inbound-media-trust-policy"></a>

以下信任策略允许AWS最终用户消息服务主体担任该角色。`123456789012`替换为您的AWS账户 ID。

```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "sms-voice.amazonaws.com"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "123456789012"
                }
            }
        }
    ]
}
```

### 权限策略
<a name="rcs-inbound-media-permission-policy"></a>

以下权限策略授予角色向您的 S3 存储桶写入对象的访问权限。将 `my-rcs-media-bucket`替换为存储桶名称。

```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject"
            ],
            "Resource": "arn:aws:s3:::my-rcs-media-bucket/*"
        }
    ]
}
```

**注意**  
将 IAM 角色范围缩小到仅限。`s3:PutObject`该服务不需要`s3:GetObject``s3:DeleteObject`、或其他权限即可进行入站媒体投放。

## 配置媒体存储 (CLI)
<a name="rcs-inbound-media-cli-example"></a>

以下 AWS CLI 命令在现有 RCS 代理上配置入站媒体存储：

```
aws pinpoint-sms-voice-v2 update-rcs-agent \
    --rcs-agent-id rcs-agent-1234567890abcdef0 \
    --two-way-media-s3-bucket-name my-rcs-media-bucket \
    --two-way-media-s3-key-prefix "inbound-media" \
    --two-way-media-s3-role arn:aws:iam::123456789012:role/RcsInboundMediaRole \
    --region us-east-1
```

## 入站媒体通知有效负载
<a name="rcs-inbound-media-notification"></a>

当AWS最终用户消息收到媒体文件时，它会向您的双向 SNS 主题发布通知。通知是一个 JSON 对象，其`messageBody`字段包含字符串化的 JSON 文档，其中包含媒体状态以及成功后的 S3 位置和文件元数据。

以下示例显示了成功的入站媒体通知：

```
{
    "originationNumber": "+14255551234",
    "destinationNumber": "rcs-cb1e6e519e9049fabf8c0ae38e4d876b",
    "messageBody": "{\"mediaStatus\":\"SUCCESS\",\"s3Bucket\":\"my-rcs-media-bucket\",\"s3Key\":\"inbound-media/rcs/msg-abc123def456#photo_2026.jpg\",\"mimeType\":\"image/jpeg\",\"fileName\":\"photo_2026.jpg\",\"fileSizeBytes\":1211843}",
    "inboundMessageId": "8821d750-4bc5-4cb1-a8c3-c3d64a38d019"
}
```

顶级通知包含以下字段：

`originationNumber`  
发送媒体的用户的电话号码。

`destinationNumber`  
收到消息的 RCS 代理标识符。

`messageBody`  
描述媒体的字符串化 JSON 文档。它包含下表中的字段。

`inboundMessageId`  
入站消息的唯一标识符。

`messageBody`JSON 包含以下字段：

`mediaStatus`  
媒体处理的结果。有效值包括 `SUCCESS`、`UPLOAD_FAILED` 和 `ROLE_ASSUME_FAILED`。

`mediaStatusMessage`  
人类可读的状态描述。何时出现`mediaStatus`是失效值。

`s3Bucket`  
存储媒体文件的 S3 存储桶的名称。成功时呈现。

`s3Key`  
存储的媒体文件的 S3 对象密钥。成功时呈现。

`mimeType`  
媒体文件的 MIME 类型（例如、`image/jpeg``video/mp4`、`application/pdf`）。

`fileName`  
用户设备提供的原始文件名。

`fileSizeBytes`  
媒体文件的大小（以字节为单位）。

**注意**  
入站媒体通知目前不包含消息类型字段。`mediaStatus`用于确定结果。

## 媒体下载失败处理
<a name="rcs-inbound-media-failure-handling"></a>

如果AWS最终用户消息无法从 RCS 提供商处下载或存储媒体，则该服务仍会向您的双向 SNS 主题发布通知。`messageBody`带有失败`mediaStatus`（`UPLOAD_FAILED`或`ROLE_ASSUME_FAILED`）和`mediaStatusMessage`描述原因的，没有 S3 位置字段。

例如，IAM 角色假设失败会生成以下`messageBody`内容：

```
{
    "mediaStatus": "ROLE_ASSUME_FAILED",
    "mediaStatusMessage": "Media received but could not assume the configured IAM role",
    "mimeType": "image/heic",
    "fileName": "IMG_7115.heic",
    "fileSizeBytes": 1211843
}
```

媒体下载失败的常见原因包括：
+ RCS 提供商不再提供该媒体（例如，媒体已过期或已删除）。
+ IAM 角色无权写入指定的 S3 存储桶。
+ S3 存储桶不存在或位于与预期不同的区域。

要对交付失败进行故障排除，请验证您的 IAM 角色信任和权限策略是否配置正确，以及 S3 存储桶是否存在且可通过服务进行访问。监控代理的媒体上传失败 CloudWatch 指标。

## 可接受的媒体类型
<a name="rcs-inbound-media-filtering"></a>

AWS最终用户消息接受以下入站媒体 MIME 类型：
+ **图片:**`image/jpeg`,`image/jpg`,`image/gif`, `image/png` 
+ **音频：**`audio/aac``audio/mp3`、`audio/mpeg`、`audio/mpg`、`audio/mp4`、`audio/mp4-latm`、`audio/3gpp`、`audio/ogg`、`application/ogg`
+ **视频：**`video/h263``video/m4v`、`video/mp4`、`video/mpeg`、`video/mpeg4`、`video/webm`
+ **文档：**`application/pdf`

**注意**  
AWS最终用户消息不对入站媒体施加大小限制。

## 最佳实践
<a name="rcs-inbound-media-best-practices"></a>
+ 如果您希望用户在 RCS 对话中发送图像、视频或文件，请务必配置媒体存储。
+ 使用 RCS 入站媒体的专用 S3 存储桶来隔离访问控制和生命周期策略。
+ 将 S3 生命周期策略设置为使旧媒体对象过期（例如，90 天后），以管理存储成本。
+ 使用由您的 SNS 主题触发的 Lamb AWS da 函数异步处理入站媒体。
+ 将 IAM 角色的范围`s3:PutObject`限定为仅限。该服务不需要更广泛的权限。
+ 监控媒体上传失败的 CloudWatch 指标，并设置警报以检测配置问题。