服务器参考

服务器实现是可选的。如果需要，您可以使用实例 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 - 应用的版本。
  • 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 提供了用于创建 无论是单独还是批量管理。

为应用实例创建关系映射

给定一个注册令牌和一种受支持的关系，您就可以创建 映射例如，您可以为应用实例订阅 FCM 主题 方法是在以下位置调用实例 ID 服务： 此端点，提供应用实例的令牌，如下所示：

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

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

响应正文包含一组已准备就绪的实例 ID 注册令牌 用于向相应的 APNs 设备令牌发送 FCM 消息。

参数

  • 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 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) - 服务不可用。重新尝试 请求。