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

Введение

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

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

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

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

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

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

• Приложения GitHub
• Объекты Webhook
• язык Ruby;
• REST API;
• Sinatra.

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

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

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.

Ниже приведены шаги, которые необходимо выполнить для создания первого приложения 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документации по событиям веб-перехватчика.

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

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

Когда вы вернетесь к терминалу, то увидите сообщение в выходных данных: 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 App добавил метку к проблеме.

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

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

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

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

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

• Вопрос. Что делать, если мой сервер не ожидает передачи данных событий? Клиент Smee работает в окне терминала, и я отправляю события на сайте GitHub.com, открыв новые проблемы, но не вижу выходных данных в окне терминала, где работает сервер.

  Ответ. Возможно, у вас неправильно указан домен Smee в параметрах приложения. Перейдите на страницу параметров приложения и дважды проверка поля, отображаемые в разделе "Настройка среды разработки для создания приложения GitHub". Убедитесь, что домен в этих полях соответствует домену, который использовался в smee -u <unique_channel> команде autoTITLE.

• Вопрос. Что делать, если мое приложение не работает? Я открыл новую проблему, но даже после обновления она без метки.

  Ответ. Убедитесь, что все из приведенных ниже условий выполняются:

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

Заключение

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

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

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

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

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