Теперь, когда мы понимаем основы веб-перехватчиков, давайте рассмотрим процесс создания собственной интеграции на основе веб-перехватчика. В этом руководстве мы создадим веб-перехватчик репозитория, который будет отвечать за создание списка популярных репозиториев в зависимости от количества проблем, которые он получает в день.
Создание веб-перехватчика — это двухэтапный процесс. Сначала необходимо настроить события, которые должен прослушивать ваш веб-перехватчик. После этого вы настроите сервер для получения полезных данных и управления ими.
REST API можно использовать для управления веб-перехватчиками репозитория, организации и приложения. Вы можете перечислить доставку веб-перехватчиков для веб-перехватчика или получить и повторно получить отдельную доставку для веб-перехватчика, которую можно интегрировать во внешнее приложение или службу. Вы также можете использовать REST API для изменения конфигурации веб-перехватчика. Например, можно изменить URL-адрес полезных данных, тип контента, проверку SSL и секрет. Дополнительные сведения см. в разделе:
Предоставление локального узла в Интернете
В рамках этого руководства мы будем использовать локальный сервер для получения событий веб-перехватчика от GitHub.
Прежде всего, необходимо предоставить локальную среду разработки в Интернете, чтобы GitHub доставить события. Мы будем использовать ngrok для этого.
Примечание: Кроме того, вы можете использовать перенаправление веб-перехватчиков, чтобы настроить локальную среду для получения веб-перехватчиков. Дополнительные сведения см. в разделе Получение веб-перехватчиков с помощью GitHub CLI.
ngrok предоставляется бесплатно для всех основных операционных систем. Дополнительные сведения см. на ngrokстранице загрузки.
После установки ngrok вы можете предоставить локальный узел, выполнив команду ./ngrok http 4567 в командной строке. 4567 — номер порта, по которому наш сервер будет ожидать передачи сообщений. Должна появиться строка, которая выглядит примерно так:
$ Forwarding http://7e9ea9dc.ngrok.io -> 127.0.0.1:4567Запишите URL-адрес *.ngrok.io. Мы будем использовать его для настройки веб-перехватчика.
Настройка веб-перехватчика
Веб-перехватчики можно установить в организации или в определенном репозитории.
Чтобы настроить веб-перехватчик, перейдите на страницу параметров репозитория или организации. После этого щелкните Веб-перехватчики, а затем выберите Добавить веб-перехватчик.
Кроме того, можно создать веб-перехватчик и управлять им с помощью API веб-перехватчиков.
Прежде чем веб-перехватчики можно будет использовать, в них требуется настроить несколько параметров конфигурации. Мы разберем каждый из этих параметров ниже.
URL-адрес полезных данных
Примечание. Веб-перехватчики GitHub в настоящее время не поддерживают протокол IPv6, но будут доступны в будущем. Конечная /meta точка REST API возвращает диапазоны IPv6, чтобы обеспечить этот переход.
URL-адрес полезных данных — это URL-адрес сервера, который будет получать запросы POST веб-перехватчика.
Так как мы выполняем разработку локально для нашего руководства, мы настроим его на URL-адрес *.ngrok.io, а затем /payload. Например, http://7e9ea9dc.ngrok.io/payload.
Тип содержимого
Веб-перехватчики могут доставляться с помощью разных типов содержимого:
- Тип содержимого
application/jsonпредоставляет полезные данные JSON непосредственно в виде текста запросаPOST. - Тип содержимого
application/x-www-form-urlencodedотправляет полезные данные JSON как параметр формы с именемpayload.
Выбирайте ту, что наилучшим образом подходит под ваши нужды. В рамках этого учебника достаточно выбрать тип содержимого по умолчанию application/json.
Секрет
Настройка секрета веб-перехватчика позволяет гарантировать, что запросы POST, отправленные на URL-адрес полезных данных, поступают из GitHub. При установке секрета вы будете получать заголовки X-Hub-Signature и X-Hub-Signature-256 в запросе POST веб-перехватчика. Дополнительные сведения об использовании секрета с заголовком подписи для защиты полезных данных веб-перехватчика см. в разделе Защита веб-перехватчиков.
Проверка SSL
Если "URL-адрес полезных данных" является защищенным сайтом (HTTPS), можно настроить параметры проверки SSL. Если "URL-адрес полезных данных" не является защищенным (HTTP), GitHub не отображает этот параметр. По умолчанию GitHub проверяет SSL-сертификат веб-сайта при доставке полезных данных веб-перехватчика. Проверка SSL помогает обеспечить безопасную доставку полезных данных веб-перехватчиков в конечную точку URL-адреса. Вы можете отключить SSL, однако параметр Включить проверку SSL рекомендуется всегда устанавливать.
Активен
По умолчанию доставки веб-перехватчика имеют статус "Активно". Вы можете отключить доставку полезных данных веб-перехватчика, отменив выбор статуса "Активный".
События
События — центральный компонент веб-перехватчиков. Эти веб-перехватчики запускаются всякий раз, когда определенное действие выполняется для репозитория, который URL-адрес полезных данных вашего сервера перехватывает и реагирует на него.
Полный список событий веб-перехватчика и условия, при которых они могут срабатывать, можно найти в справочнике по API веб-перехватчика.
Так как наш веб-перехватчик работает с проблемами в репозитории, мы нажмем кнопку Разрешить мне выбрать отдельные события, а затем Проблемы. Обязательно установите флажок Активен, чтобы получать события проблем для активированных веб-перехватчиков. Кроме того, можно выбрать все события с помощью команды по умолчанию.
После этого нажмите кнопку Добавить веб-перехватчик.
После создания веб-перехватчика пора настроить локальный сервер для тестирования веб-перехватчика. Перейдите к разделу Настройка сервера, чтобы узнать, как это сделать.
Событие с подстановочными знаками
Чтобы настроить веб-перехватчик для всех событий, используйте подстановочный знак (*) для указания событий веб-перехватчика. При добавлении события с подстановочными знаками мы заменим все настроенные существующие события, на события с подстановочными знаками, и отправим полезные данные для всех поддерживаемых событий. Вы также автоматически будете получать новые события, добавляемые в будущем.