伺服器參考資料

您可以選擇是否要導入伺服器。如要執行下列作業，請使用執行個體 ID 服務：

• 取得應用程式例項的相關資訊。 驗證應用程式權杖，或進一步瞭解建立權杖的應用程式例項。
• 為應用程式執行個體建立關係圖。在應用程式執行個體和實體之間建立關係。
• 為 APNs 權杖建立註冊權杖。這個 API 可讓您大量匯入現有的 APNs 權杖，並將這些權杖對應至 FCM 的有效註冊權杖。

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

如要取得應用程式執行個體的相關資訊，請在這個端點呼叫 Instance 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 提供個別和大量建立這類關係的方法。

為應用程式例項建立關係對應

只要有註冊權杖和支援的關係，您就能建立對應。舉例來說，您可以呼叫這個端點的 Instance 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
{}

管理多個應用程式例項的關係圖

您可以使用 Instance ID 服務的批次方法，批次管理應用程式例項。舉例來說，您可以大量新增或移除 FCM 主題的應用程式例項。如要透過每次 API 呼叫更新最多 1000 個應用程式例項，請在這個端點呼叫 Instance 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_ARGUMENT：提供的註冊權杖不適用於傳送者 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"},
    {},
  ]
}

為 APNs 權杖建立註冊權杖

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

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

回應主體包含一組 Instance 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 結果主體。對於要求中提供的每個 APNs 權杖，結果清單會包含：

• APNs 權杖。
• 狀態，成功時會顯示「OK」，失敗時則會顯示錯誤訊息。
• 如果結果成功，則為 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 伺服器 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) - 服務無法使用。以指數輪詢方式重試要求。