裝置群組訊息功能可讓您將多部裝置加入單一群組。這類似於主題訊息,但包含驗證機制,可確保只有您的伺服器管理群組成員資格。舉例來說,如果您想傳送不同訊息給不同的手機型號,伺服器可以將註冊項目新增/移除至適當的群組,並傳送適當的訊息給每個群組。裝置群組訊息與主題訊息的差異在於,裝置群組訊息需要透過伺服器管理,而非直接在應用程式中管理。
通知鍵可加入的成員數上限為 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
必須為每個用戶端應用程式提供獨特的 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
參數設為 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" }
裝置群組管理鍵
下表列出建立裝置群組、新增及移除成員的索引鍵。
參數 | 用量 | 說明 |
---|---|---|
operation |
必要,字串 | 要執行的作業。有效值為 create 、add 和 remove 。 |
notification_key_name |
必要,字串 | 要建立或修改的裝置群組使用者定義名稱。 |
notification_key |
必填 (除了 create 作業、字串 |
裝置群組的專屬 ID。這個值會在成功的 create 作業回應中傳回,且為裝置群組的所有後續作業所需。 |
registration_ids |
必要,字串陣列 | 要新增或移除的裝置 Token。如果您從裝置群組中移除所有現有的註冊權杖,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
將上游訊息傳送至裝置群組
用戶端應用程式可以將訊息指定給 to
欄位中的適當通知鍵,將訊息傳送至裝置群組的上游。
以下對 FCM 的呼叫會將上游訊息傳送至通知鍵。
Firebase.Messaging.Message message; message.To = notification_key; message.MessageId = a_unique_message_id; message.Data["hello"] = "world"; Firebase.Messaging.FirebaseMessaging.Send(message);