Udostępnij za pośrednictwem

Programowe tworzenie subskrypcji przypinania usługi

  • Artykuł

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

Korzystając z interfejsów API REST subskrypcji , można programowo utworzyć subskrypcję, która wykonuje akcję w usłudze zewnętrznej/konsumenckiej, gdy określone zdarzenie występuje w projekcie usługi Azure DevOps. Możesz na przykład utworzyć subskrypcję, aby powiadomić usługę, gdy kompilacja zakończy się niepowodzeniem.

Obsługiwane zdarzenia:

  • Budowa zakończona
  • Kod został przesłany dla projektów Git
  • Tworzenie lub aktualizowanie żądania ściągnięcia (w przypadku projektów Git)
  • Kod zatwierdzony (projekty TFVC)
  • Utworzony, zaktualizowany, usunięty, przywrócony lub skomentowany element roboczy

Filtry w subskrypcjach można skonfigurować, aby kontrolować, które zdarzenia wyzwalają akcję. Na przykład można filtrować zdarzenie zakończenia kompilacji na podstawie stanu kompilacji. Aby uzyskać pełny zestaw obsługiwanych zdarzeń i opcji filtrowania, zobacz Dokumentacja zdarzeń.

Aby uzyskać pełny zestaw obsługiwanych usług i akcji konsumenckich, zobacz Informacje o konsumentach.

Warunki wstępne

Kategoria Wymagania
dostęp do projektu członek projektu.
dane — Identyfikator projektu. Użyj interfejsu API REST projektu , aby uzyskać identyfikator projektu.
- Identyfikator zdarzenia i ustawienia. Zobacz odniesienie do wydarzenia .
— Identyfikatory i ustawienia użytkownika i akcji. Zobacz referencję Konsumenta.

Tworzenie żądania

Skonstruuj treść żądania HTTP POST, aby utworzyć subskrypcję na podstawie identyfikatora projektu, zdarzenia, odbiorcy i akcji.

Zobacz następujące przykładowe żądanie utworzenia subskrypcji, która powoduje, że zdarzenie kompilacji zostaje wysłane do https://myservice/event w przypadku niepowodzenia kompilacji WebSite.CI.

żądanie

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

Zdecydowanie zalecamy używanie bezpiecznych adresów URL HTTPS w celu zabezpieczenia danych prywatnych w obiekcie JSON.

Response Zobacz następującą odpowiedź na żądanie utworzenia subskrypcji:

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

Jeśli żądanie subskrypcji nie powiedzie się, otrzymasz kod odpowiedzi HTTP 400 z komunikatem zawierającym dalsze szczegóły.

Co się stanie po wystąpieniu zdarzenia?

W przypadku wystąpienia zdarzenia wszystkie włączone subskrypcje w projekcie są oceniane, a akcja konsumenta jest wykonywana dla wszystkich pasujących subskrypcji.

Wersje zasobów (zaawansowane)

Wersjonowanie zasobów ma zastosowanie, gdy API jest w wersji zapoznawczej. W przypadku większości scenariuszy określenie 1.0 jako wersji zasobu jest najbezpieczniejszym wyborem.

Ładunek zdarzenia wysyłany do niektórych odbiorców, takich jak webhooks, usługa Azure Service Bus i usługa Azure Storage, zawiera reprezentację zasobu przedmiotu w formacie JSON (na przykład kompilacja lub element roboczy). Reprezentacja tego zasobu może mieć różne formularze lub wersje.

Możesz określić wersję zasobu, który ma zostać wysłany do usługi konsumenta za pośrednictwem pola resourceVersion w subskrypcji. Wersja zasobu jest taka sama jak wersja API . Nieokreślenie wersji zasobu oznacza "ostatnio wydaną". Zawsze należy określić wersję zasobu, która zapewnia spójny ładunek zdarzeń w czasie.

Często zadawane pytania

.: Czy istnieją usługi, które mogę subskrybować ręcznie?

Tak. Aby uzyskać więcej informacji na temat usług, które można subskrybować na stronie administracyjnej projektu, odwiedź Przegląd.

.: Czy istnieją biblioteki języka C#, których mogę użyć do tworzenia subskrypcji?

Nie, ale oto przykład, który pomoże Ci rozpocząć.

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