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

Введение

При создании веб-перехватчика необходимо указать 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
• Пример JavaScript

Пример 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 события.

# 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 30 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

require 'sinatra'
require 'json'

post '/webhook' do

  status 202

  github_event = request.env['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

# 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 30 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. Например:

npm install express

npm install express

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

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

// 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 30 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}`);
});

const express = require('express');

const app = express();

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

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

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

  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}`);
  }
});

const port = 3000;

app.listen(port, () => {
  console.log(`Server is running on port ${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 30 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 для пересылки веб-перехватчиков в рабочей среде.

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

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

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

• "Создание приложения GitHub, реагирующего на события веб-перехватчика"
• "Рекомендации по использованию веб-перехватчиков"