迁移 GraphQL 全局节点标识符

了解两种全局节点 ID 格式以及如何从旧格式迁移到新格式。

在本文中

背景

GitHub GraphQL API 当前支持两种类型的全局节点 ID 格式。 旧版格式将被 关闭，并由新格式取代。 本指南介绍如何在必要时迁移到新格式。

通过迁移到新格式，可以确保请求的响应时间保持一致且较短。 你还需要确保在旧版 ID 被 关闭 后，应用仍可继续正常运行。

要了解旧版全局节点 ID 格式为何会被 关闭，请参阅 GraphQL 即将推出的新全局 ID 格式。

确定是否需要采取措施

仅在存储对 GraphQL 全局节点 ID 的引用时，才需要遵循迁移步骤。 这些 ID 对应于架构中任何对象的 id 字段。 如果不存储任何全局节点 ID，则可以继续与 API 交互，而不会发生任何更改。

此外，如果当前对旧 ID 进行解码以提取类型信息（例如，如果使用 PR_kwDOAHz1OX4uYAah 的前两个字符来确定对象是否为拉取请求），则由于 ID 的格式已更改，你的服务将中断。 应迁移服务以将这些 ID 视为不透明字符串进行处理。 这些 ID 将是唯一的，因此您可以直接依赖它们作为引用。

迁移到新的全局 ID

为了便于迁移到新的 ID 格式，可以在 GraphQL API 请求中使用 X-Github-Next-Global-ID 标头。 X-Github-Next-Global-ID 标头的值可以是 1 或 0。 将该值设置为 1 将强制响应有效负载始终对为其请求 id 字段的任何对象使用新的 ID 格式。 将值设置为 0 将恢复为默认行为，即根据对象创建日期显示旧 ID 或新 ID。

下面是一个使用 curl 命令的示例请求：

$ curl \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "X-Github-Next-Global-ID: 1" \
  https://api.github.com/graphql \
  -d '{ "query": "{ node(id: \"MDQ6VXNlcjM0MDczMDM=\") { id } }" }'

即使查询中使用了旧 ID MDQ6VXNlcjM0MDczMDM=，响应也将包含新的 ID 格式：

{"data":{"node":{"id":"U_kgDOADP9xw"}}}

使用 X-Github-Next-Global-ID 标头，可以找到在应用程序中引用的旧 ID 的新 ID 格式。 然后，您可以使用响应中收到的 ID 更新这些引用。 您应更新对旧版 ID 的所有引用，并对 API 的任何后续请求使用新的 ID 格式。 要执行批量操作，您可以使用别名在一次 API 调用中提交多个节点查询。 有关详细信息，请参阅 GraphQL 文档。

您还可以为一组项目获取新 ID。 例如，如果要获取组织中最后 10 个存储库的新 ID，则可以使用如下所示的查询：

{
  organization(login: "github") {
    repositories(last: 10) {
      edges {
        cursor
        node {
          name
          id
        }
      }
    }
  }
}

请注意，将 X-Github-Next-Global-ID 设置为 1会影响查询中每个 id 字段的返回值。 这意味着，即使你提交了非 node 查询，只要请求了 id 字段便会获得新的格式 ID。

分享反馈

如果您担心此变更可能对您的应用产生影响，请联系 通过网站管理员GitHub支持门户 并提供您的应用名称等信息，以便我们更好地帮助您。