Skapa en tjänsthookprenumeration programmatiskt

  • Artikel

Azure DevOps Services | Azure DevOps Server 2022 – Azure DevOps Server 2019

Med hjälp av REST-API:er för prenumerationer kan du programmatiskt skapa en prenumeration som utför en åtgärd på en extern/konsumenttjänst när en specifik händelse inträffar i ett Azure DevOps-projekt. Du kan till exempel skapa en prenumeration för att meddela din tjänst när ett bygge misslyckas.

Händelser som stöds:

  • Bygge slutfört
  • Kod push-överförd (för Git-projekt)
  • Pull-begäran skapad eller uppdaterad (för Git-projekt)
  • Kod incheckad (TFVC-projekt)
  • Arbetsobjekt skapat, uppdaterat, borttaget, återställt eller kommenterat

Du kan konfigurera filter för dina prenumerationer för att styra vilka händelser som utlöser en åtgärd. Du kan till exempel filtrera händelsen Bygge slutfört baserat på byggstatusen. En fullständig uppsättning händelser och filteralternativ som stöds finns i händelsereferensen.

En fullständig uppsättning konsumenttjänster och -åtgärder som stöds finns i konsumentreferensen.

Förutsättningar

För att skapa en prenumeration krävs följande data:

  • Projekt-ID. Använd Project REST API för att hämta projekt-ID:t.
  • Händelse-ID och inställningar. Se händelsereferensen.
  • Konsument- och åtgärds-ID och inställningar. Se konsumentreferensen.

Skapa begäran

Skapa brödtexten i HTTP POST-begäran för att skapa prenumerationen baserat på projekt-ID, händelse, konsument och åtgärd.

Se följande exempelbegäran för att skapa en prenumeration som orsakar en bygghändelse till POST när https://myservice/event bygget WebSite.CI misslyckas.

Begär

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

Vi rekommenderar starkt att du använder säkra HTTPS-URL:er för säkerheten för privata data i JSON-objektet.

Svar Se följande svar på begäran om att skapa prenumerationen:

{
    "id": "74aeeed0-bf5d-48dc-893f-f862b80987e9",
    "url": "https://dev.azure.com/fabrikam/DefaultCollection/_apis/hooks/subscriptions/74aeeed0-bf5d-48dc-893f-f862b80987e9",
    "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"
    }
}

Om prenumerationsbegäran misslyckas får du en HTTP-svarskod på 400 med ett meddelande med ytterligare information.

Vad händer när händelsen inträffar?

När en händelse inträffar utvärderas alla aktiverade prenumerationer i projektet och konsumentåtgärden utförs för alla matchande prenumerationer.

Resursversioner (avancerat)

Resursversionshantering gäller när ett API är i förhandsversion. I de flesta scenarier är det säkrast att 1.0 ange som resursversion.

Händelsenyttolasten som skickas till vissa konsumenter, till exempel Webhooks, Azure Service Bus och Azure Storage, innehåller en JSON-representation av ämnesresursen (till exempel ett bygg- eller arbetsobjekt). Representationen av den här resursen kan ha olika formulär eller versioner.

Du kan ange vilken version av resursen som du vill ha skickat till konsumenttjänsten via resourceVersion fältet i prenumerationen. Resursversionen är samma som API-versionen. Att inte ange en resursversion innebär "senaste versionen". Du bör alltid ange en resursversion, vilket garanterar en konsekvent händelsenyttolast över tid.

Vanliga frågor och svar

F: Finns det tjänster som jag kan prenumerera på manuellt?

S: Ja. Mer information om de tjänster som du kan prenumerera på från administrationssidan för ett projekt finns i Översikt.

F: Finns det C#-bibliotek som jag kan använda för att skapa prenumerationer?

S: Nej, men här är ett exempel som hjälper dig att komma igång.

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