透過 Web/JavaScript 傳送訊息至裝置群組

裝置群組訊息功能可讓您將多部裝置加入單一群組。這與主題訊息類似，但包含驗證機制，可確保只有您的伺服器能管理群組成員。舉例來說，如要向不同手機型號傳送不同訊息，伺服器可以將註冊項目新增至適當的群組，或從適當的群組中移除註冊項目，然後向每個群組傳送適當的訊息。裝置群組訊息傳送與主題訊息傳送不同，因為前者涉及從伺服器管理裝置群組，而不是直接在應用程式中管理。

通知金鑰的成員人數上限為 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_name 和 notification_key 是一組註冊權杖的專屬 ID。如果同一個傳送者 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 會刪除該裝置群組。

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

傳送訊息給裝置群組與傳送訊息給個別裝置非常相似，兩者都使用相同的方法授權傳送要求。將 token 欄位設為群組通知金鑰：