Поделиться через

Создание подписки на веб-хук программно

  • Статья

Azure DevOps Services | Azure DevOps Server 2022 — Azure DevOps Server 2019

С помощью интерфейсов REST API подписок можно программно создать подписку, которая выполняет действие в внешней/потребительской службе при возникновении определенного события в проекте Azure DevOps. Например, вы можете создать подписку, чтобы уведомить службу о сбое сборки.

Поддерживаемые события:

  • Сборка завершена
  • Отправленный код (для проектов Git)
  • Создать или обновить pull request (для проектов Git)
  • Код, зарегистрированный (в проектах TFVC)
  • Рабочий элемент, созданный, обновленный, удаленный, восстановленный или закомментированный

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

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

Необходимые условия

Категория Требования
доступ к проекту член проекта.
данные — Идентификатор проекта. Чтобы получить идентификатор проекта, используйте REST API проекта.
— Идентификатор события и параметры. См. справочник по событиям .
— Идентификаторы и настройки пользователей и действий. Смотрите справочник потребителей .

Создание запроса

Создайте текст HTTP-запроса POST, чтобы создать подписку на основе идентификатора проекта, события, потребителя и действия.

См. следующий пример запроса на создание подписки, которая приводит к отправке события сборки в https://myservice/event при сбое сборки WebSite.CI.

запрос

{
    "publisherId": "tfs",
    "eventType": "build.complete",
    "resourceVersion": "1.0",
    "consumerId": "webHooks",
    "consumerActionId": "httpRequest",
    "publisherInputs": {
        "buildStatus": "failed",
        "definitionName": "WebSite.CI",
        "projectId": "56479caf-1eeb-4bca-86ab-aaa6f29399d9",
    },
    "consumerInputs": {
        "url": " https://myservice/event"
    },
}

Настоятельно рекомендуется использовать безопасные URL-адреса HTTPS для безопасности частных данных в объекте JSON.

Ответ Смотрите следующий ответ на запрос о создании подписки:

{
    "id": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
    "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/hooks/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
    "publisherId": "tfs",
    "eventType": "build.complete",
    "resourceVersion": "1.0",
    "consumerId": "webHooks",
    "consumerActionId": "httpRequest",
    "createdBy": {
        "id": "00ca946b-2fe9-4f2a-ae2f-40d5c48001bc"
    },
    "createdDate": "2014-03-28T16:10:06.523Z",
    "modifiedBy": {
        "id": "1c4978ae-7cc9-4efa-8649-5547304a8438"
    },
    "modifiedDate": "2014-04-25T18:15:26.053Z",
    "publisherInputs": {
        "buildStatus": "failed",
        "definitionName": "WebSite.CI",
        "hostId": "17f27955-99bb-4861-9550-f2c669d64fc9",
        "projectId": "56479caf-1eeb-4bca-86ab-aaa6f29399d9",
        "tfsSubscriptionId": "29cde8b4-f37e-4ef9-a6d4-d57d526d82cc"
    },
    "consumerInputs": {
        "url": "http://myservice/event"
    }
}

Если запрос на подписку завершается сбоем, вы получите код ответа HTTP 400 с сообщением, которое содержит дополнительные сведения.

Что происходит при возникновении события?

При возникновении события оцениваются все включенные подписки в проекте, а действие потребителя выполняется для всех соответствующих подписок.

Версии ресурсов (расширенные)

Управление версиями ресурсов применимо, если API находится в предварительной версии. Для большинства сценариев указание 1.0 в качестве версии ресурса является самым безопасным маршрутом.

Полезные данные события, отправленные определенным потребителям, таким как веб-перехватчики, Azure Service Bus и Azure Storage, включают представление в формате JSON ресурса объекта (например, сборку или рабочий элемент). Представление этого ресурса может иметь разные формы или версии.

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

Часто задаваемые вопросы

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

Ответ. Да. Дополнительные сведения о службах, на которые можно подписаться через страницу администрирования проекта, см. в разделе Обзор.

Вопрос. Существуют ли библиотеки C#, которые можно использовать для создания подписок?

Ответ. Нет, но вот пример, который поможет вам приступить к работе.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Web.Mvc;

namespace Microsoft.Samples.VisualStudioOnline
{
    public class ServiceHookEventController : Controller
    {

        // POST: /ServiceHookEvent/workitemcreated
        [HttpPost]
        public HttpResponseMessage WorkItemCreated(Content workItemEvent)
        {
            //Grabbing the title for the new workitem
            var value = RetrieveFieldValue("System.field", workItemEvent.Resource.Fields);

            //Acknowledge event receipt
            return new HttpResponseMessage(HttpStatusCode.OK);
        }

        /// <summary>
        /// Gets the value for a specified work item field.
        /// </summary>
        /// <param name="key">Key used to retrieve matching value</param>
        /// <param name="fields">List of fields for a work item</param>
        /// <returns></returns>
        public String RetrieveFieldValue(String key, IList<FieldInfo> fields)
        {
            if (String.IsNullOrEmpty(key))
                return String.Empty;

            var result = fields.Single(s => s.Field.RefName == key);

            return result.Value;
        }

	}

    public class Content
    {
        public String SubscriptionId { get; set; }

        public int NotificationId { get; set; }

        public String EventType { get; set; }

        public WorkItemResource Resource { get; set; }

    }

    public class WorkItemResource
    {
        public String UpdatesUrl { get; set; }

        public IList<FieldInfo> Fields { get; set;}

        public int Id { get; set; }

        public int Rev { get; set; }

        public String Url { get; set; }

        public String WebUrl { get; set; }
    }

    public class FieldInfo
    {
        public FieldDetailedInfo Field { get; set; }

        public String Value { get; set; }

    }

    public class FieldDetailedInfo
    {
        public int Id { get; set; }

        public String Name { get; set; }

        public String RefName { get; set; }
    }
}