向设备组发送消息 (Web/JavaScript)

利用设备组消息传递功能，您可以向单个设备组添加多台设备。 这类似于主题 (topic) 消息传递，但设备组消息传递加入了身份验证，以确保组成员资格仅受您的服务器管理。例如，如果要向不同的手机型号发送不同的消息，您的服务器可以向相应的设备组添加或从中移除注册信息，并将相应的消息发送到每个设备组。设备组消息传递与主题消息传递的不同之处在于：设备组消息传递是从服务器上管理设备组，而不是直接在应用中管理。

一个通知键最多支持 20 个成员设备。

管理设备组

向设备组发送消息之前，您必须：

  1. 为想要添加到该组的每一台设备获取注册令牌 (registration token)。

  2. 创建 notification_key。它用于将某个组（通常对应一名用户）映射到该组的所有关联注册令牌，以此来标识设备组。您可以在应用服务器上创建通知键。

设备组基本管理操作（创建和移除组，以及添加或移除设备）通过 HTTP v1 API 执行，使用短期令牌授权发送请求。 如需查看受支持的键的列表，请参阅设备组管理对应的键。

在应用服务器上管理设备组

创建设备组

如需创建设备组，需要发送一个 POST 请求，并在其中提供组名称及组中所含设备的注册令牌列表。 FCM 会返回一个代表该设备组的新 notification_key。

HTTP POST 请求

发送如下请求至 https://fcm.googleapis.com/fcm/notification： 

https://fcm.googleapis.com/fcm/notification
Content-Type:application/json
access_token_auth: true
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
project_id:SENDER_ID

{
   "operation": "create",
   "notification_key_name": "appUser-Chris",
   "registration_ids": ["bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
                        "cR1rjyj4_Kc:APA91bGusqbypSuMdsh7jSNrW4nzsM...",
                        ... ]

notification_key_name 是特定于设备组的唯一名称或标识符（例如，可以是用户名）。每组注册令牌的 notification_key_name 和 notification_key 都是唯一的。如果您的多个客户端应用的发送者 ID 都相同，则这些客户端应用的 notification_key_name 必须各不相同。这样可以确保消息只会发送到既定的目标应用。

响应格式

如果请求成功，将返回如下所示的 notification_key：

{
   "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}

请保存此 notification_key 和对应的 notification_key_name，以便在后续操作中使用。

检索通知键

如果您需要检索现有的通知键，可在 GET 请求中使用 notification_key_name，如下所示：

https://fcm.googleapis.com/fcm/notification?notification_key_name=appUser-Chris
Content-Type:application/json
access_token_auth: true
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
project_id:SENDER_ID
{}

对于指定通知键名的每个 GET 请求，服务器都会返回一个独一无二的编码字符串。尽管每个字符串可能看起来像是不同的键，但它实际上是一个有效的“notification_key”值。

向设备组中添加设备及从中移除设备

如需向现有设备组中添加设备或从中移除设备，需要发送一个 operation 参数设为 add 或 remove 的 POST 请求，并提供要添加或移除的设备对应的注册令牌。

HTTP POST 请求

例如，如需将注册令牌为 bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1... 的设备添加到 appUser-Chris，您需要发送此请求：

{
   "operation": "add",
   "notification_key_name": "appUser-Chris",
   "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ",
   "registration_ids": ["bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."]
}

响应格式

如果添加或移除设备的请求成功，将返回如下所示的 notification_key：

{
   "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}

设备组管理对应的键

下表列出了用于创建设备组以及添加和移除成员的键。

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

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

向设备组发送下行消息

如需向设备组发送消息，请使用 HTTP v1 API。如果您目前使用已弃用的适用于 HTTP 或 XMPP 的旧版发送 API，或者使用基于旧版协议的任何更低版本的 Firebase Admin SDK for Node.js 向设备组发送消息，我们强烈建议您尽早迁移到 HTTP v1 API。旧版发送 API 将于 2024 年 6 月停用并移除。

向设备组发送消息的过程与向单台设备发送消息十分类似，都使用相同的方法来授权发送请求。将 token 字段设置为组通知键：

REST

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

{
   "message":{
      "token":"APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ",
      "data":{
        "hello": "This is a Firebase Cloud Messaging device group message!"
      }
   }
}

cURL 命令

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message":{
   "data":{
     "hello": "This is a Firebase Cloud Messaging device group message!"
   },
   "token":"APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send