Перенос глобальных идентификаторов узлов GraphQL

Общие сведения

API GraphQL для GitHub Enterprise Cloud в настоящее время поддерживает два формата глобальных идентификаторов узлов. Старый формат станет нерекомендуемым и будет заменен новым форматом. В этом руководстве показано, как при необходимости перейти на новый формат.

Переходя на новый формат, вы обеспечиваете стабильно малое время отклика на запросы. Вы также гарантируете, что приложение продолжит работать после окончательного упразднения старых идентификаторов.

Дополнительные сведения о причинах упразднения старого формата глобальных идентификаторов узлов см. в разделе Новый формат глобальных идентификаторов в GraphQL.

Определение необходимости принятия мер

Выполнить инструкции по переходу необходимо только в том случае, если вы храните ссылки на глобальные идентификаторы узлов GraphQL. Эти идентификаторы соответствуют полю id для любого объекта в схеме. Если вы не храните глобальные идентификаторы узлов, то можете продолжать работать с API как прежде.

Кроме того, если в настоящее время вы декодируете старые идентификаторы для извлечения сведений о типах (например, если вы используете первые два символа PR_kwDOAHz1OX4uYAah для определения того, является ли объект запросом на вытягивание), работа службы нарушится из-за изменения формата идентификаторов. Необходимо перенести службу для обработки этих идентификаторов как непрозрачных строк. Эти идентификаторы будут уникальными, поэтому их можно использовать как ссылки напрямую.

Переход на новые глобальные идентификаторы

Чтобы упростить переход на новый формат идентификаторов, можно использовать заголовок X-Github-Next-Global-ID в запросах API GraphQL. Заголовок X-Github-Next-Global-ID может иметь значение 1 или 0. Если задать значение 1, в полезных данных ответа всегда будет использоваться новый формат идентификаторов для любого объекта, для которого запрашивается поле id. Если задать значение 0, восстанавливается поведение по умолчанию, то есть отображается устаревший или новый идентификатор в зависимости от даты создания объекта.

Ниже приведен пример запроса с помощью 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 } }" }'

Несмотря на то, что в запросе использовался устаревший идентификатор MDQ6VXNlcjM0MDczMDM=, ответ будет содержать идентификатор в новом формате:

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

С помощью заголовка X-Github-Next-Global-ID можно определить новый формат для устаревших идентификаторов, на которые вы ссылаетесь в приложении. Затем можно обновить эти ссылки идентификатором, полученным в ответе. Необходимо обновить все ссылки на устаревшие идентификаторы и использовать новый формат идентификаторов во всех последующих запросах к API. Для выполнения массовых операций можно использовать псевдонимы. Они позволяют отправлять запросы к нескольким узлам в одном вызове API. Дополнительные сведения см. в документации по GraphQL.

Вы также можете получить новый идентификатор для коллекции элементов. Например, если нужно получить новый идентификатор для последних 10 репозиториев в организации, можно использовать следующий запрос:

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

Обратите внимание, что присвоение значения 1 заголовку X-Github-Next-Global-ID повлияет на возвращаемое значение каждого поля id в запросе. Это означает, что даже при отправке запроса, не относящегося к node, будет возвращен новый формат идентификаторов, если вы запросили поле id.

Отправка отзывов

Если у вас возникли проблемы с развертыванием этого изменения, влияющего на приложение, обратитесь к и включите такие сведения, как имя приложения, чтобы мы могли лучше помочь вам.