本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

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

使用者可以在與客服人員的 RCS 對話中傳送媒體 （影像、影片、音訊檔案和文件）。當您設定傳入媒體儲存時，AWS最終使用者傳訊會從 RCS 供應商下載媒體、將其上傳至 Amazon S3 儲存貯體，並使用 S3 位置和檔案中繼資料將通知發佈到您的雙向 Amazon SNS 主題。

如需接收傳入 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 代理程式上設定下列欄位。您必須先在代理程式上啟用雙向傳訊，才能設定媒體儲存。


**傳入媒體組態欄位**  

| 欄位 | 必要 | 描述 | 
| --- | --- | --- | 
| TwoWayMediaS3BucketName | 是 | AWS最終使用者傳訊存放傳入媒體檔案的 S3 儲存貯體名稱。 | 
| TwoWayMediaS3KeyPrefix | 否 | S3 物件金鑰的選用字首。如果指定，媒體物件會存放在儲存貯體中的此字首下。 | 
| TwoWayMediaS3Role | 是 | AWS最終使用者傳訊擔任的 IAM 角色 ARN，可將媒體檔案上傳至 S3 儲存貯體。 | 

需要 S3 儲存貯體和 IAM 角色。如果您指定一個，則必須同時指定兩者。

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

媒體物件會以下列金鑰格式存放，其中原始檔案名稱會附加在`#`分隔符號之後：

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

例如，如果您將金鑰字首設定為 `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>

下列 AWSCLI 命令會在現有的 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 主題。通知是具有 `messageBody` 欄位的 JSON 物件，其中包含具有媒體狀態的字串化 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 對話中傳送映像、影片或檔案，請務必設定媒體儲存。
+ 使用專用 S3 儲存貯體處理 RCS 傳入媒體，以隔離存取控制和生命週期政策。
+ 將 S3 生命週期政策設定為使舊媒體物件 （例如 90 天後） 過期，以管理儲存成本。
+ 使用由 SNS 主題觸發的 AWSLambda 函數，以非同步方式處理傳入媒體。
+ `s3:PutObject` 僅將 IAM 角色範圍限定為 。此服務不需要更廣泛的許可。
+ 監控 CloudWatch 指標是否有媒體上傳失敗，並設定警示以偵測組態問題。