Создание настраиваемого обработчика для веб-хуков служб

Сервисы Azure DevOps | Azure DevOps Server | Azure DevOps Server 2022

Используйте веб-хуки для уведомления внешних систем о событиях в проекте Azure DevOps. Пользовательское расширение клиента отправляет HTTP POST на конечную точку, которую вы настраиваете при возникновении определенных событий.

Подсказка

Если вы создаёте новое расширение Azure DevOps, попробуйте сначала использовать эти поддерживаемые образцы коллекций — они работают с текущими сборками продуктов и охватывают современные сценарии (например, добавление вкладок на страницы pull request).

Если пример не работает в вашей организации, установите его в личную или тестовую организацию и сравните целевые идентификаторы манифеста расширения и версии API с текущими документами. Справочные материалы и API см. в статье:

В этой статье показано, как создать расширение, реализующее пример службы потребителей. Пример потребителя:

  • Прослушивает три события Git: отправка кода, создание pull request и обновление pull request.
  • Отправляет HTTP POST с нагрузкой события на настраиваемый URL-адрес конечной точки

Схема, показывающая пример потребительской службы, отправляющей HTTP-сообщения для событий 'push' кода и 'pull request'.

Полную версию исходного кода см. в примере репозитория расширения на GitHub. Все доступные типы событий см. в разделе "Типы событий для хуков сервиса".

Подсказка

Для получения последних рекомендаций по разработке расширений, включая темизацию и миграцию из VSS.SDK, смотрите на портале разработчика пакета SDK для расширений Azure DevOps.

Как работают веб-хуки служб

Хуки служб имеют три компонента:

  • Публикаторы генерируют события, такие как "отправка кода" или "создание пулл-запроса".
  • Подписки соответствуют определенным событиям и действиям.
  • Потребители определяют действия, выполняемые, например отправку HTTP POST.

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

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

Создание расширения

1. Настройка проекта

Создайте проект расширения. Инструкции см. в разделе "Разработка веб-расширения".

2. Добавление вклада потребителя

Добавьте вклад потребителя в файл манифеста (vss-extension.json). В следующем примере показан полный манифест с потребителем hook-службы:

{
    "manifestVersion": 1,
    "id": "samples-service-hooks-consumer",
    "version": "0.1.2",
    "name": "Service Hooks Sample",
    "description": "A simple extension that demonstrates how to contribute a consumer service into service hooks.",
    "publisher": "fabrikam",
    "public": false,
    "icons": {
        "default": "images/logo.png"
    },
    "scopes": [],
    "files": [
        {
            "path": "images",
            "addressable": true
        }
    ],
    "content": {
        "details": {
            "path": "readme.md"
        }
    },
    "categories": [
        "Developer samples"
    ],
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services"
        }
    ],
    "contributions": [
        {
            "id": "consumer",
            "type": "ms.vss-servicehooks.consumer",
            "targets": [
                "ms.vss-servicehooks.consumers"
            ],
            "properties": {
                "id": "consumer",
                "name": "Sample Consumer",
                "description": "Sample consumer service",
                "informationUrl": "https://aka.ms/vsoextensions",
                "inputDescriptors": [
                    {
                        "id": "url",
                        "isRequired": true,
                        "name": "URL",
                        "description": "URL to post event payload to",
                        "inputMode": "textbox"
                    }
                ],
                "actions": [
                    {
                        "id": "performAction",
                        "name": "Perform action",
                        "description": "Posts a standard event payload",
                        "supportedEventTypes": [
                            "git.push",
                            "git.pullrequest.created",
                            "git.pullrequest.updated"
                        ],
                        "publishEvent": {
                            "url": "{{{url}}}",
                            "resourceDetailsToSend": "all",
                            "messagesToSend": "all",
                            "detailedMessagesToSend": "all"
                        }
                    }
                ]
            }
        }
    ]
}

Примечание.

Обновите свойство, чтобы оно совпадало с вашим идентификатором publisher издателя.

Массив contributions является ключевым разделом. Каждый вклад определяет:

  • Тип: ms.vss-servicehooks.consumer — регистрирует службу потребителей
  • Целевой объект: ms.vss-servicehooks.consumers — коллекция служб потребителей
  • Свойства: конфигурация потребителя, включая входные данные и действия (см. справочник по свойствам)

3. Упаковка, публикация и тестирование

Упаковайте и опубликуйте расширение в организации Azure DevOps. Затем создайте подписку на веб-хук, которая использует вашего пользовательского потребителя для проверки его работы.

Справочник по свойствам

Свойства потребителя

Недвижимость Описание
id Уникальный идентификатор службы потребителей.
имя Имя, отображаемое при создании подписок на служебные хуки.
описание Описывает службу потребителей.
ссылкаНаИнформацию URL-адрес, где пользователи могут узнать больше о расширении.
описатели входных данных Входные данные, предоставляемые пользователями при создании подписок (например, конечная точка URL-адреса).
Действия Действия, выполняемые при возникновении событий, и какие типы событий активируют каждое действие.

Свойства действия

Каждое действие в массиве actions имеет следующие свойства:

Недвижимость Описание
id Уникальный идентификатор действия.
имя Отображаемое имя действия.
описание Описание того, что делает действие.
поддерживаемыеТипыСобытий Массив идентификаторов типов событий, которые активируют это действие. Для ознакомления с доступными типами, смотрите в разделе "Типы событий перехватчика службы".
publishEvent.url URL-адрес конечной точки, получающий HTTP POST. Используйте синтаксис Mustache ({{{inputId}}}) для замены значений из inputDescriptors, предоставляемых пользователями при создании подписки.

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

Упаковка, публикация и установка расширений

Связанный контент

  • Последнее обновление: