您可以選擇是否實作伺服器。如要執行這些作業,請使用執行個體 ID 服務:
- 取得應用程式執行個體相關資訊。 驗證應用程式權杖,或進一步瞭解建立該權杖的應用程式執行個體。
- 建立應用程式執行個體的關係對應。在應用程式執行個體和實體 (例如 FCM 或 GCM 主題) 之間建立關係。
- 建立 APNs 權杖的註冊權杖。這個 API 可讓您大量匯入現有的 APNs 權杖,並將其對應至有效的 FCM 或 GCM 註冊權杖。
- 管理推送訂閱項目的註冊權杖。如果是使用 Push API 實作的網頁應用程式,請匯入現有的推送訂閱項目,然後將這些訂閱項目對應至 FCM 的有效註冊權杖。
取得應用程式執行個體相關資訊
如要取得應用程式執行個體的相關資訊,請在這個端點上呼叫執行個體 ID 服務,並提供應用程式執行個體的權杖,如下所示:
https://iid.googleapis.com/iid/info/IID_TOKEN
參數
Authorization
:key=YOUR_API_KEY。在標頭中設定這個參數。- [選用] 布林值
details
:將這項查詢參數設為true
以取得與此權杖相關聯的 FCM 或 GCM 主題訂閱資訊 (如有)。如未指定,則預設為false
。
結果
呼叫成功時,系統會傳回 HTTP 狀態 200,以及包含下列項目的 JSON 物件:
application
- 與權杖相關聯的套件名稱。authorizedEntity
- 已向權杖傳送專案 ID 的權限。applicationVersion
- 應用程式版本。appSigner
- 簽名中sha1
的指紋。指出簽署應用程式的簽署方,例如Play Store
。platform
- 傳回ANDROID
、IOS
或CHROME
,以表示權杖所屬的裝置平台。
如果設定了 details
旗標:
rel
- 與權杖相關聯的關係。例如,主題訂閱清單。
GET
要求範例
https://iid.googleapis.com/iid/info/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA?Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
搜尋結果範例
HTTP 200 OK
{
"application":"com.iid.example",
"authorizedEntity":"123456782354",
"platform":"Android",
"appSigner":"1a2bc3d4e5"
"rel":{
"topics":{
"topicname1":{"addDate":"2015-07-30"},
"topicname2":{"addDate":"2015-07-30"},
"topicname3":{"addDate":"2015-07-30"},
"topicname4":{"addDate":"2015-07-30"}
}
}
}
建立應用程式執行個體的關係對應
Instance ID API 可讓您建立應用程式執行個體的關係對應。舉例來說,您可以將註冊權杖對應至 Google 雲端通訊主題,以訂閱應用程式執行個體到該主題。這個 API 提供建立個別關係與大量建立方法的方法。
建立應用程式執行個體的關係對應
只要有註冊權杖和支援的關係,即可建立對應關係。舉例來說,您可以呼叫這個端點的執行個體執行個體服務,藉此提供應用程式執行個體到 Google 雲端通訊主題,如下所示:
https://iid.googleapis.com/iid/v1/IID_TOKEN/rel/topics/TOPIC_NAME
參數
Authorization
:key=YOUR_API_KEY。在標頭中設定這個參數。
結果
呼叫成功時,系統會傳回 HTTP 狀態 200。
POST
要求範例
https://iid.googleapis.com/iid/v1/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA/rel/topics/movies
Content-Type:application/json
Content-Length: 0
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
搜尋結果範例
HTTP 200 OK
{}
管理多個應用程式執行個體的關係對應
利用執行個體 ID 服務的批次方法,您可以批次管理應用程式執行個體。舉例來說,您可以對 FCM 或 GCM 主題大量新增或移除應用程式執行個體。如要為每個 API 呼叫更新最多 1000 個應用程式執行個體,請呼叫這個端點的執行個體 ID 服務,並在 JSON 主體中提供應用程式執行個體權杖:
https://iid.googleapis.com/iid/v1:batchAdd
https://iid.googleapis.com/iid/v1:batchRemove
參數
Authorization
:key=YOUR_API_KEY。在標頭中設定這個參數。to
:主題名稱。registration_tokens
:要新增或移除的應用程式執行個體的 IID 權杖陣列。
結果
呼叫成功時,系統會傳回 HTTP 狀態 200。空白結果表示訂閱項目已成功訂閱。針對失敗的訂閱項目,結果會包含下列其中一個錯誤代碼:
- NOT_FOUND:已刪除註冊權杖或應用程式解除安裝。
- INVALID_等等:所提供的註冊權杖不適用於傳送者 ID。
- 內部:後端伺服器因不明原因而失敗。重試要求。
- TOO_MANY_TOPICS:每個應用程式執行個體的主題數量過多。
- RESOURCE_EXHAUSTED — 短時間內訂閱或取消訂閱要求過多。以指數輪詢方式重試。
POST
要求範例
https://iid.googleapis.com/iid/v1:batchAdd
Content-Type:application/json
Authorization:key=API_KEY
{
"to": "/topics/movies",
"registration_tokens": ["nKctODamlM4:CKrh_PC8kIb7O...", "1uoasi24:9jsjwuw...", "798aywu:cba420..."],
}
搜尋結果範例
HTTP 200 OK
{
"results":[
{},
{"error":"NOT_FOUND"},
{},
]
}
建立 APNs 權杖的註冊權杖
您可以使用執行個體 ID 服務的 batchImport
方法,將現有的 iOS APNs 權杖大量匯入 Google 雲端通訊或 Firebase 雲端通訊,然後將這些權杖對應至有效的註冊權杖。在這個端點上呼叫執行個體 ID 服務,並在 JSON 主體中提供 APNs 權杖清單:
https://iid.googleapis.com/iid/v1:batchImport
回應內文含有執行個體 ID 註冊權杖陣列,可用於將 FCM 或 GCM 訊息傳送至對應的 APNs 裝置權杖。
參數
Authorization
:key=YOUR_API_KEY。在標頭中設定這個參數。application
:應用程式的軟體包 ID。sandbox
:代表沙箱環境 (TRUE) 或正式版 (FALSE) 的布林值apns_tokens
:要新增或移除的應用程式執行個體的 APNs 憑證陣列。每項要求最多可以有 100 個符記。
結果
呼叫成功時,系統會傳回 HTTP 狀態 200 和 JSON 結果內文。針對要求中提供的每個 APNs 權杖,結果清單包括:
- APNs 權杖。
- 狀態,「確定」或關於失敗的錯誤訊息。
- 如要取得成功,FCM 或 GCM 對應的註冊權杖會對應至 APNs 權杖。
POST
要求範例
https://iid.googleapis.com/iid/v1:batchImport
{
"application": "com.google.FCMTestApp",
"sandbox":false,
"apns_tokens":[
"368dde283db539abc4a6419b1795b6131194703b816e4f624ffa12",
"76b39c2b2ceaadee8400b8868c2f45325ab9831c1998ed70859d86"
]
}
}
搜尋結果範例
HTTP 200 OK
{
"results":[
{
"apns_token": "368dde283db539abc4a6419b1795b6131194703b816e4f624ffa12",
"status": "OK",
"registration_token":"nKctODamlM4:CKrh_PC8kIb7O...clJONHoA"
},
{
"apns_token": "76b39c2b2ceaadee8400b8868c2f45325ab9831c1998ed70859d86",
"status":"Internal Server Error"
},
]
}
管理推送訂閱項目的註冊權杖
您可以使用執行個體 ID 服務的 Web 方法匯入 Firebase 雲端通訊的現有推送訂閱項目。您也可以更新及刪除這些內容。
匯入推送訂閱項目時,您會收到註冊權杖。這個權杖可讓您使用 FCM 功能 (例如主題訊息和裝置群組訊息),將通知鎖定至您的網頁應用程式。
匯入推送訂閱項目
您可以使用 InstanceID 的網路端點匯入推送訂閱項目:
https://iid.googleapis.com/v1/web/iid
要求必須含有一個設為 OAuth 2.0 存取權杖的授權標頭、設為應用程式伺服器金鑰的加密編譯金鑰金鑰,以及要求內文中的 PushSubscription
物件。
回應主體含有可用於將 FCM 或 GCM 訊息傳送至對應的網頁應用程式執行個體的註冊權杖,無須加密酬載。
將 VAPID 金鑰組上傳至控制台
如要匯入金鑰,您必須具備 Firebase 專案的擁有者層級存取權。以 Base64 網址安全編碼格式匯入現有的公開和私密金鑰:
- 在 Firebase 控制台的「設定」窗格開啟 「雲端通訊」分頁,然後捲動至「網路設定」部分。
- 在 [網路推送憑證] 分頁中,找出並選取 [匯入現有金鑰組] 連結文字。
- 在「Import key key」(匯入金鑰組) 對話方塊中的對應欄位中輸入您的公開與私密金鑰,然後按一下「匯入」。控制台會顯示公開金鑰字串和新增日期。
擷取 OAuth2 權杖:使用憑證擷取存取權杖
您必須為請求建立存取權杖並新增至 HTTP 要求,才能建立要求的存取權杖。
node.js
function getAccessToken() {
return admin.credential.applicationDefault().getAccessToken()
.then(accessToken => {
return accessToken.access_token;
})
.catch(err => {
console.error('Unable to get access token');
console.error(err);
});
}
Python
def _get_access_token():
"""Retrieve a valid access token that can be used to authorize requests.
:return: Access token.
"""
credentials = ServiceAccountCredentials.from_json_keyfile_name(
'service-account.json', SCOPES)
access_token_info = credentials.get_access_token()
return access_token_info.access_token
Java
private static String getAccessToken() throws IOException {
GoogleCredentials googleCredentials = GoogleCredentials
.fromStream(new FileInputStream("service-account.json"))
.createScoped(Arrays.asList(SCOPES));
googleCredentials.refreshAccessToken();
return googleCredentials.getAccessToken().getTokenValue();
}
如要授予 FCM 存取權,請要求 https://www.googleapis.com/auth/firebase.messaging
範圍。
參數
- 授權:
Bearer <access_token>
。在標頭中設定這個參數。 - 加密編譯金鑰:
p256ecdsa=APPLICATION_PUBLIC_KEY
。在標頭中設定這個參數。 - 要求主體:
PushSubscription.toJson()
。將推送訂閱項目傳遞至 HTTP 主體,而不進行剖析。內容與PushSubscription
的 W3C 編碼相符。
回應
呼叫成功時,系統會傳回 HTTP 狀態 200 OK 和包含 IID 權杖的 JSON 結果內文。
POST
要求範例
https://iid.googleapis.com/v1/web/iid
Content-Type:application/json
Authorization:Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
Crypto-Key:p256ecdsa=BFv5XHxdkZgpQzCb-...8uI42kf4A4USEIMo
{
"endpoint": "https://fcm.googleapis.com/fcm/send/dS4xerbSlqU:APb...aRs4QP",
"keys": {
"auth": "7cdY...xxjwz46Q",
"p256dh": "BH7xPjScJe...z9lbIZDmOV_c"
}
}
搜尋結果範例
HTTP 200 OK
{
"token":"KctODamlM4:CKrh_PC...cl"
}
更新推送訂閱項目
您可以使用下列端點,更新與註冊權杖相關聯的推送訂閱項目:
https://iid.googleapis.com/v1/web/iid/REGISTRATION_TOKEN:refresh
參數
- 授權:
Bearer <access_token>
。在標頭中設定這個參數。 - 加密編譯金鑰:
p256ecdsa=APPLICATION_PUBLIC_KEY
。在標頭中設定這個參數。 - 要求主體:
PushSubscription.toJson()
。將推送訂閱項目傳遞至 HTTP 主體,而不進行剖析。內容與PushSubscription
的 W3C 編碼相符。
結果
呼叫成功時,系統會傳回 HTTP 狀態 200 和註冊權杖。這可能與您在要求中傳遞的權杖相同,也可能是新的權杖。
HTTP 200 OK
{
"token":"KctODamlM4:CKrh_PC...cl"
}
POST
要求範例
https://iid.googleapis.com/v1/web/iid/KctODamlM4:CKrh_PC...cl:refresh
Content-Type:application/json
Authorization:Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
Crypto-Key:p256ecdsa=BFv5XHxdkZgpQzCb-...8uI42kf4A4USEIMo
{
"endpoint": "https://fcm.googleapis.com/fcm/send/dS4xerbSlqU:APb...aRs4QP",
"keys": {
"auth": "7cdY...xxjwz46Q"",
"p256dh": "BH7xPjScJe...z9lbIZDmOV_c"
}
}
搜尋結果範例
HTTP 200 OK
{
"token":"KctODamlM4:CI2k_HHw...3P1"
}
刪除推送訂閱項目
從 DELETE
要求中移除 FCM 資料庫的推送訂閱項目詳細資料。您仍然可以使用 Push API 通訊協定,在網頁應用程式中接收訊息。
如要刪除推送訂閱項目,請傳送 DELETE
要求至:
https://iid.googleapis.com/v1/web/iid/REGISTRATION_TOKEN
DELETE
要求範例
https://iid.googleapis.com/v1/web/iid/KctODamlM4:CI2k_HHw...3P1
Authorization:Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
搜尋結果範例
HTTP 200 OK {}
錯誤回應
向執行個體 ID 伺服器 API 的呼叫會傳回下列 HTTP 錯誤代碼:
HTTP status 400 (Bad request)
- 要求參數遺失或無效。查看錯誤訊息瞭解詳情。HTTP status 401 (Unauthorized)
- 授權標頭無效。HTTP status 403 (Forbidden)
- 授權標頭與authorizedEntity
不符。HTTP status 404 (Not found)
- 找不到 HTTP 路徑或 IID 權杖。查看錯誤訊息瞭解詳情。HTTP status 503 (Service unavailable)
- 無法使用服務。以指數輪詢方式重試要求。