迁移 GraphQL 全局节点 ID

了解两种全局节点 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 支持门户 联系我们，并提供诸如你的应用名称之类的信息，以便我们更好地为你提供帮助。