迁移 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 } }" }'

即使查询中使用了旧 IDMDQ6VXNlcjM0MDczMDM=，响应也将包含新的 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 支持门户与我们联系，并包含您的应用程序名称等信息，以便我们更好地为您提供帮助。