Использование веб-перехватчика в качестве триггера для Azure Logic Apps и Power Automate

  • Статья

Веб-перехватчики — это простые обратные вызовы HTTP, используемые для уведомлений о событиях. Как в Azure Logic Apps, так и в Power Automate веб-перехватчики можно использовать в качестве триггеров. Приложение логики или поток прослушивает этот триггер и выполняет действие при каждом срабатывании триггера. В этом учебнике демонстрируется, как использовать веб-перехватчик в качестве триггера.

Примечание

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

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

Определение 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.

  1. Перейдите на сайт GitHub и выполните вход, если вы еще этого не сделали.

  2. В правом верхнем углу выберите свое изображение профиля и выберите в меню Параметры.

    Настройки

  3. В меню слева выберите Параметры разработчика, затем выберите Личные маркеры доступа.

  4. Выберите кнопку Создать новый токен, затем подтвердите свой пароль, если он запрошен.

    Создание нового маркера

  5. В поле Описание маркера введите описание.

  6. Установите флажок admin:repo_hook.

    admin:repo_hook

  7. Выберите кнопку Создать маркер.

  8. Запишите свой новый маркер.

    Новый маркер

    Важно!

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

Импорт определения OpenAPI

Сначала импортируйте определение OpenAPI для Logic Apps или для Power Automate.

Импорт определения OpenAPI для Logic Apps

  1. Откройте портал Azure, найдите и откройте соединитель Logic Apps, который вы создали при работе с руководством по созданию настраиваемого соединителя в Azure Logic Apps.

  2. В меню вашего соединителя выберите Соединитель Logic Apps, затем выберите Редактировать.

    Редактирование соединителя Logic Apps

  3. В разделе Общее выберите Передать файл OpenAPI, а затем перейдите к загруженному файлу OpenAPI.

    Снимок экрана, показывающий параметр Передать файл OpenAPI.

Импорт определения OpenAPI для Power Automate

  1. Перейдите на сайт flow.microsoft.com.

  2. В правом верхнем углу выберите значок шестеренки, затем — Настраиваемые соединители.

    Пользовательские соединители

  3. Выберите Создать пользовательский соединитель, а затем выберите Импортировать коллекцию Postman.

    Создание настраиваемого соединителя

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

    Снимок экрана, на котором показано поле для ввода имени.

    Параметр Значение
    Название настраиваемого соединителя "GitHubDemo"

Завершение создания пользовательского соединителя

  1. На странице Общее выберите Продолжить.

  2. На странице Безопасность в разделе Тип аутентификации выберите Базовая аутентификация.

  3. В разделе Обычная проверка подлинности для полей меток введите текст Имя пользователя и Пароль. При использовании триггера в потоке или приложении логики будут отображаться только эти метки.

    Обычная проверка подлинности

  4. Убедитесь, что в верхней части окна мастера указано имя "GitHubDemo", затем выберите Создать соединитель.

Теперь вы готовы использовать триггер в приложении логики или потоке или вы можете прочитать о том, как создавать триггеры из пользовательского интерфейса.

Создание триггеров веб-перехватчика из пользовательского интерфейса

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

  1. На странице Общие убедитесь, что указаны описание и URL-адрес.

    Параметр Value
    Описание "GitHub — это социальный репозиторий исходного кода".
    URL-адрес "api.github.com"

  2. На странице Безопасность настройте базовую аутентификацию, как вы делали в предыдущем разделе.

  3. На странице Определение выберите + Создать триггер и заполните описание вашего триггера. В этом примере создается триггер, срабатывающий при запросе на вытягивание в репозитории.

    Создание триггера — 1

    Параметр Value
    Сводка "Срабатывает, когда делается запрос на извлечение в выбранный репозиторий"
    Описание "Срабатывает, когда делается запрос на извлечение в выбранный репозиторий"
    Идентификатор операции "webhook-PR-trigger"
    Видимость "none" (дополнительные сведения см. ниже)
    Тип триггера "Веб-перехватчик"

    Свойство Видимость для операций и параметров в приложении логики или потоке имеет следующие параметры:

    • нет: обычно отображается в приложении логики или потоке
    • расширенная: скрыто в дополнительном меню
    • внутренняя: скрыто от пользователя
    • важная: всегда сначала предоставляется пользователю для просмотра

  4. Область Запрос отображает информацию на основе HTTP-запроса на действие. Выберите Импорт из примера.

    Страница определения — импорт из примера

  5. Определите запрос для триггера веб-перехватчика и выберите действие Импорт. Мы предоставляем образец для импорта (ниже изображения). Дополнительные сведения см. в разделе Справочник по API GitHub. Logic Apps и Power Automate автоматически добавляют стандартные заголовки content-type и заголовки безопасности, поэтому их не нужно определять при импорте из примера.

    Создание триггера — 2

    Параметр Value
    Команда "POST"
    URL-адрес "https://api.github.com/repos/{owner}/{repo}/hooks"
    Текст См. ниже 
    {
  "name": "web",
  "active": true,
  "events": [
    "pull_request"
  ],
  "config": {
    "url": "http://example.com/webhook"
  }
}

  6. Область Ответ отображает информацию на основе HTTP-ответа для действия. Выберите Добавить ответ по умолчанию.

    Страница определения — ответ

  7. Определите ответ для триггера веб-перехватчика и выберите действие Импорт. Опять, мы предоставляем образец для импорта. Дополнительные сведения см. в разделе Справочник по API GitHub.

    Создание триггера — 3

    {
  "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"
    }
  }
}

  8. В области Конфигурация триггера выберите параметр, который должен получить значение URL-адреса обратного вызова из GitHub. Эти свойство url в объекте config.

    Создание триггера — 4

  9. В верхней части мастера введите имя, затем выберите Создать соединитель.

Использование веб-перехватчика в качестве триггера

Теперь настроены все необходимые параметры и можно применить веб-перехватчик в приложении логики или в потоке. Далее создайте поток, который будет отправлять push-уведомление в мобильное приложение Power Automate каждый раз, когда репозиторий GitHub будет получать отправку git.

  1. В flow.microsoft.com в верхней части страницы выберите Мои потоки.

  2. Выберите Создать с нуля, затем на следующей странице выберите Поиск среди сотен соединителей и триггеров.

    Поиск соединителей

  3. В конструкторе Power Automate найдите настраиваемый соединитель, который вы зарегистрировали ранее.

    Новый триггер

    Выберите элемент в списке, чтобы использовать его в качестве триггера.

  4. Так как этот настраиваемый соединитель будет использоваться впервые, к нему нужно подключиться. Введите информацию о соединении, затем выберите Создать.

    Новое подключение

    Параметр Value
    Имя подключения Описательное имя
    Имя пользователя Ваше имя пользователя GitHub
    Пароль Личный маркер доступа, который вы создали ранее

  5. Введите сведения о репозитории, который хотите отслеживать. В объекте WebhookRequestBody в файле OpenAPI вы увидите знакомые поля.

    Сведения о репозитории

    Параметр Стоимость
    владелец Владелец репозитория для мониторинга
    репозиторий Репозиторий для мониторинга

    Важно!

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

  6. Выберите + Новый шаг, а затем — Добавить действие.

  7. Найдите и выберите действие Push-уведомление.

    Push-уведомление

  8. Введите некоторый текст в поле Текст и другие поля, используя значения из диалогового окна динамического содержимого. Обратите внимание, что эти значения взяты из объекта WebhookPushResponse в файле OpenAPI.

    Сведения о push-уведомлении

    Параметр Стоимость
    Имя подключения Описательное имя
    Имя пользователя Ваше имя пользователя GitHub
    Пароль Личный маркер доступа, который вы создали ранее

  9. В верхней части страницы присвойте потоку имя и выберите Создать поток.

    Имя потока

Проверка и устранение неполадок

Чтобы убедиться, все настроено правильно, выберите Мои потоки, а затем выберите значок сведений рядом с новым потоком, чтобы просмотреть журнал запусков:

  • Вы должны увидеть как минимум одно успешное выполнение (Succeeded) с момента создания веб-перехватчика. Это означает, что веб-перехватчик успешно создан на стороне GitHub.

  • Если выполнение завершилось ошибкой, вы можете перейти сведениям о выполнении, чтобы узнать причину сбоя. Если ошибка возникла из-за ответа "404 — не найдено", вполне вероятно, что у учетной записи GitHub нет разрешений на создание веб-перехватчика в репозитории, который использовался.

Сводка

Если все настроено правильно, вы будете получать push-уведомления в мобильном приложении Power Automate при каждой отправке git в выбранный репозиторий GitHub. Следуя описанным выше инструкциям, можно использовать любую службу с поддержкой веб-перехватчика в качестве триггера потоков.

Дальнейшие шаги

Предоставление отзывов

Для нас очень важны отзывы о проблемах с нашей платформой соединителей и новые идеи о функциях. Чтобы оставить отзыв, выберите пункт Сообщить о проблемах или получить помощь с соединителями и выберите тип отзыва.