服务器参考

服务器实现是可选的。如果您要执行以下操作，请使用实例 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 Cloud Messaging 主题，并将应用实例订阅到该主题。该 API 提供了单独和批量创建此类关系的方法。

为应用实例创建关系映射

如果有注册令牌和受支持的关系，您就可以创建映射。例如，您可以为应用实例订阅 Google Cloud Messaging 主题，方法是调用此端点上的实例 ID 服务，并提供应用实例的令牌，如下所示：

 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_STRING - 提供的注册令牌对于发送者 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 Cloud Messaging 或 Firebase Cloud Messaging，将它们映射到有效的注册令牌。在此端点上调用实例 ID 服务，在 JSON 正文中提供 APNs 令牌列表：

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

响应正文包含一系列可用于向相应 APNs 设备令牌发送 FCM 或 GCM 消息的实例 ID 注册令牌。

参数

  • 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 Cloud Messaging 导入现有推送订阅。您还可以更新和删除它们。

导入推送订阅时，您会收到注册令牌。通过此令牌，您可以使用 FCM 功能（如主题消息传递和设备组消息传递）将通知发送到您的 Web 应用。

导入推送订阅

您可以使用 InstanceID 的 Web 端点导入推送订阅：

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

此请求必须包含一个设置为 OAuth 2.0 访问令牌的授权标头、一个设置为您的应用服务器密钥的加密密钥标头，以及请求正文中的 PushSubscription 对象。

响应正文包含一个注册令牌，可直接用于向相应的 Web 应用实例发送 FCM 或 GCM 消息，而无需加密载荷。

将您的 VAPID 密钥对上传到控制台

如需导入密钥，您必须拥有对 Firebase 项目的所有者级访问权限。以 base64 网址 安全编码形式导入现有的公钥和私钥：

  1. 打开 Firebase 控制台设置窗格中的 Cloud Messaging 标签页，然后滚动至 Web 配置部分。
  2. 在 Web 推送证书标签页中，找到并选择链接文本“导入现有密钥对”(import an existing keypair)。
  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 协议在 Web 应用中接收消息。

如需删除推送订阅，请向以下应用发送 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) - 服务不可用。请使用指数退避算法重试该请求。