伺服器參考資料

您可以選擇是否實作伺服器。如要執行這些作業,請使用執行個體 ID 服務:

取得應用程式執行個體的相關資訊

如要取得應用程式執行個體的相關資訊,請在此端點呼叫執行個體 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 - 應用程式的版本。
  • appSigner - sha1 指紋,用於套件套用的簽名。指出簽署應用程式的一方,例如 Play Store
  • platform - 傳回 ANDROIDIOSCHROME 來表示權杖所屬的裝置平台。

如果已設定 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",
  "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 可讓您為應用程式執行個體建立關係對應。例如,您可以將註冊權杖對應至 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 呼叫更新最多 1000 個應用程式執行個體,請在此端點呼叫執行個體 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_VALUE — 提供的註冊符記不適用於寄件者 ID。
  • 內部:後端伺服器因不明原因而失敗。重試要求。
  • 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"},
    {},
  ]
}

為 APNs 權杖建立註冊權杖

使用執行個體 ID 服務的 batchImport 方法,您可以將現有的 iOS APN 權杖大量匯入 Firebase 雲端通訊,並將其對應至有效的註冊權杖。在這個端點呼叫執行個體 ID 服務,並在 JSON 主體中提供 APNs 憑證清單:

 https://iid.googleapis.com/iid/v1:batchImport

回應主體包含一組執行個體 ID 註冊權杖陣列,可用於將 FCM 訊息傳送至對應的 APNs 裝置權杖。

參數

  • Authorization: Bearer <access_token>:在標頭中設定這個參數。將短期 OAuth2 權杖新增為 Authorization 標頭的值。如要進一步瞭解如何取得此權杖,請參閱「手動提供憑證」。
  • access_token_auth: true:在標頭中設定這個參數。
  • application:應用程式的軟體包 ID。
  • sandbox:布林值,用來表示沙箱環境 (TRUE) 或實際執行 (FALSE)
  • apns_tokens:您要新增或移除的應用程式執行個體的 APNs 權杖陣列。每個要求最多 100 個符記。

成果

成功後,呼叫會傳回 HTTP 狀態 200 和 JSON 結果主體。對於要求中提供的每個 APN 權杖,結果清單包括:

  • APNs 權杖。
  • 狀態,可以,或說明失敗的錯誤訊息。
  • 為確保結果成功,FCM 對應至 APNs 權杖的註冊權杖。

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"
        },
     ]
  }

錯誤回應

呼叫 Instance ID Server 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) - 服務無法使用。以指數輪詢方式重試要求。