Delen via

Programmatisch een abonnement voor een service hook maken

  • Artikel

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Met behulp van de REST API's voor abonnementen kunt u programmatisch een abonnement maken dat een actie uitvoert op een externe/consumentenservice wanneer een specifieke gebeurtenis plaatsvindt in een Azure DevOps-project. U kunt bijvoorbeeld een abonnement maken om uw service op de hoogte te stellen wanneer een build mislukt.

Ondersteunde gebeurtenissen:

  • Build voltooid
  • Code gepusht (voor Git-projecten)
  • Pull-aanvraag maken of bijgewerkt (voor Git-projecten)
  • Code ingecheckt (TFVC-projecten)
  • Werkitem gemaakt, bijgewerkt, verwijderd, hersteld of van opmerkingen voorzien

U kunt filters voor uw abonnementen configureren om te bepalen welke gebeurtenissen een actie activeren. U kunt bijvoorbeeld de gebeurtenis voltooide build filteren op basis van de buildstatus. Zie de Naslaginformatie over gebeurtenissen voor een volledige set ondersteunde gebeurtenissen en filteropties.

Zie de Naslaginformatie voor consumenten voor een volledige set ondersteunde consumentenservices en -acties.

Vereisten

Voor het maken van een abonnement zijn de volgende gegevens vereist:

De aanvraag maken

Bouw de hoofdtekst van de HTTP POST-aanvraag om het abonnement te maken op basis van de project-id, gebeurtenis, consument en actie.

Zie de volgende voorbeeldaanvraag voor het maken van een abonnement waardoor een build-gebeurtenis naar POST https://myservice/event wordt verzonden wanneer de build WebSite.CI mislukt.

Aanvragen

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

We raden u ten zeerste aan beveiligde HTTPS-URL's te gebruiken voor de beveiliging van de persoonlijke gegevens in het JSON-object.

Antwoord Zie het volgende antwoord op de aanvraag voor het maken van het abonnement:

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

Als de abonnementsaanvraag mislukt, krijgt u een HTTP-antwoordcode van 400 met een bericht met meer informatie.

Wat gebeurt er wanneer de gebeurtenis plaatsvindt?

Wanneer een gebeurtenis plaatsvindt, worden alle ingeschakelde abonnementen in het project geëvalueerd en wordt de consumentenactie uitgevoerd voor alle overeenkomende abonnementen.

Resourceversies (geavanceerd)

Versiebeheer van resources is van toepassing wanneer een API in preview is. Voor de meeste scenario's is het opgeven 1.0 als de resourceversie de veiligste route.

De nettolading van de gebeurtenis die naar bepaalde consumenten wordt verzonden, zoals Webhooks, Azure Service Bus en Azure Storage, bevat een JSON-weergave van de onderwerpresource (bijvoorbeeld een build- of werkitem). De weergave van deze resource kan verschillende formulieren of versies hebben.

U kunt de versie opgeven van de resource die u naar de consumentenservice wilt verzenden via het resourceVersion veld in het abonnement. De resourceversie is hetzelfde als de API-versie. Het niet opgeven van een resourceversie betekent 'nieuwste uitgebracht'. U moet altijd een resourceversie opgeven, die zorgt voor een consistente nettolading van gebeurtenissen in de loop van de tijd.

Veelgestelde vragen

V: Zijn er services waarop ik me handmatig kan abonneren?

A: Ja. Zie het overzicht voor meer informatie over de services waarop u zich kunt abonneren op de beheerpagina voor een project.

V: Zijn er C#-bibliotheken die ik kan gebruiken om abonnementen te maken?

A: Nee, maar hier volgt een voorbeeld om u te helpen aan de slag te gaan.

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