使用 C++ 傳送訊息至裝置群組

裝置群組訊息功能可讓您將多部裝置加入單一群組。 這類似於主題訊息,但包含驗證機制,可確保只有您的伺服器管理群組成員資格。舉例來說 傳送不同的訊息至不同的手機型號,您的伺服器可新增或移除 註冊適當的群組,並向每個群組傳送適當的訊息 群組。裝置群組訊息與主題訊息不同, 從伺服器管理裝置群組,而不是直接在機構內部 應用程式。

通知鍵的會員數量上限為 20。

管理裝置群組

傳送訊息給裝置群組前,您必須:

  1. 為要新增的每部裝置取得註冊權杖 群組。

  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 是特定群組專屬的名稱或 ID (例如使用者名稱)。notification_key_namenotification_key 是特定一組註冊權杖專屬的值。請務必讓 notification_key_name 是 如果同一個用戶端應用程式有多個用戶端應用程式, 寄件者 ID。 這樣可確保訊息只會傳送至指定的目標應用程式。

回應格式

成功的要求會傳回 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` 值。

在裝置群組中新增及移除裝置

如要從現有群組新增或移除裝置,請傳送 POST 要求,且 operation 參數已設為 addremove,並提供 註冊憑證。

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 必要,字串 要執行的作業。有效值為 createaddremove
notification_key_name 必要,字串 要建立或修改的裝置群組使用者定義名稱。
notification_key 必填 (除了 create 作業、字串 裝置群組的專屬 ID。這個值會在成功的 create 作業回應中傳回,且為裝置群組的所有後續作業所需。
registration_ids 必要項目,字串陣列 要新增或移除的裝置符記。如果您移除所有的現有 裝置群組中註冊憑證,FCM 會刪除裝置群組。

將下游訊息傳送至裝置群組

如要傳送訊息給裝置群組,請使用 HTTP v1 API。如果您目前 將資料傳送至裝置群組 HTTP 或 XMPP,或者是 Firebase Admin SDK 適用於 Node.js 提供舊版通訊協定的更新 遷移至 HTTP v1 API 最先把握舊版 Send 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