您可以選擇是否導入伺服器。如要執行這些作業,請使用執行個體 ID 服務:
- 取得應用程式執行個體的相關資訊。 驗證應用程式權杖,或進一步瞭解建立權杖的應用程式執行個體。
- 為應用程式執行個體建立關係圖。建立應用程式執行個體和實體之間的關係。
- 建立 APNs 權杖的註冊權杖。這個 API 可讓您大量匯入現有的 APN 權杖,並將其對應至有效的 FCM 註冊權杖。
取得應用程式執行個體的相關資訊
如要取得應用程式執行個體的相關資訊,請在這個端點呼叫執行個體 ID 服務,提供應用程式執行個體的憑證,如下所示:
https://iid.googleapis.com/iid/info/IID_TOKEN
參數
Authorization: Bearer <access_token>
:在標頭中設定這個參數。新增短期 OAuth2 權杖做為Authorization
標頭的值。如要進一步瞭解如何取得這個憑證,請參閱手動提供憑證。access_token_auth: true
:在標頭中設定這個參數。- [選用] 布林值
details
:將這個查詢參數設為true
,即可取得與這個權杖相關聯的 FCM 主題訂閱資訊 (如有)。如未指定,則會預設為false
。
結果
呼叫成功時,系統會傳回 HTTP 狀態 200 和包含以下內容的 JSON 物件:
application
- 與權杖相關聯的套件名稱。authorizedEntity
- 經授權可傳送至權杖的專案 ID。applicationVersion
- 應用程式版本。platform
:傳回ANDROID
、IOS
或CHROME
來表示權杖所屬的裝置平台。
如果已設定 details
標記:
rel
:與權杖相關聯的關聯,例如主題訂閱項目清單。
GET
要求示例
https://iid.googleapis.com/iid/info/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA
Content-Type:application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
access_token_auth: true
結果範例
HTTP 200 OK
{
"application":"com.iid.example",
"authorizedEntity":"123456782354",
"platform":"Android",
"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 為應用程式執行個體建立關係對應。舉例來說,您可以將註冊權杖對應至 FCM 主題,訂閱應用程式執行個體與該主題。API 提供可個別或大量建立這類關係的方法。
為應用程式執行個體建立關聯對應
只要有註冊權杖和支援的關係,您就可以建立對應關係。舉例來說,您可以在這個端點呼叫執行個體 ID 服務,提供應用程式執行個體的權杖,藉此將應用程式執行個體訂閱 FCM 主題,如下所示:
https://iid.googleapis.com/iid/v1/IID_TOKEN/rel/topics/TOPIC_NAME
參數
Authorization: Bearer <access_token>
:在標頭中設定這個參數。新增短期 OAuth2 權杖做為Authorization
標頭的值。如要進一步瞭解如何取得這個憑證,請參閱手動提供憑證。access_token_auth: true
:在標頭中設定這個參數。
結果
呼叫成功時,會傳回 HTTP 狀態 200。
POST
要求示例
https://iid.googleapis.com/iid/v1/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA/rel/topics/movies
Content-Type:application/json
Content-Length: 0
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
access_token_auth: true
結果範例
HTTP 200 OK
{}
管理多個應用程式執行個體的關係圖
您可以使用執行個體 ID 服務的批次方法,執行應用程式執行個體的批次管理。舉例來說,您可以對 FCM 主題執行大量新增或移除應用程式執行個體。如要為每個 API 呼叫更新最多 1,000 個應用程式執行個體,請在這個端點呼叫執行個體 ID 服務,並在 JSON 主體中提供應用程式執行個體權杖:
https://iid.googleapis.com/iid/v1:batchAdd
https://iid.googleapis.com/iid/v1:batchRemove
參數
Authorization: Bearer <access_token>
:在標頭中設定這個參數。新增短期 OAuth2 權杖做為Authorization
標頭的值。如要進一步瞭解如何取得這個憑證,請參閱手動提供憑證。access_token_auth: true
:在標頭中設定這個參數。to
:主題名稱。registration_tokens
:要新增或移除的應用程式執行個體的 IID 權杖陣列。
結果
呼叫成功時,會傳回 HTTP 狀態 200。空白結果表示該符記訂閱成功。如果是失敗的訂閱,結果會包含下列其中一個錯誤代碼:
- NOT_FOUND — 註冊憑證已遭刪除,或應用程式已解除安裝。
- INVALID_src — 提供的註冊權杖對寄件者 ID 無效。
- INTERNAL:後端伺服器因不明原因而失敗。重試要求。
- TOO_MANY_TOPICS - 每個應用程式執行個體的主題數量過多。
- RESOURCE_EXHAUSTED:短時間內的訂閱或取消訂閱要求過多。以指數輪詢方式重試。
POST
要求示例
https://iid.googleapis.com/iid/v1:batchAdd
Content-Type:application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
access_token_auth: true
{
"to": "/topics/movies",
"registration_tokens": ["nKctODamlM4:CKrh_PC8kIb7O...", "1uoasi24:9jsjwuw...", "798aywu:cba420..."],
}
結果範例
HTTP 200 OK
{
"results":[
{},
{"error":"NOT_FOUND"},
{},
]
}
建立 APN 權杖的註冊權杖
您可以使用執行個體 ID 服務的 batchImport
方法,將現有的 iOS APN 權杖大量匯入至 Firebase 雲端通訊,並對應至有效的註冊權杖。在這個端點呼叫執行個體 ID 服務,提供 JSON 主體中的 APN 權杖清單:
https://iid.googleapis.com/iid/v1:batchImport
回應主體包含執行個體 ID 註冊權杖的陣列,可用於將 FCM 訊息傳送至對應的 APN 裝置權杖。
參數
Authorization: Bearer <access_token>
:在標頭中設定這個參數。新增短期 OAuth2 權杖做為Authorization
標頭的值。如要進一步瞭解如何取得這個憑證,請參閱手動提供憑證。access_token_auth: true
:在標頭中設定這個參數。application
:應用程式的軟體包 ID。sandbox
:代表沙箱環境 (TRUE) 或實際執行 (FALSE) 的布林值apns_tokens
:要新增或移除的應用程式執行個體的 APN 權杖陣列。每個要求最多 100 個符記。
結果
呼叫成功時,會傳回 HTTP 狀態 200 和 JSON 結果主體。針對要求中提供的每個 APN 符記,結果清單包括:
- APN 權杖。
- 狀態,可以,或說明失敗的錯誤訊息。
- 如要取得成功,FCM 對應至 APN 權杖的註冊權杖。
POST
要求示例
https://iid.googleapis.com/iid/v1:batchImport
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
access_token_auth:true
{
"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 伺服器 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)
- 服務無法使用。以指數輪詢方式重試要求。