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

# 在 Amazon SNS 中使用 Google Firebase Cloud Messaging v1 承載
<a name="sns-fcm-v1-payloads"></a>

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 承載結構傳送訊息
<a name="sending-messages-using-v1-payload"></a>

如果您是第一次建立 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 的 FCM v1 範例承載：**

**注意**  
使用 Amazon SNS 發佈通知時，下列範例中使用的`GCM`金鑰值必須編碼為字串。

```
{
  "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
<a name="sns-fcm-v1-legacy-payload-structure"></a>

遷移至 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 裝置。如果您目前正在將無提示通知傳送至 APNs 裝置，則它們將無法與舊版方法搭配使用。反之，我們建議您使用 FCM v1 承載，以避免非預期的問題。若要尋找 APNs 標頭及其用途的清單，請參閱 *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`預期整數值，而傳遞給 的`badge`金鑰`webpush`預期字串值。如果您提供`badge`金鑰，FCM v1 映射只會填入您提供有效值的金鑰。

## FCM 交付失敗事件
<a name="sns-fcm-delivery-failure-events"></a>

下表提供對應於從 Google for FCM v1 通知請求收到的錯誤/狀態碼的 Amazon SNS 失敗類型。當您設定應用程式的[交付狀態記錄](topics-attrib.md)時，您可以在 CloudWatch 中使用從 FCM v1 API 收到的所有觀察到的錯誤代碼。


| 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) 中，稍後再重新驅動。  | 
|  `INTERNAL`  |  `UnexpectedFailure`  |  意外失敗；請聯絡 Amazon。失敗片語 【內部錯誤】。  |  FCM 伺服器在嘗試處理您的請求時發生錯誤。Amazon SNS 執行的所有重試都失敗。您可以將這些訊息存放在無效字母佇列 (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 動作。  |