{"meta":{"title":"迁移 GraphQL 全局节点标识符","intro":"了解两种全局节点 ID 格式以及如何从旧格式迁移到新格式。","product":"GraphQL API","breadcrumbs":[{"href":"/zh/graphql","title":"GraphQL API"},{"href":"/zh/graphql/guides","title":"指南"},{"href":"/zh/graphql/guides/migrating-graphql-global-node-ids","title":"迁移全局节点 ID"}],"documentType":"article"},"body":"# 迁移 GraphQL 全局节点标识符\n\n了解两种全局节点 ID 格式以及如何从旧格式迁移到新格式。\n\n## 背景\n\nGitHub GraphQL API 当前支持两种类型的全局节点 ID 格式。 旧版格式将被 关闭，并由新格式取代。 本指南介绍如何在必要时迁移到新格式。\n\n通过迁移到新格式，可以确保请求的响应时间保持一致且较短。 你还需要确保在旧版 ID 被 关闭 后，应用仍可继续正常运行。\n\n要了解旧版全局节点 ID 格式为何会被 关闭，请参阅 [GraphQL 即将推出的新全局 ID 格式](https://github.blog/2021-02-10-new-global-id-format-coming-to-graphql)。\n\n## 确定是否需要采取措施\n\n仅在存储对 GraphQL 全局节点 ID 的引用时，才需要遵循迁移步骤。 这些 ID 对应于架构中任何对象的 `id` 字段。 如果不存储任何全局节点 ID，则可以继续与 API 交互，而不会发生任何更改。\n\n此外，如果当前对旧 ID 进行解码以提取类型信息（例如，如果使用 `PR_kwDOAHz1OX4uYAah` 的前两个字符来确定对象是否为拉取请求），则由于 ID 的格式已更改，你的服务将中断。 应迁移服务以将这些 ID 视为不透明字符串进行处理。 这些 ID 将是唯一的，因此您可以直接依赖它们作为引用。\n\n## 迁移到新的全局 ID\n\n为了便于迁移到新的 ID 格式，可以在 GraphQL API 请求中使用 `X-Github-Next-Global-ID` 标头。 \n`X-Github-Next-Global-ID` 标头的值可以是 `1` 或 `0`。 将该值设置为 `1` 将强制响应有效负载始终对为其请求 `id` 字段的任何对象使用新的 ID 格式。 将值设置为 `0` 将恢复为默认行为，即根据对象创建日期显示旧 ID 或新 ID。\n\n下面是一个使用 `curl` 命令的示例请求：\n\n```shell\n$ curl \\\n  -H \"Authorization: Bearer $GITHUB_TOKEN\" \\\n  -H \"X-Github-Next-Global-ID: 1\" \\\n  https://api.github.com/graphql \\\n  -d '{ \"query\": \"{ node(id: \\\"MDQ6VXNlcjM0MDczMDM=\\\") { id } }\" }'\n```\n\n即使查询中使用了旧 ID `MDQ6VXNlcjM0MDczMDM=`，响应也将包含新的 ID 格式：\n\n```json\n{\"data\":{\"node\":{\"id\":\"U_kgDOADP9xw\"}}}\n```\n\n使用 `X-Github-Next-Global-ID` 标头，可以找到在应用程序中引用的旧 ID 的新 ID 格式。 然后，您可以使用响应中收到的 ID 更新这些引用。 您应更新对旧版 ID 的所有引用，并对 API 的任何后续请求使用新的 ID 格式。\n要执行批量操作，您可以使用别名在一次 API 调用中提交多个节点查询。 有关详细信息，请参阅 [GraphQL 文档](https://graphql.org/learn/queries/#aliases)。\n\n您还可以为一组项目获取新 ID。 例如，如果要获取组织中最后 10 个存储库的新 ID，则可以使用如下所示的查询：\n\n```graphql\n{\n  organization(login: \"github\") {\n    repositories(last: 10) {\n      edges {\n        cursor\n        node {\n          name\n          id\n        }\n      }\n    }\n  }\n}\n```\n\n请注意，将 `X-Github-Next-Global-ID` 设置为 `1`会影响查询中每个 `id` 字段的返回值。 这意味着，即使你提交了非 `node` 查询，只要请求了 `id` 字段便会获得新的格式 ID。\n\n## 分享反馈\n\n如果您担心此变更可能对您的应用产生影响，请联系 通过网站管理员[GitHub支持门户](https://support.github.com) 并提供您的应用名称等信息，以便我们更好地帮助您。"}