Firebase 云消息传递 HTTP 协议

本文档提供了通过 Firebase 云消息传递从您的应用服务器向客户端应用传递消息时所用到的 HTTP 语法的参考信息。您的应用服务器必须将所有 HTTP 请求定向到以下端点：

https://fcm.googleapis.com/fcm/send

可用的参数和选项分为以下几个大类：

• 下行消息语法
• 下行消息错误响应代码

下行消息语法

本部分将介绍发送下行消息和解读来自 Firebase 云消息传递的 HTTP 响应所使用的语法。

下行 HTTP 消息 (JSON)

下表列出了 HTTP JSON 消息的目标、选项和有效负载。

表 1. 下行 HTTP 消息 (JSON) 的目标、选项和有效负载。

参数	用法	说明
目标
to	可选，字符串	此参数用于指定消息的接收者。 值可以是设备的注册令牌、设备组的通知键或单个主题（前缀为 /topics/）。要发送到多个主题，请使用 condition 参数。
registration_ids	可选，字符串数组	此参数用于指定多播消息（发送到多个注册令牌的消息）的接收者。 值应该是向其发送多播消息的目标注册令牌数组。该数组必须包含至少 1 个、最多 1000 个注册令牌。要向单一设备发送消息，请使用 to 参数。 仅允许使用 HTTP JSON 格式进行多播消息传递。
condition	可选，字符串	此参数指定用于确定消息目标的逻辑条件表达式。 支持的条件：主题，格式为“'yourTopic' in topics”。此值不区分大小写。 支持的运算符：&&、||。每个主题消息最多支持两个运算符。
notification_key 已弃用	可选，字符串	此参数已被弃用。目前，应使用 to 来指定消息接收者。如需详细了解如何向多个设备发送消息，请参阅适用于您所用平台的文档。
选项
collapse_key	可选，字符串	此参数用于指定一组可折叠的消息（例如含有 collapse_key: "Updates Available"），因此当恢复传送时只有最后一条消息被送出。这是为了避免当设备重新上线或活动时重复发送过多相同的消息。 请注意，消息发送顺序并不固定。 注意：在任意给定时间最多允许 4 个不同的折叠键。这意味着 FCM 连接服务器可以为每个客户端应用同时存储 4 条不同的消息。如果超出此数量，FCM 连接服务器将无法保证会保留哪 4 个折叠键。
priority	可选，字符串	设置消息的优先级。有效值包括“normal”（普通）和“high”（高）。在 iOS 中，这些值相当于 APNs 优先级中的 5 级和 10 级。 默认情况下，通知消息以高优先级发送，数据消息以普通优先级发送。普通优先级可减轻客户端应用的电池消耗，除非需要立即传送，否则应使用普通优先级。对于普通优先级消息，应用可能会收到未指定延迟时间的消息。 当以高优先级发送消息时，消息会立即发送，应用可能会显示通知。
content_available	可选，布尔值	在 iOS 中，使用此字段表示 APNs 有效负载中的 content-available。如果发送通知或消息时此字段设为 true，将会唤醒处于非活动状态的客户端应用，且消息将作为静默通知通过 APNs 发送，而不是通过 FCM 连接服务器发送。请注意，APNs 中的静默通知不保证能传送，并且可能受多种因素影响（比如用户开启低电量模式、强制退出应用等）。在 Android 系统上，数据消息默认唤醒应用。Chrome 中目前不支持此功能。
mutable_content	可选，JSON 布尔值	目前仅适用于运行 iOS 10 及更高版本的设备。在 iOS 中，使用此字段表示 APNs 有效负载中的 mutable-content。如果发送通知时此字段设为 true，则可以使用通知服务附加应用信息功能在通知显示之前修改通知的内容。Android 应用和网页应用将忽略此参数。
time_to_live	可选，数字	此参数指定当设备离线时消息在 FCM 存储中保留的时长（以秒为单位）。受支持的最长生存时间为 4 周，默认值为 4 周。如需了解详情，请参阅设置消息的有效期。
restricted_package_ name（仅适用于 Android 应用）	可选，字符串	此参数用于指定应用的软件包名称，其注册令牌必须匹配才能接收消息。
dry_run	可选，布尔值	此参数设置为 true 时，开发者可在不实际发送消息的情况下对请求进行测试。 默认值为 false。
有效负载
data	可选，对象	此参数用于指定消息有效负载的自定义键值对。 例如，使用 data:{"score":"3x1"}: 在 iOS 中，如果通过 APNs 发送消息，该参数代表自定义数据字段。如果通过 FCM 连接服务器发送，则该参数将以 AppDelegate application:didReceiveRemoteNotification: 中的键值字典的形式来表示。 在 Android 中，这会导致产生名为 score、字符串值为 3x1 的 Intent 附加信息 (extra)。 键不能是保留的字词（“from”或任何以“google”或“gcm”开头的字词）。请勿使用此表中定义的任何字词（例如 collapse_key）。 推荐使用字符串类型中的值。您必须将对象中的值或其他非字符串数据类型（例如整数或布尔值）转换成字符串。
notification	可选，对象	此参数用于指定通知有效负载的用户可见的预定义键值对。如需了解详情，请参阅“通知有效负载支持”。如需详细了解通知消息和数据消息选项，请参阅消息类型。如果为发送到 iOS 设备的消息提供了通知有效负载，或者将 content_available 选项设为 true，消息将通过 APNs 发送，否则会通过 FCM 连接服务器发送。

通知有效负载支持

下方各表列出了 iOS 和 Android 中可用于构建通知消息的预定义键。

表 2a. iOS - 通知消息对应的键

参数	用法	说明
title	可选，字符串	通知的标题。 此字段不会在 iOS 手机和平板电脑上显示。
body	可选，字符串	通知的正文。
sound	可选，字符串或字典	设备收到通知时要播放的声音。 用于指定声音文件的字符串，该文件可以位于客户端应用的主软件包中，也可位于应用的数据容器的 Library/Sounds 文件夹中。如需了解详情，请参阅 iOS 开发者库。 对于重要通知，请使用包含关键提醒的声音信息的字典。要了解必需的键，请参阅 iOS 开发者库。对于常规通知，请改用声音字符串。
badge	可选，字符串	主屏幕应用图标上的标志值。 如果未指定该值，则标志不会发生更改。 如果该值设为 0，则会移除该标志。
click_action	可选，字符串	与用户点击通知相关的操作。 对应于 APNs 有效负载中的 category。
subtitle	可选，字符串	通知的副标题。
body_loc_key	可选，字符串	应用的字符串资源中正文字符串的键，用于将正文文字本地化为用户当前的本地化设置语言。 对应于 APNs 有效负载中的 loc-key。 如需了解详情，请参阅有效负载键参考和将远程通知的内容本地化。
body_loc_args	可选，字符串形式的 JSON 数组	将用于替换 body_loc_key（用来将正文文字本地化为用户当前的本地化设置语言）中的格式说明符的变量字符串值。 对应于 APNs 有效负载中的 loc-args。 如需了解详情，请参阅有效负载键参考和将远程通知的内容本地化。
title_loc_key	可选，字符串	应用的字符串资源中标题字符串的键，用于将标题文字本地化为用户当前的本地化设置语言。 对应于 APNs 有效负载中的 title-loc-key。 如需了解详情，请参阅有效负载键参考和将远程通知的内容本地化。
title_loc_args	可选，字符串形式的 JSON 数组	将用于替换 title_loc_key（用来将标题文字本地化为用户当前的本地化设置语言）中的格式说明符的变量字符串值。 对应于 APNs 有效负载中的 title-loc-args。 如需了解详情，请参阅有效负载键参考和将远程通知的内容本地化。

表 2b. Android - 通知消息对应的键

参数	用法	说明
title	可选，字符串	通知的标题。
body	可选，字符串	通知的正文。
android_channel_id	可选，字符串	通知的渠道 ID（Android O 中的新功能）。 应用必须使用此 ID 创建一个渠道，然后才能收到所有含有此渠道 ID 的通知。 如果您不在请求中发送此渠道 ID，或者如果应用尚未创建所提供的渠道 ID，则 FCM 将使用应用清单文件中指定的渠道 ID。
icon	可选，字符串	通知的图标。 将可绘制资源 myicon 的通知图标设置为 myicon。如果您不在请求中发送此键，则 FCM 将会显示您的应用清单文件中指定的启动器图标。
sound	可选，字符串	设备收到通知时要播放的声音。 可以使用 "default" 或应用中包含的声音资源的文件名。声音文件必须位于 /res/raw/ 中。
tag	可选，字符串	用于替换抽屉式通知栏中现有通知的标识符。 如果未指定此参数，每次请求时将创建一条新的通知。 如果已指定此参数，且已显示带有相同标记的通知，则新通知将替换抽屉式通知栏中的现有通知。
color	可选，字符串	通知的图标颜色，以 #rrggbb 格式来表示。
click_action	可选，字符串	与用户点击通知相关的操作。 如果已指定此参数，则当用户点击通知时，将会启动带有匹配 intent 过滤器的 Activity。
body_loc_key	可选，字符串	应用的字符串资源中正文字符串的键，用于将正文文字本地化为用户当前的本地化设置语言。 如需了解详情，请参阅字符串资源。
body_loc_args	可选，字符串形式的 JSON 数组	将用于替换 body_loc_key（用来将正文文字本地化为用户当前的本地化设置语言）中的格式说明符的变量字符串值。 如需了解详情，请参阅格式和样式设置。
title_loc_key	可选，字符串	应用的字符串资源中标题字符串的键，用于将标题文字本地化为用户当前的本地化设置语言。 如需了解详情，请参阅字符串资源。
title_loc_args	可选，字符串形式的 JSON 数组	将用于替换 title_loc_key（用来将标题文字本地化为用户当前的本地化设置语言）中的格式说明符的变量字符串值。 如需了解详情，请参阅格式和样式设置。

表 2c. Web (JavaScript) - 通知消息对应的键

参数	用法	说明
title	可选，字符串	通知的标题。
body	可选，字符串	通知的正文。
icon	可选，字符串	通知图标所对应的网址。
click_action	可选，字符串	与用户点击通知相关的操作。 所有网址值都需要采用 HTTPS。

下行 HTTP 消息（纯文本）

下表列出了纯文本下行 HTTP 消息的目标、选项和有效负载使用的语法。

表 3. 下行纯文本 HTTP 消息的目标、选项和有效负载。

参数	用法	说明
目标
registration_id	必选，字符串	此参数用于指定接收消息的客户端应用（注册 ID）。 仅允许使用 HTTP JSON 格式进行多播消息传递（发送至一个以上注册 ID）。
选项
collapse_key	可选，字符串	请参阅表 1 了解详情。
time_to_live	可选，数字	请参阅表 1 了解详情。
restricted_package_name	可选，字符串	请参阅表 1 了解详情。
dry_run	可选，布尔值	请参阅表 1 了解详情。
有效负载
data.<key>	可选，字符串	此参数用于指定消息有效负载的键值对。 键值参数没有数量限制，但是消息总大小不得超过 4kb。 例如，在 Android 中，"data.score"."3x1" 会导致产生名为 score、字符串值为 3x1 的 Intent 附加信息 (extra)。 键不能是保留的字词（“from”或任何以“google”或“gcm”开头的字词）。请勿使用此表中定义的任何字词（例如 collapse_key）。

解读下行消息响应

应用服务器应评估消息响应标头和正文以解读通过 FCM 发送的消息响应。下表介绍了可能的响应。

表 4. 下行 HTTP 消息响应标头。

响应	说明
200	消息处理成功。响应正文包含有关消息状态的更多详细信息，但其格式取决于请求是 JSON 格式还是纯文本格式。请参阅表 5 了解详情。
400	仅适用于 JSON 请求。 表示请求不能作为 JSON 进行解析，或者其中包含无效字段（例如，传递预计会有数字的字符串）。响应中会描述出现问题的确切原因，应先解决问题，之后方可重试请求。
401	验证发送者帐号身份时出错。
5xx	错误代码若在 500-599 范围之间（例如 500 或 503），表示在尝试处理请求时，FCM 连接服务器发生内部错误，或服务器暂时不可用（例如，由于超时原因）。发送者必须接受响应中的任何 Retry-After 标头，稍后重试。应用服务器必须实现指数退避。

下表列出了下行消息响应正文 (JSON) 中的字段。

表 5. 下行 HTTP 消息响应正文 (JSON)。

参数	用法	说明
multicast_id	必选，数字	用于识别多播消息的唯一 ID（数字）。
success	必选，数字	处理时未出错的消息数。
failure	必选，数字	无法处理的消息数。
results	必选，对象数组	代表已处理消息状态的对象数组。对象的排列顺序与请求相同（即对于请求中的每个注册 ID，其结果的列出顺序与响应中的索引顺序相同）。 message_id：字符串，用于指定每条成功处理的消息的唯一 ID。 registration_id：可选字符串，用于指定处理和接收消息的客户端应用的注册令牌。 error：字符串，用于指定处理收件人的消息时发生的错误。表 9 中列出了可能的值。

表 6. 主题消息 HTTP 响应正文 (JSON)。

参数	用法	说明
message_id	可选，数字	当 FCM 成功接收到请求并尝试传递至所有已订阅设备时的主题消息 ID。
error	可选，字符串	处理消息时发生的错误。 表 9 中列出了可能的值。

表 7. 下行 HTTP 消息响应正文（纯文本）的成功响应。

参数	用法	说明
id	必选，字符串	此参数用于指定 FCM 连接服务器成功处理的唯一消息 ID。
registration_id	可选，字符串	此参数用于指定处理和接收消息的客户端应用的注册令牌。

表 8. 下行 HTTP 消息响应正文（纯文本）的错误响应。

参数	用法	说明
Error	必选，字符串	此参数用于指定处理接收者消息时的错误值。请参阅表 9 了解详情。

下行消息错误响应代码

下表列出了下行消息的错误响应代码。

表 9. 下行消息错误响应代码。

错误	HTTP 代码	建议采取的操作
缺少注册令牌	200 + error:MissingRegistration	检查请求中是否包含一个注册令牌（在纯文本消息中的 registration_id 中，或在 JSON 中的 to 或 registration_ids 字段中）。
无效注册令牌	200 + error:InvalidRegistration	检查您传送至服务器的注册令牌格式。确保它与客户端应用在注册 Firebase 通知时获得的注册令牌匹配。不能截断或添加其他字符。
未注册设备	200 + error:NotRegistered	现有注册令牌可能在很多情况下失效，包括： 客户端应用撤消 FCM 注册。 客户端应用自动撤消注册（用户卸载应用时可能发生此情况）。例如，在 iOS 中，APNs 反馈服务报告称 APNs 令牌无效。 注册令牌过期（例如 Google 可能决定更新注册令牌，或 iOS 设备的 APNs 令牌已过期）。 客户端应用已更新，但新版本未配置为接收消息。 对于所有这些情况，请从应用服务器中移除此注册令牌，并停止用其发送消息。
无效的软件包名称	200 + error:InvalidPackageName	确保消息发送至软件包名称与请求中传递的值相匹配的注册令牌。
身份验证错误	401	无法对用于发送消息的发送者帐号进行身份验证。可能的原因如下： 身份验证标头缺失或 HTTP 请求中使用了无效的语法。 指定的服务器密钥所属的 Firebase 项目不正确。 仅限旧版服务器密钥 - 从服务器发出的请求不在服务器密钥 IP 白名单中。 检查您在身份验证标头内部发送的令牌是不是与您的项目关联的正确的服务器密钥。请参阅检查服务器密钥的有效性了解详情。如果您使用的是旧版服务器密钥，建议您升级到没有 IP 限制的新密钥。
发送者不匹配	200 + error:MismatchSenderId	一个注册令牌与一组特定的发送者关联。当客户端应用注册 FCM 时，必须指定允许哪些发送者发送消息。当向客户端应用发送消息时，您应使用这些发送者 ID 之一。如果您切换为其他发送者，将无法使用现有注册令牌。
JSON 无效	400	检查 JSON 消息是否格式正确以及包含有效字段（例如确保传入正确的数据类型）。
参数无效	400 + error:InvalidParameters	确保提供的参数具有正确的名称和类型。
消息过大	200 + error:MessageTooBig	确保消息中包含的有效负载数据的总大小不超过 FCM 的限制：大多数消息的上限是 4096 字节；如果是主题消息，则上限为 2048 字节。这包括键和值。
数据键无效	200 + error: InvalidDataKey	确保有效负载数据不包含 FCM 内部使用的密钥（例如 from、gcm，或任何以 google 为前缀的值）。请注意，有效负载中允许包含 FCM 也会使用的某些字词（例如 collapse_key），在这种情况下有效负载值将由 FCM 值覆盖。
无效的生存时间	200 + error:InvalidTtl	检查 time_to_live 中使用的值是否是代表 0 至 2419200 秒（4 周）之间的一段时间的整数值。
超时	5xx 或 200 + error:Unavailable	服务器无法及时处理请求。重试同一请求，但必须： 如果 Retry-After 标头包含在 FCM 连接服务器发出的响应中，则接受该标头。 在您的重试机制中实现指数退避（例如，如果等待一秒钟后进行第一次重试，则至少要等待两秒钟再进行下一次重试，然后等待四秒钟，依此类推）。如果您要发送多条消息，以额外随机时长单独地延迟每条消息，从而避免同时对所有消息发布新的请求。 导致出现问题风险的发送者将被列入黑名单。
内部服务器错误	500 或 200 + error:InternalServerError	服务器在尝试处理请求时遇到错误。您可按照“超时”中的要求重试同一请求（请参阅上一行）。如果错误仍然存在，请联系 Firebase 支持团队。
超出设备消息投递率	200 + error: DeviceMessageRate Exceeded	针对特定设备的消息投递率过高。如果 iOS 应用发送消息的速率超过 APNs 限制，就可能会收到此错误消息 请减少发送到此设备的消息数量，并使用指数退避重试发送。
超出主题消息投递率	200 + error: TopicsMessageRate Exceeded	针对特定主题订阅者的消息投递率过高。请减少针对此主题发送的消息数量，并使用指数退避重试发送。
APNs 凭据无效	200 + error: InvalidApnsCredential	因为所需的 APNs 身份验证密钥尚未上传或已过期，所以无法向 iOS 设备发送消息。请检查您的开发环境凭据和正式环境凭据是否有效。

设备组管理

下表列出了用于创建设备组以及添加和移除成员的键。如需了解详情，请参阅适用于您所用平台（iOS 或 Android）的指南。

表 10. 设备组管理对应的键。

参数	用法	说明
operation	必选，字符串	要执行的操作。有效值为 create、add 和 remove。
notification_key_name	必选，字符串	用户定义的要创建或修改的设备组的名称。
notification_key	必选（create 操作除外），字符串	设备组的唯一标识符。成功 create 操作的响应中会返回此值，设备组的所有后续操作也需要此值。
registration_ids	必选，字符串数组	要添加或移除的设备令牌。如果您移除了某个设备组中的所有现有注册令牌，那么 FCM 会删除该设备组。