Skip to main content
Мы публикуем частые обновления нашей документации, и перевод этой страницы может все еще выполняться. Актуальные сведения см. в документации на английском языке.

Формирование вызовов с помощью GraphQL

Узнайте, как выполнить проверку подлинности в API GraphQL, а затем узнайте, как создавать и выполнять запросы и изменения.

Проверка подлинности с помощью GraphQL

Примечание. Для проверки подлинности в API GraphQL необходимо создать personal access token, GitHub App или OAuth App. API GraphQL не поддерживает проверку подлинности с помощью fine-grained personal access tokens.

Проверка подлинности с помощью Personal access token

Чтобы пройти проверку подлинности с помощью personal access token, выполните действия, описанные в разделе Создание personal access token, чтобы создать personal access token. Запрашиваемые данные определяют, какие области вам потребуются. Например, выберите область read:user, чтобы запросить данные о пользователях. Выберите область "public_repo", чтобы запросить данные об общедоступных репозиториях.

Если у маркера нет необходимых областей для доступа к ресурсу, API вернет сообщение об ошибке, указывающее, какие области требуются маркеру.

Проверка подлинности с помощью GitHub App

Если вы хотите использовать API от имени организации или другого пользователя, GitHub рекомендует использовать GitHub App. Для проверки подлинности в качестве GitHub App необходимо сначала создать закрытый ключ в формате PEM. Затем необходимо использовать этот ключ для подписи веб-токена JSON (JWT). Веб-маркер JSON можно использовать для запроса маркера установки из GitHub, который можно использовать для проверки подлинности в API GraphQL. Дополнительные сведения см. в разделе Создание приложения GitHub, Проверка подлинности при входе в приложения GitHub и Идентификация и авторизация пользователей для приложений GitHub.

Проверка подлинности с помощью OAuth App

Чтобы пройти проверку подлинности с помощью маркера OAuth из OAuth App, сначала необходимо авторизовать OAuth App с помощью потока веб-приложения или потока устройства. Затем можно использовать полученный маркер доступа для доступа к API. Дополнительные сведения см. в разделах Создание приложения OAuth и Авторизация приложений OAuth.

Конечная точка GraphQL

REST API имеет множество конечных точек; API GraphQL — только одну:

http(s)://HOSTNAME/api/graphql

Конечная точка остается неизменной независимо от выполняемой операции.

Взаимодействие с GraphQL

Так как операции GraphQL состоят из нескольких строк кода JSON, GitHub рекомендует использовать Explorer для выполнения вызовов GraphQL. Вы также можете использовать curl или любую другую библиотеку http-речи.

В REST HTTP-команды определяют выполняемую операцию. В GraphQL вы предоставите текст в кодировке JSON независимо от того, выполняете ли вы запрос или изменение, поэтому HTTP-команда — POST. Исключением является запрос интроспекции, который представляет собой простой запрос GET к конечной точке. Дополнительные сведения о различиях между GraphQL и REST см. в разделе Переход с REST на GraphQL.

Чтобы запросить GraphQL в команде curl , выполните POST запрос с полезными данными JSON. Полезные данные должны содержать строку query:

curl -H "Authorization: bearer TOKEN" -X POST -d " \
 { \
   \"query\": \"query { viewer { login }}\" \
 } \
" http(s)://HOSTNAME/api/graphql

Примечание. В строковом значении "query" символы новой строки должны экранироваться, иначе оно будет неправильно проанализировано схемой. Для текста запроса POST используйте внешние двойные кавычки и экранированные внутренние двойные кавычки.

Операции запроса и изменения

В API GraphQL на GitHub разрешены два типа операций: запросы и изменения. Если сравнивать GraphQL с REST, запросы работают как запросы GET, а изменения — как POST/PATCH/DELETE. Имя изменения определяет производимую модификацию.

Сведения об ограничении скорости см. в разделе Ограничения ресурсов GraphQL.

Запросы и изменения похожи по форме за несколькими важными различиями.

Сведения о запросах

Запросы GraphQL возвращают только указанные данные. Для формирования запроса необходимо указать поля внутри полей (также известные как вложенные подполя), пока не будут возвращены только скалярные значения.

Запросы имеют следующую структуру:

query {
  JSON-OBJECT-TO-RETURN
}

Реальный пример см. в разделе Пример запроса.

Сведения об изменениях

Чтобы сформировать изменение, необходимо указать три элемента.

  1. Имя изменения — тип нужного изменения.
  2. Входной объект — данные, которые необходимо отправить на сервер; состоят из полей входных данных. Передайте его в качестве аргумента имени изменения.
  3. Объект полезных данных — данные, которые должны быть получены с сервера; состоят из возвращаемых полей. Передайте его в качестве тела имени мутации.

Изменения имеют следующую структуру:

mutation {
  MUTATION-NAME(input: {MUTATION-NAME-INPUT!}) {
    MUTATION-NAME-PAYLOAD
  }
}

Входной объект в этом примере — MutationNameInput, а объект полезных данных — MutationNamePayload.

В справочнике по изменениям перечислены поля входных данных, передаваемые в качестве входного объекта. Кроме того, перечислены возвращаемые поля, передаваемые в качестве объекта полезных данных.

Реальный пример см. в разделе Пример изменения.

Работа с переменными

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

Примечание. Если вы используете Explorer, вводите переменные в отдельной области "Переменные запроса" и не добавляйте слово variables перед объектом JSON.

Ниже приведен пример запроса с одной переменной.

query($number_of_repos:Int!) {
  viewer {
    name
     repositories(last: $number_of_repos) {
       nodes {
         name
       }
     }
   }
}
variables {
   "number_of_repos": 3
}

Переменные используются в три этапа.

  1. Определите переменную вне операции в объекте variables:

    variables {
       "number_of_repos": 3
    }
    

    Объект должен быть допустимым кодом JSON. В этом примере показана переменная простого типа Int, но можно определять переменные и более сложных типов, такие как входные объекты. Здесь также можно определить несколько переменных.

  2. Передайте переменную в операцию в качестве аргумента:

    query($number_of_repos:Int!){
    

    Аргумент представляет собой пару "ключ-значение", где ключ — это имя, начинающееся с $ (например, $number_of_repos), а значение — это тип (например, Int). Чтобы указать, что тип является обязательным, добавьте !. Если вы определили несколько переменных, включите их здесь как несколько аргументов.

  3. Используйте переменную в операции:

    repositories(last: $number_of_repos) {
    

    В этом примере переменная означает количество получаемых репозиториев. Тип указывается на шаге 2, так как в GraphQL действует строгая типизация.

Этот процесс делает аргумент запроса динамическим. Теперь мы можем просто изменить значение в объекте variables, оставив остальную часть запроса без изменений.

Использование переменных в качестве аргументов позволяет динамически обновлять значения в объекте variables, не меняя запрос.

Пример запроса

Давайте рассмотрим более сложный запрос в контексте.

Следующий запрос обращается к репозиторию octocat/Hello-World, находит 20 последних закрытых проблем и возвращает заголовок, URL-адрес и первые пять меток каждой проблемы:

query {
  repository(owner:"octocat", name:"Hello-World") {
    issues(last:20, states:CLOSED) {
      edges {
        node {
          title
          url
          labels(first:5) {
            edges {
              node {
                name
              }
            }
          }
        }
      }
    }
  }
}

Рассмотрим его структуру построчно.

  • query {

    Так как мы хотим считать данные с сервера, а не изменить их, query является корневой операцией. (Если операция не указана, query также выполняется по умолчанию.)

  • repository(owner:"octocat", name:"Hello-World") {

    Сначала нужно найти объект repository. Проверка схемы показывает, что для этого объекта требуются аргументы owner и name.

  • issues(last:20, states:CLOSED) {

    Чтобы получить сведения о всех проблемах в репозитории, мы вызываем объект issues. (Мы могли бы запросить одну проблему issue из объекта repository, но для этого нужно знать количество возвращаемых проблем и предоставить его в качестве аргумента.)

    Некоторые сведения об объекте issues:

    • В документации говорится, что этот объект имеет тип IssueConnection.
    • Проверка схемы показывает, что в качестве аргумента для этого объекта требуется количество последних (last) или первых (first) результатов, поэтому мы указываем 20.
    • В документации также говорится, что этот объект принимает аргумент states, который содержит одно из значений перечисления IssueState: OPEN или CLOSED. Чтобы найти только закрытые проблемы, мы присваиваем ключу states значение CLOSED.
  • edges {

    Мы знаем, что объект issues — это соединение, так как он имеет тип IssueConnection. Чтобы получить сведения об отдельных проблемах, необходимо получить доступ к узлу через edges.

  • node {

    В данном случае мы получаем узлы в конце ребра. В документации по IssueConnection указано, что узел в конце типа IssueConnection является объектом Issue.

  • Теперь, когда мы знаем, что извлекаем объект Issue, мы можем обратиться к документации и указать поля, которые нужно вернуть:

    title
    url
    labels(first:5) {
      edges {
        node {
          name
        }
      }
    }
    

    В данном случае мы указываем поля title, url и labels объекта Issue.

    Тип поля labels — LabelConnection. Как и в случае с объектом issues, так как labels — это соединение, необходимо пройти по его ребрам к подключенному узлу: объекту label. В этом узле можно указать поля объекта label, которые нужно вернуть, в данном случае name.

Вы можете заметить, что при выполнении этого запроса в общедоступном репозитории Octocat Hello-World возвращается небольшое количество меток. Попробуйте выполнить его в одном из собственных репозиториев, использующих метки, и вы, скорее всего, заметите разницу.

Пример изменения

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

  1. запрос для получения идентификатора проблемы;
  2. изменение для добавления реакции эмодзи на проблему.
query FindIssueID {
  repository(owner:"octocat", name:"Hello-World") {
    issue(number:349) {
      id
    }
  }
}

mutation AddReactionToIssue {
  addReaction(input:{subjectId:"MDU6SXNzdWUyMzEzOTE1NTE=",content:HOORAY}) {
    reaction {
      content
    }
    subject {
      id
    }
  }
}

Хотя запрос и изменение можно добавить в одном окне Explorer, если присвоить им имена (в данном примере FindIssueID и AddReactionToIssue), операции будут выполняться как отдельные вызовы конечной точки GraphQL. Запрос невозможно выполнить одновременно с изменением, и наоборот.

Разберем этот пример. Задача звучит просто: добавить реакцию эмодзи на проблему.

С какого же запроса нам начать? Пока мы не знаем.

Так как мы хотим изменить данные на сервере (добавить эмодзи к проблеме), мы начинаем с поиска подходящего изменения в схеме. В справочной документации есть изменение addReaction с таким описанием: Adds a reaction to a subject. Отлично!

В документации по изменению перечислены три поля входных данных:

  • clientMutationId (String)
  • subjectId (ID!)
  • content (ReactionContent!)

Символы ! указывают, что subjectId и content являются обязательными полями. То, что поле content обязательное, разумно: мы хотим добавить реакцию, поэтому нам нужно указать, какой эмодзи следует использовать.

Но почему обязательным является поле subjectId? Это связано с тем, что subjectId — это единственный способ указать, на какую проблему в каком репозитории следует отреагировать.

Вот почему мы начинаем этот пример с запроса: чтобы получить ID.

Давайте разберем запрос построчно.

  • query FindIssueID {

    Здесь мы выполняем запрос и называем его FindIssueID. Обратите внимание, что именование запроса является необязательным. В данном случае мы присваиваем ему имя, чтобы можно было включить его в то же окно Explorer, что и изменение.

  • repository(owner:"octocat", name:"Hello-World") {

    Мы указываем репозиторий, запрашивая объект repository и передавая аргументы owner и name.

  • issue(number:349) {

    Мы указываем проблему, на которую нужно отреагировать, запрашивая объект issue и передавая аргумент number.

  • id

    Здесь мы получаем id https://github.com/octocat/Hello-World/issues/349 для передачи в subjectId.

При выполнении запроса мы получаем id MDU6SXNzdWUyMzEzOTE1NTE=.

Примечание. Возвращаемое в запросе значение id — это значение, которое мы передадим как subjectID в изменении. Ни в документации, ни в схеме эта связь не определена. Необходимо просто понимать, как работают имена.

Зная идентификатор, мы можем перейти к изменению:

  • mutation AddReactionToIssue {

    Здесь мы выполняем изменение и называем его AddReactionToIssue. Как и в случае с запросами, именование изменения является необязательным. В данном случае мы присваиваем ему имя, чтобы можно было включить его в то же окно Explorer, что и запрос.

  • addReaction(input:{subjectId:"MDU6SXNzdWUyMzEzOTE1NTE=",content:HOORAY}) {

    Разберем эту строку:

    • addReaction — это имя изменения.

    • input — это обязательный ключ аргумента. Для изменения это всегда input.

    • {subjectId:"MDU6SXNzdWUyMzEzOTE1NTE=",content:HOORAY} — это обязательное значение аргумента. Для изменения это всегда будет входной объект (отсюда фигурные скобки), состоящий из полей входных данных (в данном случае subjectId и content).

      Как узнать, какое значение следует использовать для содержимого? В документации по addReaction говорится, что поле content имеет тип ReactionContent, который является перечислением, так как для проблем GitHub поддерживаются только некоторые реакции эмодзи. Ниже перечислены допустимые значения для реакций (обратите внимание, что некоторые значения отличаются от соответствующих имен эмодзи).

      содержимое эмодзи
      +1 👍
      -1 👎
      laugh 😄
      confused 😕
      heart ❤️
      hooray 🎉
      rocket 🚀
      eyes 👀
  • Остальная часть вызова — это объект полезных данных. Здесь мы указываем данные, которые сервер должен вернуть после изменения. В документации по addReaction определены три возможных возвращаемых поля:

    • clientMutationId (String)
    • reaction (Reaction!)
    • subject (Reactable!)

    В этом примере возвращаются два обязательных поля (reaction и subject); оба они имеют обязательные вложенные поля (content и id соответственно).

При выполнении изменения ответ будет следующим:

{
  "data": {
    "addReaction": {
      "reaction": {
        "content": "HOORAY"
      },
      "subject": {
        "id": "MDU6SXNzdWUyMTc5NTQ0OTc="
      }
    }
  }
}

Вот и все! Проверьте реакцию на проблему, наведя указатель мыши на 🎉 и посмотрев имя пользователя.

Последнее замечание: при передаче нескольких полей во входном объекте синтаксис может получиться громоздким. Помочь может помещение полей в переменную. Вот как можно переписать исходное изменение с использованием переменной:

mutation($myVar:AddReactionInput!) {
  addReaction(input:$myVar) {
    reaction {
      content
    }
    subject {
      id
    }
  }
}
variables {
  "myVar": {
    "subjectId":"MDU6SXNzdWUyMTc5NTQ0OTc=",
    "content":"HOORAY"
  }
}

Вы можете заметить, что в значении поля content в предыдущем примере (где оно используется в изменении напрямую) нет кавычек вокруг HOORAY, но при использовании в переменной кавычки есть. Этому есть причина:

  • При использовании content в изменении напрямую схема предполагает, что значение имеет тип ReactionContent, который является перечислением, а не строкой. Если добавить кавычки вокруг значения перечисления, при проверке схемы возникнет ошибка, так как кавычки зарезервированы для строк.
  • При использовании content в переменной раздел переменных должен быть допустимым кодом JSON, поэтому кавычки требуются. Проверка схемы правильно интерпретирует тип ReactionContent, когда переменная передается в изменение во время выполнения.

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

Дополнительные материалы

При формировании вызовов GraphQL доступно гораздо больше возможностей. Дополнительную информацию можно найти в следующих ресурсах: