기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# Amazon SNS에서 Google Firebase Cloud Messaging v1 페이로드 사용
Amazon SNS는 FCM HTTP v1 API를 사용하여 Android, iOS 및 Webpush 대상으로 알림을 보낼 수 있도록 지원합니다. 이 주제에서는 CLI 또는 Amazon SNS API를 사용하여 모바일 푸시 알림을 게시할 때 페이로드 구조의 예를 제공합니다.
FCM 알림을 보낼 때 페이로드에 다음 메시지 유형을 포함할 수 있습니다.
+ **데이터 메시지** - 데이터 메시지는 클라이언트 앱에서 처리되며 사용자 지정 키-값 페어를 포함합니다. 데이터 메시지를 구성할 때 JSON 객체가 있는 `data` 키를 값으로 포함시킨 다음 사용자 지정 키-값 페어를 입력해야 합니다.
+ **알림 메시지** 또는 **표시 메시지** - 알림 메시지에는 FCM SDK에서 처리하는 미리 정의된 키 세트가 포함되어 있습니다. 이러한 키는 전송하려는 디바이스 유형에 따라 다릅니다. 플랫폼별 알림 키에 대한 자세한 내용은 다음을 참조하세요.
+ [Android 알림 키](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages)
+ [APNS 알림 키](https://developer.apple.com/documentation/usernotifications/generating-a-remote-notification)
+ [Webpush 알림 키](https://developer.mozilla.org/en-US/docs/Web/API/Notification)
FCM 메시지 유형에 대한 자세한 내용은 Google *Firebase* 설명서의 에서 [메시지 유형](https://firebase.google.com/docs/cloud-messaging/concept-options#notifications_and_data_messages)을 참조하세요.
## FCM v1 페이로드 구조를 사용하여 메시지 전송
FCM 애플리케이션을 처음 생성하거나 FCM v1 기능을 활용하려는 경우 FCM v1 형식의 페이로드를 전송하도록 선택할 수 있습니다. 이렇게 하려면 최상위 키 `fcmV1Message`를 포함해야 합니다. FCM v1 페이로드 구성에 대한 자세한 내용은 Google *Firebase* 설명서의 [레거시 FCM APIs에서 HTTP v1로 마이그레이션](https://firebase.google.com/docs/cloud-messaging/migrate-v1) 및 [플랫폼 간에 메시지 사용자 지정](https://firebase.google.com/docs/cloud-messaging/concept-options#customizing-a-message-across-platforms)을 참조하세요.
**Amazon SNS페이로드:**
**참고**
다음 예제에서 사용되는 `GCM` 키 값은 Amazon SNS 를 사용하여 알림을 게시할 때 문자열로 인코딩되어야 합니다.
```
{
"GCM": "{
\"fcmV1Message\": {
\"validate_only\": false,
\"message\": {
\"notification\": {
\"title\": \"string\",
\"body\": \"string\"
},
\"data\": {
\"dataGen\": \"priority message\"
},
\"android\": {
\"priority\": \"high\",
\"notification\": {
\"body_loc_args\": [\"string\"],
\"title_loc_args\": [\"string\"],
\"sound\": \"string\",
\"title_loc_key\": \"string\",
\"title\": \"string\",
\"body\": \"string\",
\"click_action\": \"clicky_clacky\",
\"body_loc_key\": \"string\"
},
\"data\": {
\"dataAndroid\": \"priority message\"
},
\"ttl\": \"10023.32s\"
},
\"apns\": {
\"payload\": {
\"aps\": {
\"alert\": {
\"subtitle\": \"string\",
\"title-loc-args\": [\"string\"],
\"title-loc-key\": \"string\",
\"loc-args\": [\"string\"],
\"loc-key\": \"string\",
\"title\": \"string\",
\"body\": \"string\"
},
\"category\": \"Click\",
\"content-available\": 0,
\"sound\": \"string\",
\"badge\": 5
}
}
},
\"webpush\": {
\"notification\": {
\"badge\": \"5\",
\"title\": \"string\",
\"body\": \"string\"
},
\"data\": {
\"dataWeb\": \"priority message\"
}
}
}
}
}"
}
```
JSON 페이로드를 전송할 때는 요청에 `message-structure` 속성을 포함시키고 `json`으로 설정해야 합니다.
**CLI 예제:**
```
aws sns publish --topic $TOPIC_ARN --message '{"GCM": "{\"fcmV1Message\": {\"message\":{\"notification\":{\"title\":\"string\",\"body\":\"string\"},\"android\":{\"priority\":\"high\",\"notification\":{\"title\":\"string\",\"body\":\"string\"},\"data\":{\"customAndroidDataKey\":\"custom key value\"},\"ttl\":\"0s\"},\"apns\":{\"payload\":{\"aps\":{\"alert\":{\"title\":\"string\", \"body\":\"string\"},\"content-available\":1,\"badge\":5}}},\"webpush\":{\"notification\":{\"badge\":\"URL\",\"body\":\"Test\"},\"data\":{\"customWebpushDataKey\":\"priority message\"}},\"data\":{\"customGeneralDataKey\":\"priority message\"}}}}", "default": "{\"notification\": {\"title\": \"test\"}"}' --region $REGION --message-structure json
```
FCM v1 형식의 페이로드를 보내는 방법에 대한 자세한 내용은 Google의 *Firebase* 설명서에서 다음을 참조하세요.
+ [레거시 FCM APIs에서 HTTP v1로 마이그레이션](https://firebase.google.com/docs/cloud-messaging/migrate-v1)
+ [FCM 메시지 정보](https://firebase.google.com/docs/cloud-messaging/concept-options#customizing_a_message_across_platforms)
+ [REST 리소스: projects.messages](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages)
## 레거시 페이로드 구조를 사용하여 FCM v1 API로 메시지 전송
FCM v1로 마이그레이션할 때 레거시 자격 증명에 사용하던 페이로드 구조를 변경할 필요가 없습니다. Amazon SNS는 페이로드를 새 FCM v1 페이로드 구조로 변환하고 Google로 전송합니다.
입력 메시지 페이로드 형식:
```
{
"GCM": "{\"notification\": {\"title\": \"string\", \"body\": \"string\", \"android_channel_id\": \"string\", \"body_loc_args\": [\"string\"], \"body_loc_key\": \"string\", \"click_action\": \"string\", \"color\": \"string\", \"icon\": \"string\", \"sound\": \"string\", \"tag\": \"string\", \"title_loc_args\": [\"string\"], \"title_loc_key\": \"string\"}, \"data\": {\"message\": \"priority message\"}}"
}
```
Google로 전송된 메시지:
```
{
"message": {
"token": "***",
"notification": {
"title": "string",
"body": "string"
},
"android": {
"priority": "high",
"notification": {
"body_loc_args": [
"string"
],
"title_loc_args": [
"string"
],
"color": "string",
"sound": "string",
"icon": "string",
"tag": "string",
"title_loc_key": "string",
"title": "string",
"body": "string",
"click_action": "string",
"channel_id": "string",
"body_loc_key": "string"
},
"data": {
"message": "priority message"
}
},
"apns": {
"payload": {
"aps": {
"alert": {
"title-loc-args": [
"string"
],
"title-loc-key": "string",
"loc-args": [
"string"
],
"loc-key": "string",
"title": "string",
"body": "string"
},
"category": "string",
"sound": "string"
}
}
},
"webpush": {
"notification": {
"icon": "string",
"tag": "string",
"body": "string",
"title": "string"
},
"data": {
"message": "priority message"
}
},
"data": {
"message": "priority message"
}
}
}
```
**잠재적 위험**
+ 레거시 대 v1 매핑은 Apple Push Notification Service(APNS) `headers` 또는 `fcm_options` 키를 지원하지 않습니다. 이러한 필드를 사용하려면 FCM v1 페이로드를 전송합니다.
+ 경우에 따라 FCM v1에서 메시지 헤더를 사용하여 APNs 디바이스에 자동 알림을 보내야 합니다. 현재 APN 디바이스에 자동 알림을 보내는 경우 레거시 접근 방식에서는 작동하지 않습니다. 대신 예상치 못한 문제를 방지하려면 FCM v1 페이로드를 사용하는 것이 좋습니다. APN 헤더 목록과 헤더의 용도를 찾으려면 *Apple 개발자 안내서*의 [ APNs과의 통신을 참조하세요](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CommunicatingwithAPNs.html).
+ 알림을 보낼 때 `TTL` Amazon SNS 속성을 사용하는 경우 `android` 필드에서만 업데이트됩니다. `TTL` APNS 속성을 설정하려면 FCM v1 페이로드를 사용합니다.
+ `android`, `apns` 및 `webpush` 키는 제공된 모든 관련 키로 매핑되고 채워집니다. 예를 들어 세 플랫폼 모두에서 공유하는 키인 `title`을 제공하는 경우 FCM v1 매핑은 세 플랫폼 모두에 입력한 제목을 채웁니다.
+ 플랫폼 간에 공유되는 일부 키는 다양한 값 유형을 기대합니다. 예를 들어 에 전달된 `badge` 키는 정수 값을 `apns` 예상하는 반면 `webpush`에 전달된 `badge` 키는 문자열 값을 예상합니다. `badge` 키를 제공하는 경우 FCM v1 매핑은 유효한 값을 제공한 키만 채웁니다.
## FCM 전송 실패 이벤트
다음 표는 FCM v1 알림 요청에 대해 Google에서 수신한 오류/상태 코드에 해당하는 Amazon SNS 실패 유형을 제공합니다. 애플리케이션에 대한 [전송 상태 로깅](topics-attrib.md)을 설정할 때 FCM v1 API에서 수신한 모든 관찰된 오류 코드를 CloudWatch에서 사용할 수 있습니다.
| FCM 오류/상태 코드 | Amazon SNS 장애 유형 | 오류 메시지 | 원인 및 완화 |
| --- | --- | --- | --- |
| `UNREGISTERED` | `InvalidPlatformToken` | 엔드포인트와 연결된 플랫폼 토큰이 유효하지 않습니다. | 엔드포인트에 연결된 디바이스 토큰이 오래되었거나 유효하지 않습니다. Amazon SNS가 엔드포인트를 비활성화했습니다. Amazon SNS 엔드포인트를 최신 디바이스 토큰으로 업데이트합니다. |
| `INVALID_ARGUMENT` | `InvalidNotification` | 알림 본문이 유효하지 않습니다. | 디바이스 토큰 또는 메시지 페이로드가 유효하지 않을 수 있습니다. 메시지 페이로드가 유효한지 확인합니다. 메시지 페이로드가 유효한 경우 Amazon SNS 엔드포인트를 최신 디바이스 토큰으로 업데이트합니다. |
| `SENDER_ID_MISMATCH` | `InvalidPlatformToken` | 엔드포인트와 연결된 플랫폼 토큰이 유효하지 않습니다. | 디바이스 토큰과 연결된 플랫폼 애플리케이션에는 디바이스 토큰으로 전송할 권한이 없습니다. Amazon SNS 플랫폼 애플리케이션에서 올바른 FCM 자격 증명을 사용하고 있는지 확인합니다. |
| `UNAVAILABLE` | `DependencyUnavailable` | 종속성을 사용할 수 없습니다. | FCM에서 요청을 처리할 수 없습니다. Amazon SNS에서 실행한 모든 재시도가 실패했습니다. 이러한 메시지를 DLQ(Dad-Letter Queue)에 저장하고 나중에 다시 구동할 수 있습니다. |
| `INTERNAL` | `UnexpectedFailure` | 예기치 않은 실패. Amazon에 문의하세요. 실패 문구 [내부 오류]. | 요청을 처리하는 도중 FCM 서버에서 오류가 발생하였습니다. Amazon SNS에서 실행한 모든 재시도가 실패했습니다. 이러한 메시지를 Dead Letter Queue(DLQ)에 저장하고 나중에 다시 구동할 수 있습니다. |
| `THIRD_PARTY_AUTH_ERROR` | `InvalidCredentials` | 플랫폼 애플리케이션 자격 증명이 유효하지 않습니다. | iOS 디바이스 또는 Webpush 디바이스를 대상으로 하는 메시지를 전송할 수 없습니다. 개발 및 프로덕션 자격 증명이 유효한지 확인합니다. |
| `QUOTA_EXCEEDED` | `Throttled` | [gcm]로 제한되는 요청입니다. | 메시지 속도 할당량, 디바이스 메시지 속도 할당량 또는 주제 메시지 속도 할당량을 초과했습니다. 이 문제를 해결하는 방법에 대한 자세한 내용은 Google *Firebase* 설명서의 에서 [ErrorCode](https://firebase.google.com/docs/reference/fcm/rest/v1/ErrorCode)를 참조하세요. |
| `PERMISSION_DENIED` | `InvalidNotification` | 알림 본문이 유효하지 않습니다. | `PERMISSION_DENIED` 예외의 경우 호출자(FCM 애플리케이션)는 페이로드에서 지정된 작업을 실행할 권한이 없습니다. FCM 콘솔로 이동하여 자격 증명에 필요한 API 작업이 활성화되어 있는지 확인합니다. |