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

Использование API GitHub в приложении

Узнайте, как настроить приложение для прослушивания событий и использовать библиотеку Octokit для выполнения операций REST API.

Введение

Это руководство поможет вам создать приложение GitHub и запустить его на сервере. Приложение, которое вы создаете, добавит метку ко всем новым проблемам, открытым в репозитории, где оно установлено.

Этот проект позволит вам выполнить следующие действия:

  • программирование приложения для ожидания передачи данных для событий;
  • использование библиотеки Octokit.rb для выполнения операций REST API.

Примечание. В этом руководстве демонстрируется процесс разработки приложений с использованием языка программирования Ruby. Однако существуют и другие способы применения Octokit. Если вы предпочитаете JavaScript, то для разработки приложений GitHub можно использовать Probot и Node.js.

После выполнения этих шагов вы будете готовы к разработке других видов интеграции с помощью полного набора API-интерфейсов GitHub.

Предварительные требования

Могут быть полезны базовые знания в следующих областях:

Но вы можете работать, имея любой уровень опыта. Мы будем ссылаться на необходимую информацию на этом пути!

Перед началом работы сделайте следующее:

  1. Клонируйте репозиторий для использования API GitHub в приложении.

    $ git clone https://github.com/github-developer/using-the-github-api-in-your-app.git

    В каталоге вы найдете файл template_server.rb с кодом шаблона, который будет использоваться в этом кратком руководстве, и файл server.rb с готовым кодом проекта.

  2. Выполните действия, описанные в кратком руководстве Настройка среды разработки, чтобы настроить и запустить сервер приложений template_server.rb. Если вы ранее выполнили инструкции из краткого руководства по приложению GitHub, отличного от руководства Настройка среды разработки, зарегистрируйте новое приложение GitHub и запустите новый канал Smee, который будет использоваться с этим кратким руководством.

    В этом кратком руководстве содержится тот же код template_server.rb, что и в кратком руководстве Настройка среды разработки. Примечание. Следуя инструкциям из краткого руководства Настройка среды разработки, обязательно используйте файлы проекта, включенные в репозиторий для применения API GitHub в приложении.

    Если у вас возникли проблемы с настройкой шаблона приложения GitHub, ознакомьтесь с разделом Устранение неполадок.

Сборка приложения

Теперь, когда вы знакомы с кодом template_server.rb, вы можете создать код, который автоматически добавляет метку needs-response ко всем проблемам, открытым в репозитории, где установлено приложение.

Файл template_server.rb содержит код шаблона приложения, который еще не был настроен. В этом файле вы увидите код заполнителя для обработки событий веб-перехватчика и другой код для инициализации клиента Octokit.rb.

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

Окончательный настроенный код, который вы создадите в конце этого руководства, приведен в server.rb. Однако попробуйте дойти до конца, чтобы ознакомиться с ним!

Ниже приведены шаги, которые необходимо выполнить для создания первого приложения GitHub.

  1. Обновление разрешений приложения
  2. Добавление средств обработки событий
  3. Создание новой метки
  4. Добавление средств обработки меток

Шаг 1. Обновление разрешений приложения

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

Чтобы обновить разрешения приложения:

  1. Выберите приложение на странице параметров приложения и щелкните Разрешения и веб-перехватчики на боковой панели.
  2. В разделе "Разрешения" откройте пункт "Проблемы" и выберите Чтение и запись в раскрывающемся списке "Доступ" рядом с ним. В описании говорится, что этот параметр предоставляет разрешения для доступа как к проблемам, так и к меткам, а именно это вам и нужно.
  3. Чтобы подписаться на событие, выберите Проблемы в разделе "Подписка на события".
  4. Нажмите Сохранить изменения в нижней части страницы.
  5. Если вы установили приложение в своей учетной записи, проверьте свой почтовый ящик и перейдите по ссылке, чтобы принять новые разрешения. Каждый раз, когда вы изменяете разрешения или веб-перехватчики приложения, пользователи, которые установили приложение (включая вас самих), должны принять новые разрешения, прежде чем изменения вступят в силу. Чтобы принять новые разрешения, можно также перейти на страницу установки и щелкнуть "Настроить" рядом с приложением. В верхней части страницы появится баннер, сообщающий, что приложение запрашивает различные разрешения. Щелкните "Сведения" и нажмите "Принять новые разрешения".

Отлично! Ваше приложение имеет разрешение на выполнение необходимых задач. Теперь вы можете добавить код для его работы.

Шаг 2. Добавление средств обработки событий

Первое, что нужно сделать вашему приложению, — ожидать передачи данных для новых открытых проблем. Теперь, когда вы подписались на событие Issues (Проблемы), вы начнете получать веб-перехватчик issues, который активируется при возникновении определенных действий, связанных с проблемами. Этот тип события можно отфильтровать для конкретного действия в коде.

GitHub отправляет полезные данные веб-перехватчика в виде запросов POST. Так как вы перенаправили полезные данные веб-перехватчика Smee в http://localhost/event_handler:3000, сервер получит полезные данные запроса POST для маршрута post '/event_handler'.

Пустой маршрут post '/event_handler' уже включен в файл template_server.rb, который вы скачали в разделе предварительных требований. Пустой маршрут выглядит следующим образом:

  post '/event_handler' do

    # # # # # # # # # # # #
    # ADD YOUR CODE HERE  #
    # # # # # # # # # # # #

    200 # success status
  end

Используйте этот маршрут для обработки события issues, добавив следующий код:

case request.env['HTTP_X_GITHUB_EVENT']
when 'issues'
  if @payload['action'] === 'opened'
    handle_issue_opened_event(@payload)
  end
end

Каждое событие, которое отправляет GitHub, включает в себя заголовок запроса с именем HTTP_X_GITHUB_EVENT, который указывает тип события в запросе POST. Сейчас вас интересуют только типы событий issues. Каждое событие имеет дополнительное поле action, указывающее тип действия, которое активировало события. Для issues поле action может быть assigned, unassigned, labeled, unlabeled, opened, edited, milestoned, demilestoned, closed или reopened.

Чтобы протестировать обработчик событий, попробуйте добавить временный вспомогательный метод. Обновление выполните позже при работе с разделом Добавление средств обработки меток. Теперь в раздел кода helpers do добавьте следующий код. Новый метод можно поместить выше или ниже любого другого вспомогательного метода. Порядок не имеет значения.

def handle_issue_opened_event(payload)
  logger.debug 'An issue was opened!'
end

Этот метод получает полезные данные события в формате JSON в качестве аргумента. Это означает, что вы можете анализировать полезные данные в методе и детализировать все необходимые данные. Рекомендуем проверить все полезные данные: попробуйте изменить logger.debug 'An issue was opened! на logger.debug payload. Отображаемая структура полезных данных должна соответствовать тому, что показано в issuesдокументации по событиям веб-перехватчика.

Отлично! Пришло время проверить изменения.

Примечание. Прежде чем тестировать изменения, необходимо перезапустить сервер Sinatra. Введите Ctrl-C, чтобы остановить сервер, а затем снова выполните ruby template_server.rb. Если вы не хотите делать это при каждом изменении в коде приложения, можно использовать перезагрузку.

В браузере перейдите в репозиторий, в котором установлено приложение. Откройте новую проблему в этом репозитории. В проблеме можете указать все, что хотите. Это просто для тестирования.

Когда вы вернетесь к терминалу, то увидите сообщение в выходных данных: An issue was opened! Congrats! (Поздравляем!) Вы добавили обработчик событий в приложение. 💪

Шаг 3. Создание новой метки

Хорошо, ваше приложение может определить открытие проблем. Теперь вы хотите добавить метку needs-response к новой открытой проблеме в репозитории, где установлено приложение.

Перед добавлением метки в любое место необходимо создать пользовательскую метку в репозитории. Это нужно сделать только один раз. Для целей этого руководства создайте метку вручную на сайте GitHub. В репозитории щелкните Проблемы, затем Метки, а после этого выберите Новая метка. Назовите новую метку needs-response.

Совет. Было бы замечательно, если бы ваше приложение могло программно создать метку, не правда ли? Это возможно! Попробуйте добавить код самостоятельно после завершения действий, описанных в этом руководстве.

Теперь, когда есть метка, вы можете запрограммировать приложение, чтобы использовать REST API для добавления метки к любой только что открытой проблеме.

Шаг 4. Добавление средств обработки меток

Поздравляем! Вы добрались до последнего шага: добавление средства обработки меток в приложение. Для этой задачи необходимо использовать библиотеку Octokit.rb Ruby.

В документации по Octokit.rb найдите список методов для метки. Необходимый метод: add_labels_to_an_issue.

Вернитесь к template_server.rb и найдите метод, определенный ранее:

def handle_issue_opened_event(payload)
  logger.debug 'An issue was opened!'
end

В документации по add_labels_to_an_issue указано, что вам потребуется передать три аргумента в этот метод:

  • репозиторий (строка в формате "owner/name");
  • номер проблемы (целое число);
  • метки (массив).

Вы можете анализировать полезные данные, чтобы получить как репозиторий, так и номер проблемы. Так как имя метки всегда будет одинаковым (needs-response), его можно передать в виде жестко заданной строки в массиве меток. После объединения этих составляющих обновленный метод может выглядеть следующим образом:

# When an issue is opened, add a label
def handle_issue_opened_event(payload)
  repo = payload['repository']['full_name']
  issue_number = payload['issue']['number']
  @installation_client.add_labels_to_an_issue(repo, issue_number, ['needs-response'])
end

Попробуйте открыть новую проблему в тестовом репозитории и посмотрите, что произойдет! Если ничего не произойдет сразу, попробуйте обновить.

В терминале вы не увидите много, но заметите, что пользователь-бот добавил метку к проблеме.

Примечание. Когда приложения GitHub выполняют действия через API, например добавление меток, GitHub показывает эти действия как выполняемые учетными записями ботов. Дополнительные сведения см. в разделе Учетные записи компьютера и бота.

Если удалось, поздравляем! Вы успешно создали рабочее приложение! 🎉

Окончательный код можно увидеть в server.rb в репозитории шаблонов приложений.

В разделе Дальнейшие действия приведены идеи о том, что можно еще сделать.

Устранение неполадок

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

Заключение

После прохождения этого руководства вы узнали об основных стандартных блоках для разработки приложений GitHub! Для этого вы:

  • Запрограммировали приложение на ожидание передачи данных для событий.
  • Использовали библиотеку Octokit.rb для выполнения операций REST API.

Дальнейшие действия

Ниже приведены некоторые идеи о том, что еще можно сделать:

  • Перезаписать приложение с помощью GraphQL!
  • Перезаписать приложение в Node.js с помощью Probot!
  • Убедиться, что в проблеме уже существует метка needs-response, а если нет, то добавить ее.
  • Когда бот успешно добавит метку, отобразится сообщение в терминале. (Указание. Сравните идентификатор метки needs-response с идентификатором метки в полезных данных в качестве условия для сообщения, чтобы сообщение отображалось только при добавлении соответствующей метки, а не другой.)
  • Добавьте целевую страницу в приложение и подключите для нее маршрут Sinatra.
  • Переместите код на размещенный сервер (например, Heroku). Не забудьте обновить параметры приложения для нового домена.
  • Поделитесь проектом или получите совет в Обсуждения API и интеграции в сообществе GitHub