기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 인바운드 RCS 미디어 수신
사용자는 에이전트와의 RCS 대화에서 미디어(이미지, 비디오, 오디오 파일 및 문서)를 보낼 수 있습니다. 인바운드 미디어 스토리지를 구성하면 AWSEnd User Messaging은 RCS 공급자에서 미디어를 다운로드하여 Amazon S3 버킷에 업로드하고 S3 위치 및 파일 메타데이터와 함께 양방향 Amazon SNS 주제에 알림을 게시합니다.
인바운드 RCS 메시지 수신에 대한 일반적인 정보(텍스트, 위치 및 제안 응답)는 섹션을 참조하세요[인바운드 RCS 메시지 수신](rcs-inbound.md). 사용자에게 리치 미디어를 보내는 방법에 대한 자세한 내용은 섹션을 참조하세요[리치 RCS 메시지 전송](rcs-rich-messaging.md).
## 인바운드 미디어 작동 방식
사용자가 RCS 대화에서 미디어 파일을 보내면AWSEnd User Messaging은 다음 단계를 통해 메시지를 처리합니다.
1. 사용자는 RCS 메시징 앱에서 이미지, 비디오, 오디오 파일 또는 문서를 전송합니다.
1. AWSEnd User Messaging은 RCS 공급자로부터 미디어를 다운로드합니다.
1. AWSEnd User Messaging은 지정한 IAM 역할을 사용하여 구성된 S3 버킷에 미디어를 업로드합니다.
1. AWSEnd User Messaging은 양방향 SNS 주제에 알림을 게시합니다. 알림에는 S3 버킷, 키, MIME 유형 및 메시지 메타데이터가 포함됩니다.
`LOCATION` 및 `SUGGESTION` 메시지 유형의 경우 S3 업로드가 수행되지 않습니다. 콘텐츠는 SNS 알림 본문에 직접 전달됩니다. 이러한 메시지 유형에 대한 자세한 내용은 섹션을 참조하세요[인바운드 RCS 메시지 수신](rcs-inbound.md).
## 인바운드 미디어 스토리지 구성
인바운드 미디어를 수신하려면 `UpdateRcsAgent` API를 사용하여 RCS 에이전트에서 다음 필드를 구성합니다. 미디어 스토리지를 구성하기 전에 에이전트에서 양방향 메시징을 활성화해야 합니다.
**인바운드 미디어 구성 필드**
| Field | 필수 | 설명 |
| --- | --- | --- |
| TwoWayMediaS3BucketName | 예 | AWSEnd User Messaging이 인바운드 미디어 파일을 저장하는 S3 버킷의 이름입니다. |
| TwoWayMediaS3KeyPrefix | 아니요 | S3 객체 키의 선택적 접두사입니다. 지정된 경우 미디어 객체는 버킷의이 접두사 아래에 저장됩니다. |
| TwoWayMediaS3Role | 예 | AWSEnd User Messaging이 S3 버킷에 미디어 파일을 업로드하기 위해 수임하는 IAM 역할의 ARN입니다. |
S3 버킷과 IAM 역할이 함께 필요합니다. 하나를 지정하는 경우 둘 다 지정해야 합니다.
### S3 키 형식
미디어 객체는 다음 키 형식으로 저장됩니다. 여기서 원래 파일 이름은 `#` 구분자 뒤에 추가됩니다.
```
{prefix}/rcs/{messageId}#{fileName}
```
예를 들어 키 접두사를 로 설정하면 `inbound-media`미디어 파일이 다음과 같이 저장될 수 있습니다.
```
inbound-media/rcs/msg-abc123def456#photo_2026.jpg
```
## 인바운드 미디어에 대한 IAM 역할 생성
AWSEnd User Messaging 서비스가 미디어 파일을 S3 버킷에 업로드할 수 있도록 허용하는 IAM 역할을 생성합니다. 역할에는 서비스가 이를 수임하도록 허용하는 신뢰 정책과 버킷에 `s3:PutObject` 대한 액세스 권한을 부여하는 권한 정책이 필요합니다.
### 신뢰 정책
다음 신뢰 정책은 AWSEnd User Messaging 서비스 보안 주체가 역할을 수임하도록 허용합니다. 를 AWS계정 ID`123456789012`로 바꿉니다.
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "sms-voice.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "123456789012"
}
}
}
]
}
```
### 권한 정책
다음 권한 정책은 역할에 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)
다음 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
```
## 인바운드 미디어 알림 페이로드
AWSEnd User Messaging은 미디어 파일을 수신하면 양방향 SNS 주제에 알림을 게시합니다. 알림은 미디어 상태와 성공 시 S3 위치 및 파일 메타데이터가 있는 문자열화된 JSON 문서가 포함된 `messageBody` 필드가 있는 JSON 객체입니다.
다음 예제에서는 성공적인 인바운드 미디어 알림을 보여줍니다.
```
{
"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`를 사용하여 결과를 결정합니다.
## 미디어 다운로드 실패 처리
AWSEnd User Messaging이 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 지표를 모니터링합니다.
## 허용되는 미디어 유형
AWSEnd User Messaging은 다음과 같은 인바운드 미디어 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`
**참고**
AWSEnd User Messaging은 인바운드 미디어에 크기 제한을 부과하지 않습니다.
## 모범 사례
+ 사용자가 RCS 대화에서 이미지, 비디오 또는 파일을 보낼 것으로 예상되는 경우 항상 미디어 스토리지를 구성합니다.
+ RCS 인바운드 미디어용 전용 S3 버킷을 사용하여 액세스 제어 및 수명 주기 정책을 격리합니다.
+ 스토리지 비용을 관리하기 위해 이전 미디어 객체를 만료(예: 90일 후)하도록 S3 수명 주기 정책을 설정합니다.
+ SNS 주제에 의해 트리거된 AWSLambda 함수를 사용하여 인바운드 미디어를 비동기적으로 처리합니다.
+ IAM 역할의 범위를 로`s3:PutObject`만 지정합니다. 이 서비스에는 더 광범위한 권한이 필요하지 않습니다.
+ CloudWatch 지표에서 미디어 업로드 실패를 모니터링하고 경보를 설정하여 구성 문제를 감지합니다.