伺服器參考資料

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

伺服器實作是選擇性的。如要執行以下作業，請使用執行個體 ID 服務：

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

如要取得應用程式執行個體的相關資訊，請在這個端點呼叫執行個體 ID 服務，並提供應用程式執行個體的權杖，如下所示：

 https://iid.googleapis.com/iid/info/IID_TOKEN

參數

  • Authorization：key=YOUR_API_KEY。在標頭中設定這個參數。
  • [選用] 布林值 details：將此查詢參數設為 true，以取得與這個符記相關聯的 FCM 或 GCM 主題訂閱資訊 (如果有的話)。如未指定，則預設為 false。

結果

呼叫成功時，系統會傳回 HTTP 狀態 200 以及包含以下項目的 JSON 物件：

  • application - 與憑證相關聯的套件名稱。
  • authorizedEntity - 可傳送至權杖的 projectId。
  • 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 提供個別和大量建立這類關係的方法。

為應用程式執行個體建立關係對應

只要註冊權杖與支援的關係，您就能建立對應關係。例如，您可以將這個端點的執行個體呼叫到這個端點的執行個體 ID 服務，以訂閱 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 呼叫中更新最多 1,000 個應用程式執行個體，請在這個端點呼叫執行個體 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_ARGUMENT — 提供的註冊憑證對寄件者 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"},
    {},
  ]
}

建立 APN 權杖的註冊憑證

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

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

回應主體包含一組執行個體 ID 註冊憑證，可用來將 FCM 或 GCM 訊息傳送至對應的 APN 裝置權杖。

參數

  • Authorization：key=YOUR_API_KEY。在標頭中設定這個參數。
  • application：應用程式的軟體包 ID。
  • sandbox：表示沙箱環境 (TRUE) 或正式版 (FALSE) 的布林值
  • apns_tokens - 您要新增或移除的應用程式執行個體的 APN 權杖陣列。每個要求最多 100 個憑證。

結果

呼叫成功時，系統會傳回 HTTP 狀態 200 和 JSON 結果主體。對於要求中提供的每個 APN 憑證，結果清單包括：

  • APN 權杖。
  • 狀態，可能是正常，或是描述失敗的錯誤訊息。
  • 為獲得最佳效果，FCM 或 GCM 會對應至 APN 憑證。

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 網址安全編碼格式匯入現有的公開與私密金鑰：

  1. 開啟 Firebase 控制台的「Settings」(設定) 窗格的 [Cloud Messaging] (雲端通訊) 分頁，然後捲動至「Web configuration」(網頁設定)部分。
  2. 在「Web Push Certificate」分頁中，找出並選取 [匯入現有的金鑰組] 連結文字。
  3. 在 [匯入金鑰組] 對話方塊中，在對應的欄位中提供公開和私密金鑰，然後按一下 [匯入]。主控台會顯示公開金鑰和新增的日期。

擷取 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);
      });
}
index.js

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
configure.py

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();
}
Configure.java

如要授權存取 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) - 服務無法使用。以指數輪詢方式重試要求。