Использование веб-перехватчика в качестве триггера для Azure Logic Apps и Power Automate
Веб-перехватчики — это простые обратные вызовы HTTP, используемые для уведомлений о событиях. Как в Azure Logic Apps, так и в Power Automate веб-перехватчики можно использовать в качестве триггеров. Приложение логики или поток прослушивает этот триггер и выполняет действие при каждом срабатывании триггера. В этом учебнике демонстрируется, как использовать веб-перехватчик в качестве триггера.
Примечание
Мы будем использовать GitHub в качестве примера службы, которая может отправлять уведомления с помощью веб-перехватчиков. Но методики, продемонстрированные здесь, можно применять в любой службе, использующей веб-перехватчики.
Предварительные условия
- Одна из следующих подписок:
- Azure, если вы используете Logic Apps
- Power Automate
- Базовый опыт построения приложений логики или потоков, и пользовательских соединителей.
- Если вы используете Logic Apps, прежде всего создайте пользовательский соединитель Azure Logic Apps.
- Общее представление о веб-перехватчиках.
- Базовое понимание Технических характеристик OpenAPI (ранее известного как Swagger).
- Учетная запись GitHub.
- Пример определения OpenAPI для этого руководства.
Определение OpenAPI
Веб-перехватчики реализованы в Logic Apps и Power Automate в составе пользовательского соединителя. Следовательно, вам нужно указать определение OpenAPI для описания формы веб-перехватчика. Если вы хотите создать триггер, но у вас нет определения OpenAPI, вы можете использовать пользовательский интерфейс триггеров в мастере настраиваемых соединителей, чтобы определить триггеры веб-перехватчиков.
Каждое определение OpenAPI состоит из следующих трех частей, необходимых для функционирования веб-перехватчика:
- Создание веб-перехватчика
- Определение входящего запроса hook из API (в данном случае — GitHub).
- Удаление веб-перехватчика
Создание веб-перехватчика
Веб-перехватчик создается на стороне GitHub путем HTTP-запроса POST к /repos/{owner}/{repo}/hooks
. Когда создается новое приложение логики или поток, публикация происходит по этому URL-адресу с помощью триггера, определенного в определении OpenAPI. Оно также публикует на URL-адресе, если триггер изменен. В примере ниже свойство post
содержит схему запроса, который отправляется на GitHub.
"/repos/{owner}/{repo}/hooks": {
"x-ms-notification-content": {
"description": "Details for Webhook",
"schema": {
"$ref": "#/definitions/WebhookPushResponse"
}
},
"post": {
"description": "Creates a Github webhook",
"summary": "Triggers when a PUSH event occurs",
"operationId": "webhook-trigger",
"x-ms-trigger": "single",
"parameters": [
{
"name": "owner",
"in": "path",
"description": "Name of the owner of targeted repository",
"required": true,
"type": "string"
},
{
"name": "repo",
"in": "path",
"description": "Name of the repository",
"required": true,
"type": "string"
},
{
"name": "Request body of webhook",
"in": "body",
"description": "This is the request body of the Webhook",
"schema": {
"$ref": "#/definitions/WebhookRequestBody"
}
}
],
"responses": {
"201": {
"description": "Created",
"schema": {
"$ref": "#/definitions/WebhookCreationResponse"
}
}
}
}
},
Важно!
Свойство "x-ms-trigger": "single"
представляет собой расширение схемы, которое обязательно нужно использовать. Оно сообщает Logic Apps и Power Automate, что этот веб-перехватчик нужно показывать в списке доступных триггеров в конструкторе.
Определение входящего запроса перехватчика из API
Форма входящего запроса перехватчика (уведомления от GitHub к Logic Apps или Power Automate) определяется в пользовательском свойстве x-ms-notification-content
, как показано в предыдущем примере. Это свойство не должно содержать все содержимое запроса, а только части, которые вы хотите использовать в своем приложении логики или потоке.
Удаление веб-перехватчика
Определение OpenAPI должно включать определение того, как удалить веб-перехватчик. Logic Apps и Power Automate пытаются удалить веб-перехватчик при обновлении триггера, а также при удалении приложения логики или потока.
"/repos/{owner}/{repo}/hooks/{hook_Id}": {
"delete": {
"description": "Deletes a Github webhook",
"operationId": "DeleteTrigger",
"parameters": [
{
"name": "owner",
"in": "path",
"description": "Name of the owner of targeted repository",
"required": true,
"type": "string"
},
{
"name": "repo",
"in": "path",
"description": "Name of the repository",
"required": true,
"type": "string"
},
{
"name": "hook_Id",
"in": "path",
"description": "ID of the Hook being deleted",
"required": true,
"type": "string"
}
]
}
},
Дополнительный заголовок для вызова удаления веб-перехватчика не включается. То же подключение, которое используется в соединителе, также используется для вызова веб-перехватчика удаления.
Важно!
Чтобы Logic Apps и Power Automate могли успешно удалить веб-перехватчик, API обязательно должен передать заголовок HTTP Location
в ответе 201, который он возвращает при создании веб-перехватчика. Заголовок Location
должен содержать путь к веб-перехватчику, который используется с HTTP-запросом DELETE. Например, Location
в составе ответа GitHub имеет следующий формат: https://api.github.com/repos/<user name>/<repo name>/hooks/<hook ID>
.
Включение аутентификации в GitHub
В API, который отправляет запрос веб-перехватчика в Logic Apps и Power Automate, используется тот или иной механизм аутентификации. GitHub в этом отношении — не исключение. GitHub поддерживает несколько типов аутентификации; в рамках этого учебника мы будем использовать личные маркеры доступа GitHub.
Перейдите на сайт GitHub и выполните вход, если вы еще этого не сделали.
В правом верхнем углу выберите свое изображение профиля и выберите в меню Параметры.
В меню слева выберите Параметры разработчика, затем выберите Личные маркеры доступа.
Выберите кнопку Создать новый токен, затем подтвердите свой пароль, если он запрошен.
В поле Описание маркера введите описание.
Установите флажок admin:repo_hook.
Выберите кнопку Создать маркер.
Запишите свой новый маркер.
Важно!
Вы больше не сможете получить доступ к этому маркеру. Скопируйте и сохраните его где-то, чтобы использовать позже в этом руководстве.
Импорт определения OpenAPI
Сначала импортируйте определение OpenAPI для Logic Apps или для Power Automate.
Импорт определения OpenAPI для Logic Apps
Откройте портал Azure, найдите и откройте соединитель Logic Apps, который вы создали при работе с руководством по созданию настраиваемого соединителя в Azure Logic Apps.
В меню вашего соединителя выберите Соединитель Logic Apps, затем выберите Редактировать.
В разделе Общее выберите Передать файл OpenAPI, а затем перейдите к загруженному файлу OpenAPI.
Импорт определения OpenAPI для Power Automate
Перейдите на сайт flow.microsoft.com.
В правом верхнем углу выберите значок шестеренки, затем — Настраиваемые соединители.
Выберите Создать пользовательский соединитель, а затем выберите Импортировать коллекцию Postman.
Введите имя настраиваемого соединителя, затем перейдите к загруженному вами файлу OpenAPI и выберите Подключить.
Параметр Значение Название настраиваемого соединителя "GitHubDemo"
Завершение создания пользовательского соединителя
На странице Общее выберите Продолжить.
На странице Безопасность в разделе Тип аутентификации выберите Базовая аутентификация.
В разделе Обычная проверка подлинности для полей меток введите текст Имя пользователя и Пароль. При использовании триггера в потоке или приложении логики будут отображаться только эти метки.
Убедитесь, что в верхней части окна мастера указано имя "GitHubDemo", затем выберите Создать соединитель.
Теперь вы готовы использовать триггер в приложении логики или потоке или вы можете прочитать о том, как создавать триггеры из пользовательского интерфейса.
Создание триггеров веб-перехватчика из пользовательского интерфейса
В этом разделе мы покажем, как создать триггер в пользовательском интерфейсе без каких-либо определений триггера в вашем определении OpenAPI. Начните с базового определения OpenAPI или начните с нуля в мастере настраиваемых соединителей.
На странице Общие убедитесь, что указаны описание и URL-адрес.
Параметр Value Описание "GitHub — это социальный репозиторий исходного кода". URL-адрес "api.github.com" На странице Безопасность настройте базовую аутентификацию, как вы делали в предыдущем разделе.
На странице Определение выберите + Создать триггер и заполните описание вашего триггера. В этом примере создается триггер, срабатывающий при запросе на вытягивание в репозитории.
Параметр Value Сводка "Срабатывает, когда делается запрос на извлечение в выбранный репозиторий" Описание "Срабатывает, когда делается запрос на извлечение в выбранный репозиторий" Идентификатор операции "webhook-PR-trigger" Видимость "none" (дополнительные сведения см. ниже) Тип триггера "Веб-перехватчик" Свойство Видимость для операций и параметров в приложении логики или потоке имеет следующие параметры:
- нет: обычно отображается в приложении логики или потоке
- расширенная: скрыто в дополнительном меню
- внутренняя: скрыто от пользователя
- важная: всегда сначала предоставляется пользователю для просмотра
Область Запрос отображает информацию на основе HTTP-запроса на действие. Выберите Импорт из примера.
Определите запрос для триггера веб-перехватчика и выберите действие Импорт. Мы предоставляем образец для импорта (ниже изображения). Дополнительные сведения см. в разделе Справочник по API GitHub. Logic Apps и Power Automate автоматически добавляют стандартные заголовки
content-type
и заголовки безопасности, поэтому их не нужно определять при импорте из примера.Параметр Value Команда "POST" URL-адрес "https://api.github.com/repos/{owner}/{repo}/hooks" Текст См. ниже { "name": "web", "active": true, "events": [ "pull_request" ], "config": { "url": "http://example.com/webhook" } }
Область Ответ отображает информацию на основе HTTP-ответа для действия. Выберите Добавить ответ по умолчанию.
Определите ответ для триггера веб-перехватчика и выберите действие Импорт. Опять, мы предоставляем образец для импорта. Дополнительные сведения см. в разделе Справочник по API GitHub.
{ "action": "opened", "number": 1, "pull_request": { "html_url": "https://github.com/baxterthehacker/public-repo/pull/1", "state": "open", "locked": false, "title": "Update the README with new information", "user": { "login": "baxterthehacker", "type": "User" } } }
В области Конфигурация триггера выберите параметр, который должен получить значение URL-адреса обратного вызова из GitHub. Эти свойство
url
в объектеconfig
.В верхней части мастера введите имя, затем выберите Создать соединитель.
Использование веб-перехватчика в качестве триггера
Теперь настроены все необходимые параметры и можно применить веб-перехватчик в приложении логики или в потоке. Далее создайте поток, который будет отправлять push-уведомление в мобильное приложение Power Automate каждый раз, когда репозиторий GitHub будет получать отправку git.
В flow.microsoft.com в верхней части страницы выберите Мои потоки.
Выберите Создать с нуля, затем на следующей странице выберите Поиск среди сотен соединителей и триггеров.
В конструкторе Power Automate найдите настраиваемый соединитель, который вы зарегистрировали ранее.
Выберите элемент в списке, чтобы использовать его в качестве триггера.
Так как этот настраиваемый соединитель будет использоваться впервые, к нему нужно подключиться. Введите информацию о соединении, затем выберите Создать.
Параметр Value Имя подключения Описательное имя Имя пользователя Ваше имя пользователя GitHub Пароль Личный маркер доступа, который вы создали ранее Введите сведения о репозитории, который хотите отслеживать. В объекте WebhookRequestBody в файле OpenAPI вы увидите знакомые поля.
Параметр Стоимость владелец Владелец репозитория для мониторинга репозиторий Репозиторий для мониторинга Важно!
Используйте репозиторий, к которому имеет доступ ваша учетная запись. Проще всего использовать собственный репозиторий.
Выберите + Новый шаг, а затем — Добавить действие.
Найдите и выберите действие Push-уведомление.
Введите некоторый текст в поле Текст и другие поля, используя значения из диалогового окна динамического содержимого. Обратите внимание, что эти значения взяты из объекта WebhookPushResponse в файле OpenAPI.
Параметр Стоимость Имя подключения Описательное имя Имя пользователя Ваше имя пользователя GitHub Пароль Личный маркер доступа, который вы создали ранее В верхней части страницы присвойте потоку имя и выберите Создать поток.
Проверка и устранение неполадок
Чтобы убедиться, все настроено правильно, выберите Мои потоки, а затем выберите значок сведений рядом с новым потоком, чтобы просмотреть журнал запусков:
Вы должны увидеть как минимум одно успешное выполнение (Succeeded) с момента создания веб-перехватчика. Это означает, что веб-перехватчик успешно создан на стороне GitHub.
Если выполнение завершилось ошибкой, вы можете перейти сведениям о выполнении, чтобы узнать причину сбоя. Если ошибка возникла из-за ответа "404 — не найдено", вполне вероятно, что у учетной записи GitHub нет разрешений на создание веб-перехватчика в репозитории, который использовался.
Сводка
Если все настроено правильно, вы будете получать push-уведомления в мобильном приложении Power Automate при каждой отправке git в выбранный репозиторий GitHub. Следуя описанным выше инструкциям, можно использовать любую службу с поддержкой веб-перехватчика в качестве триггера потоков.
Дальнейшие шаги
- Создание пользовательского соединителя для веб-API
- Аутентификация API и соединителя с помощью Microsoft Entra ID
Предоставление отзывов
Для нас очень важны отзывы о проблемах с нашей платформой соединителей и новые идеи о функциях. Чтобы оставить отзыв, выберите пункт Сообщить о проблемах или получить помощь с соединителями и выберите тип отзыва.