裝置群組訊息功能可讓您將多部裝置加入單一群組。 這類似於主題訊息,但包含驗證來確保 群組成員資格只能透過您的伺服器管理。舉例來說 傳送不同的訊息至不同的手機型號,您的伺服器可新增或移除 註冊適當的群組,並向每個群組傳送適當的訊息 群組。裝置群組訊息與主題訊息不同, 從伺服器管理裝置群組,而不是直接在機構內部 應用程式。
通知鍵的成員人數上限為 20 人。
管理裝置群組
傳送訊息至裝置群組前,您必須:
-
為要新增的每部裝置取得註冊權杖 群組。
-
建立
notification_key
,用來識別 來對應特定群組 (通常是 user) 傳遞至群組相關聯的所有註冊權杖。 您可以在應用程式伺服器上建立通知鍵。
裝置群組的基本管理功能:建立及移除群組、 以及新增或移除裝置 — 是透過 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" }
裝置群組管理金鑰
下表列出建立裝置群組的金鑰 以及新增及移除成員
表 10.裝置群組管理金鑰。
參數 | 用量 | 說明 |
---|---|---|
operation |
必要,字串 | 要執行的作業。有效值為 create 、
add 和remove 。 |
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