Skip to main content

Обработка доставки веб-перехватчика

Узнайте, как писать код для прослушивания и реагирования на поставки веб-перехватчика.

Введение

При создании веб-перехватчика необходимо указать URL-адрес и подписаться на типы событий. Когда происходит событие, на которое подписан веб-перехватчик, GitHub отправляет HTTP-запрос с данными о событии в указанный URL-адрес. Если сервер настроен для прослушивания доставки веб-перехватчиков по указанному URL-адресу, он может принять меры при получении одного.

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

Настройка

Для локального тестирования веб-перехватчика можно использовать URL-адрес прокси-сервера веб-перехватчика для пересылки веб-перехватчиков из GitHub на компьютер или пространство кода. В этой статье используется smee.io для предоставления URL-адреса прокси-сервера веб-перехватчика и перенаправления веб-перехватчиков.

Получение URL-адреса прокси-сервера веб-перехватчика

  1. В браузере перейдите по адресу https://smee.io/.
  2. Нажмите кнопку " Пуск нового канала".
  3. Скопируйте полный URL-адрес в разделе "URL-адрес прокси-сервера веб-перехватчика". Этот URL-адрес будет использоваться в следующих шагах установки.

Перенаправление веб-перехватчиков

  1. Если у вас еще нет see-client , выполните следующую команду в терминале:

    Shell
    npm install --global smee-client
    
  2. Чтобы получить перенаправленные веб-перехватчики из smee.io, выполните следующую команду в терминале. Замените WEBHOOK_PROXY_URL URL-адрес прокси-сервера веб-перехватчика ранее.

    Shell
    smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000
    

    Вы увидите выходные данные, которые выглядят следующим образом, где WEBHOOK_PROXY_URL находится URL-адрес прокси-сервера веб-перехватчика:

    Shell
    Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
    Connected WEBHOOK_PROXY_URL
    

    Обратите внимание, что путь есть /webhook и порт 3000. Эти значения будут использоваться позже при написании кода для обработки доставки веб-перехватчиков.

  3. Сохраните эту работу, пока вы тестируете веб-перехватчик. Если вы хотите прекратить перенаправление веб-перехватчиков, введите CTRL+C.

Создание веб-перехватчика

  1. Создайте веб-перехватчик со следующими параметрами. Дополнительные сведения см. в разделе Создание веб-перехватчиков.

    • Для URL-адреса используйте URL-адрес прокси-сервера веб-перехватчика из более ранних версий.
    • Если у вас есть возможность выбрать тип контента, используйте JSON.

Написание кода для обработки доставки веб-перехватчика

Чтобы обрабатывать поставки веб-перехватчика, необходимо написать код, который:

  • Инициализация сервера для прослушивания запросов к URL-адресу веб-перехватчика
  • Чтение заголовков и текста HTTP из запроса
  • Выполните требуемое действие в ответ на запрос

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

В следующих примерах выводится сообщение при получении доставки веб-перехватчика. Однако можно изменить код, чтобы выполнить другое действие, например выполнить запрос к API GitHub или отправить сообщение Slack.

Пример Ruby

В этом примере используется драгоценный камень Ruby, Sinatra, для определения маршрутов и обработки HTTP-запросов. Дополнительные сведения см. в Sinatra README.

Пример Ruby: установка зависимостей

Чтобы использовать этот пример, необходимо установить драгоценный камень Sinatra в проекте Ruby. Например, это можно сделать с помощью bundler:

  1. Если у вас еще нет пакета, выполните следующую команду в терминале:

    Shell
    gem install bundler
    
  2. Если у вас еще нет файла Gemfile для приложения, выполните следующую команду в терминале:

    Shell
    bundle init
    
  3. Если у вас еще нет файла Gemfile.lock для приложения, выполните следующую команду в терминале:

    Shell
    bundle install
    
  4. Установите драгоценный камень Sinatra, выполнив следующую команду в терминале:

    Shell
    bundle add sinatra
    

Пример Ruby: написание кода

Создайте файл Ruby со следующим содержимым. Измените код, чтобы обрабатывать типы событий, на которые подписан веб-перехватчик, а также ping событие, на которое GitHub отправляется при создании веб-перехватчика. В этом примере обрабатываются issues события и ping события.

Ruby
require 'sinatra'
require 'json'

These are the dependencies for this code. You installed the sinatra gem earlier. For more information, see "Ruby example: Install dependencies." The json library is a standard Ruby library, so you don't need to install it.

post '/webhook' do

The /webhook route matches the path that you specified for the smee.io forwarding. For more information, see "Forward webhooks."

Once you deploy your code to a server and update your webhook URL, you should change this to match the path portion of the URL for your webhook.

  status 202

Respond to indicate that the delivery was successfully received. Your server should respond with a 2XX response within 10 seconds of receiving a webhook delivery. If your server takes longer than that to respond, then GitHub terminates the connection and considers the delivery a failure.

  github_event = request.env['HTTP_X_GITHUB_EVENT']

Check the X-GitHub-Event header to learn what event type was sent. Sinatra changes X-GitHub-Event to HTTP_X_GITHUB_EVENT.

  if github_event == "issues"
    data = JSON.parse(request.body.read)
    action = data['action']
    if action == "opened"
      puts "An issue was opened with this title: #{data['issue']['title']}"
    elsif action == "closed"
      puts "An issue was closed by #{data['issue']['user']['login']}"
    else
      puts "Unhandled action for the issue event: #{action}"
    end
  elsif github_event == "ping"
    puts "GitHub sent the ping event"
  else
    puts "Unhandled event: #{github_event}"
  end
end

You should add logic to handle each event type that your webhook is subscribed to. For example, this code handles the issues and ping events.

If any events have an action field, you should also add logic to handle each action that you are interested in. For example, this code handles the opened and closed actions for the issue event.

For more information about the data that you can expect for each event type, see "События и полезные данные веб-перехватчика."

# These are the dependencies for this code. You installed the `sinatra` gem earlier. For more information, see "[Ruby example: Install dependencies](#ruby-example-install-dependencies)." The `json` library is a standard Ruby library, so you don't need to install it.
require 'sinatra'
require 'json'

# The `/webhook` route matches the path that you specified for the smee.io forwarding. For more information, see "[Forward webhooks](#forward-webhooks)."
#
# Once you deploy your code to a server and update your webhook URL, you should change this to match the path portion of the URL for your webhook.
post '/webhook' do

  # Respond to indicate that the delivery was successfully received.
  # Your server should respond with a 2XX response within 10 seconds of receiving a webhook delivery. If your server takes longer than that to respond, then GitHub terminates the connection and considers the delivery a failure.
  status 202

  # Check the `X-GitHub-Event` header to learn what event type was sent.
  # Sinatra changes `X-GitHub-Event` to `HTTP_X_GITHUB_EVENT`.
  github_event = request.env['HTTP_X_GITHUB_EVENT']

  # You should add logic to handle each event type that your webhook is subscribed to.
  # For example, this code handles the `issues` and `ping` events.
  #
  # If any events have an `action` field, you should also add logic to handle each action that you are interested in.
  # For example, this code handles the `opened` and `closed` actions for the `issue` event.
  #
  # For more information about the data that you can expect for each event type, see "[AUTOTITLE](/webhooks/webhook-events-and-payloads)."
  if github_event == "issues"
    data = JSON.parse(request.body.read)
    action = data['action']
    if action == "opened"
      puts "An issue was opened with this title: #{data['issue']['title']}"
    elsif action == "closed"
      puts "An issue was closed by #{data['issue']['user']['login']}"
    else
      puts "Unhandled action for the issue event: #{action}"
    end
  elsif github_event == "ping"
    puts "GitHub sent the ping event"
  else
    puts "Unhandled event: #{github_event}"
  end
end

Пример Ruby: тестирование кода

Чтобы протестировать веб-перехватчик, можно использовать компьютер или пространство кода для работы в качестве локального сервера. Если у вас возникли проблемы с этими инструкциями, см . статью "Устранение неполадок".

  1. Убедитесь, что вы переадресуете веб-перехватчики. Если вы больше не перенаправляете веб-перехватчики, выполните действия, описанные в разделе "Переадресация веб-перехватчиков ".

  2. В отдельном окне терминала выполните следующую команду, чтобы запустить локальный сервер на компьютере или в пространстве кода. Замените FILE_PATH путь к файлу, в котором хранится код из предыдущего раздела. Обратите внимание, что PORT=3000 соответствует порту, указанному для переадресации веб-перехватчика на предыдущем шаге.

    Shell
    PORT=3000 ruby FILE_NAME
    

    Вы должны увидеть выходные данные, указывающие на то, что "Sinatra занял этап на 3000".

  3. Активируйте веб-перехватчик. Например, если вы создали веб-перехватчик репозитория, подписанный issues на событие, откройте проблему в репозитории. Вы также можете переделить предыдущую доставку веб-перехватчика. Дополнительные сведения см. в разделе Повторное создание веб-перехватчиков.

  4. Перейдите по URL-адресу прокси-сервера веб-перехватчика на smee.io. Должно появиться событие, соответствующее событию, которое вы активировали или перевели. Это означает, что GitHub успешно отправил доставку веб-перехватчика в указанный URL-адрес полезных данных.

  5. В окне терминала, где вы выполнили, smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000вы должны увидеть что-то подобное POST http://127.0.0.1:3000/webhook - 202. Это означает, что smee успешно перенаправил веб-перехватчик на локальный сервер.

  6. В окне терминала, на котором вы выполнили, PORT=3000 ruby FILE_NAMEпоявится сообщение, соответствующее событию, которое было отправлено. Например, если вы используете пример кода из выше, и вы повторно создали ping событие, должно появиться сообщение "GitHub отправило событие ping". Вы также можете увидеть некоторые другие строки, которые Sinatra автоматически печатает.

  7. В обоих окнах терминала введите CTRL+C, чтобы остановить локальный сервер и прекратить прослушивание перенаправленных веб-перехватчиков.

Теперь, когда вы протестировали код локально, вы можете внести изменения в использование веб-перехватчика в рабочей среде. Дополнительные сведения см. в разделе "Дальнейшие действия". Если у вас возникли проблемы с тестированием кода, выполните действия, описанные в разделе "Устранение неполадок".

Пример JavaScript

В этом примере используется Node.js и библиотека Express для определения маршрутов и обработки HTTP-запросов. Дополнительные сведения см. в разделе "expressjs.com".

Пример, использующий пакет SDK Octokit.js %}данных GitHub, см. в разделе "Создание приложения GitHub, реагирующего на события веб-перехватчика".

В этом примере требуется, чтобы компьютер или пространство кода выполнялось Node.js версии 12 или более поздней и npm версии 6.12.0 или более поздней. Дополнительные сведения см. в Node.js.

Пример JavaScript: установка зависимостей

Чтобы использовать этот пример, необходимо установить библиотеку express в проекте Node.js. Например:

Shell
npm install express

Пример JavaScript: написание кода

Создайте файл JavaScript со следующим содержимым. Измените код, чтобы обрабатывать типы событий, на которые подписан веб-перехватчик, а также ping событие, на которое GitHub отправляется при создании веб-перехватчика. В этом примере обрабатываются issues события и ping события.

JavaScript
const express = require('express');

You installed the express library earlier. For more information, see "JavaScript example: Install dependencies."

const app = express();

This initializes a new Express application.

app.post('/webhook', express.json({type: 'application/json'}), (request, response) => {

This defines a POST route at the /webhook path. This path matches the path that you specified for the smee.io forwarding. For more information, see "Forward webhooks."

Once you deploy your code to a server and update your webhook URL, you should change this to match the path portion of the URL for your webhook.

  response.status(202).send('Accepted');

Respond to indicate that the delivery was successfully received. Your server should respond with a 2XX response within 10 seconds of receiving a webhook delivery. If your server takes longer than that to respond, then GitHub terminates the connection and considers the delivery a failure.

  const githubEvent = request.headers['x-github-event'];

Check the x-github-event header to learn what event type was sent.

  if (githubEvent === 'issues') {
    const data = request.body;
    const action = data.action;
    if (action === 'opened') {
      console.log(`An issue was opened with this title: ${data.issue.title}`);
    } else if (action === 'closed') {
      console.log(`An issue was closed by ${data.issue.user.login}`);
    } else {
      console.log(`Unhandled action for the issue event: ${action}`);
    }
  } else if (githubEvent === 'ping') {
    console.log('GitHub sent the ping event');
  } else {
    console.log(`Unhandled event: ${githubEvent}`);
  }
});

You should add logic to handle each event type that your webhook is subscribed to. For example, this code handles the issues and ping events.

If any events have an action field, you should also add logic to handle each action that you are interested in. For example, this code handles the opened and closed actions for the issue event.

For more information about the data that you can expect for each event type, see "События и полезные данные веб-перехватчика."

const port = 3000;

This defines the port where your server should listen. 3000 matches the port that you specified for webhook forwarding. For more information, see "Forward webhooks."

Once you deploy your code to a server, you should change this to match the port where your server is listening.

app.listen(port, () => {
  console.log(`Server is running on port ${port}`);
});

This starts the server and tells it to listen at the specified port.

// You installed the `express` library earlier. For more information, see "[JavaScript example: Install dependencies](#javascript-example-install-dependencies)."
const express = require('express');

// This initializes a new Express application.
const app = express();

// This defines a POST route at the `/webhook` path. This path matches the path that you specified for the smee.io forwarding. For more information, see "[Forward webhooks](#forward-webhooks)."
//
// Once you deploy your code to a server and update your webhook URL, you should change this to match the path portion of the URL for your webhook.
app.post('/webhook', express.json({type: 'application/json'}), (request, response) => {

  // Respond to indicate that the delivery was successfully received.
  // Your server should respond with a 2XX response within 10 seconds of receiving a webhook delivery. If your server takes longer than that to respond, then GitHub terminates the connection and considers the delivery a failure.
  response.status(202).send('Accepted');

  // Check the `x-github-event` header to learn what event type was sent.
  const githubEvent = request.headers['x-github-event'];

  // You should add logic to handle each event type that your webhook is subscribed to.
  // For example, this code handles the `issues` and `ping` events.
  //
  // If any events have an `action` field, you should also add logic to handle each action that you are interested in.
  // For example, this code handles the `opened` and `closed` actions for the `issue` event.
  //
  // For more information about the data that you can expect for each event type, see "[AUTOTITLE](/webhooks/webhook-events-and-payloads)."
  if (githubEvent === 'issues') {
    const data = request.body;
    const action = data.action;
    if (action === 'opened') {
      console.log(`An issue was opened with this title: ${data.issue.title}`);
    } else if (action === 'closed') {
      console.log(`An issue was closed by ${data.issue.user.login}`);
    } else {
      console.log(`Unhandled action for the issue event: ${action}`);
    }
  } else if (githubEvent === 'ping') {
    console.log('GitHub sent the ping event');
  } else {
    console.log(`Unhandled event: ${githubEvent}`);
  }
});

// This defines the port where your server should listen.
// 3000 matches the port that you specified for webhook forwarding. For more information, see "[Forward webhooks](#forward-webhooks)."
//
// Once you deploy your code to a server, you should change this to match the port where your server is listening.
const port = 3000;

// This starts the server and tells it to listen at the specified port.
app.listen(port, () => {
  console.log(`Server is running on port ${port}`);
});

Пример JavaScript: тестирование кода

Чтобы протестировать веб-перехватчик, можно использовать компьютер или пространство кода для работы в качестве локального сервера. Если у вас возникли проблемы с этими инструкциями, см . статью "Устранение неполадок".

  1. Убедитесь, что вы переадресуете веб-перехватчики. Если вы больше не перенаправляете веб-перехватчики, выполните действия, описанные в разделе "Переадресация веб-перехватчиков ".

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

    Shell
    node FILE_NAME
    

    Вы должны увидеть выходные данные, которые говорят Server is running on port 3000.

  3. Активируйте веб-перехватчик. Например, если вы создали веб-перехватчик репозитория, подписанный issues на событие, откройте проблему в репозитории. Вы также можете переделить предыдущую доставку веб-перехватчика. Дополнительные сведения см. в разделе Повторное создание веб-перехватчиков.

  4. Перейдите по URL-адресу прокси-сервера веб-перехватчика на smee.io. Должно появиться событие, соответствующее событию, которое вы активировали или перевели. Это означает, что GitHub успешно отправил доставку веб-перехватчика в указанный URL-адрес полезных данных.

  5. В окне терминала, где вы выполнили, smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000вы должны увидеть что-то подобное POST http://127.0.0.1:3000/webhook - 202. Это означает, что smee успешно перенаправил веб-перехватчик на локальный сервер.

  6. В окне терминала, на котором вы выполнили, node FILE_NAMEпоявится сообщение, соответствующее событию, которое было отправлено. Например, если вы используете пример кода из выше, и вы повторно создали ping событие, должно появиться сообщение "GitHub отправило событие ping".

  7. В обоих окнах терминала введите CTRL+C, чтобы остановить локальный сервер и прекратить прослушивание перенаправленных веб-перехватчиков.

Теперь, когда вы протестировали код локально, вы можете внести изменения в использование веб-перехватчика в рабочей среде. Дополнительные сведения см. в разделе "Дальнейшие действия". Если у вас возникли проблемы с тестированием кода, выполните действия, описанные в разделе "Устранение неполадок".

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

Если ожидаемые результаты, описанные в шагах тестирования, не отображаются, попробуйте следующее:

  • Убедитесь, что веб-перехватчик использует URL-адрес прокси-сервера веб-перехватчика (Smee.io URL-адрес). Дополнительные сведения о URL-адресе прокси-сервера веб-перехватчика см. в разделе "Получение URL-адреса прокси-сервера веб-перехватчика". Дополнительные сведения о параметрах веб-перехватчика см. в разделе "Создание веб-перехватчиков".
  • Убедитесь, что веб-перехватчик использует тип контента JSON, если у вас есть выбор типа контента для использования. Дополнительные сведения о параметрах веб-перехватчика см. в разделе "Создание веб-перехватчиков".
  • Убедитесь, что запущен как клиент smee, так и локальный сервер. Эти процессы выполняются в двух отдельных окнах терминала.
  • Убедитесь, что сервер прослушивает тот же порт, где smee.io перенаправляет веб-перехватчики. Все примеры в этой статье используют порт 3000.
  • Убедитесь, что путь, в котором smee.io перенаправляет веб-перехватчики, соответствует маршруту, определенному в коде. Все примеры, приведенные в этой статье, используют /webhooks путь.
  • Проверьте наличие сообщений об ошибках в окнах терминала, где выполняется клиент smee и локальный сервер.
  • Проверьте GitHub, чтобы убедиться, что доставка веб-перехватчика была активирована. Дополнительные сведения см. в разделе Просмотр доставленных данных веб-перехватчика.
  • Проверьте URL-адрес прокси-сервера веб-перехватчика на smee.io. Должно появиться событие, соответствующее событию, которое вы активировали или перевели. Это означает, что GitHub успешно отправил доставку веб-перехватчика в указанный URL-адрес полезных данных.

Следующие шаги

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

вносит изменения в код;

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

  • Выполните запрос к API GitHub
  • Отправка сообщения в Slack
  • События журнала
  • Обновление внешнего средства управления проектами

Убедитесь, что доставка получена из GitHub

В коде, обрабатывающем поставки веб-перехватчика, необходимо убедиться, что доставка от GitHub перед дальнейшей обработкой доставки. Дополнительные сведения см. в разделе Проверка доставки веб-перехватчика.

Развертывание кода на сервере

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

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

Обновление URL-адреса веб-перехватчика

После установки сервера для получения трафика веб-перехватчика из GitHubобновите URL-адрес в параметрах веб-перехватчика. Возможно, потребуется обновить маршрут, который обрабатывает код, чтобы соответствовать части пути нового URL-адреса. Например, если новый URL-адрес веб-перехватчика имеет значение https://example.com/github-webhooks, необходимо изменить маршрут в этих примерах на /webhooks /github-webhooks.

Не следует использовать smee.io для пересылки веб-перехватчиков в рабочей среде.

Применение рекомендаций

Вы должны стремиться следовать рекомендациям с веб-перехватчиками. Дополнительные сведения см. в разделе Рекомендации по использованию веб-перехватчиков.

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