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

裝置群組訊息功能可讓您將多部裝置加入單一群組。這與主題訊息類似，但包含驗證，確保只有您的伺服器能管理群組成員。舉例來說，如果您想向不同的手機機型傳送不同的訊息，伺服器可新增/移除註冊至適當的群組，並向各個群組傳送適當的訊息。裝置群組訊息與主題訊息不同，您需要透過伺服器管理裝置群組，而不是直接在應用程式內進行。

通知鍵的成員人數上限為 20 人。

管理裝置群組

向裝置群組傳送訊息前，您必須：

為要加入群組的每部裝置取得註冊權杖。
建立 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_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」值。

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

如要在現有群組中新增或移除裝置，請傳送 POST 要求並將 operation 參數設為 add 或 remove，並提供要新增或移除的註冊權杖。

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` 作業、字串除外)	裝置群組的專屬 ID。成功執行 `create` 作業的回應中會傳回此值，裝置群組後續的所有作業都必須使用這個值。
`registration_ids`	必要，字串陣列	要新增或移除的裝置權杖。如果從裝置群組中移除所有現有註冊權杖，FCM 會刪除裝置群組。

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

如要傳送訊息至裝置群組，請使用 HTTP v1 API。如果您目前將 HTTP 或 XMPP 適用的舊版傳送 API 傳送至裝置群組，或使用舊版通訊協定的 Node.js 適用的 Firebase Admin SDK 任何版本，強烈建議您最先遷移至 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