Programové vytvoření předplatného volaných služeb

  • Článek

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

Pomocí rozhraní REST API pro předplatná můžete programově vytvořit předplatné, které provede akci u externí/spotřebitelské služby, když dojde k určité události v projektu Azure DevOps. Můžete například vytvořit předplatné, které vaši službu upozorní na selhání sestavení.

Podporované události:

  • Dokončení sestavení
  • Vložení kódu (pro projekty Git)
  • Vytvoření nebo aktualizace žádosti o přijetí změn (pro projekty Git)
  • Vrácení kódu se změnami (projekty TFVC)
  • Vytvoření, aktualizace, odstranění nebo obnovení pracovní položky nebo přidání komentáře k pracovní položce

V předplatných můžete nakonfigurovat filtry, které určují, které události aktivují akci. Můžete například filtrovat událost dokončení sestavení na základě stavu sestavení. Kompletní sadu podporovaných událostí a možností filtrování najdete v referenčních informacích o událostech.

Kompletní sadu podporovaných uživatelských služeb a akcí najdete v referenčních informacích o příjemci.

Požadavky

K vytvoření předplatného se vyžadují následující data:

Vytvoření požadavku

Vytvořte tělo požadavku HTTP POST a vytvořte odběr na základě ID projektu, události, příjemce a akce.

Podívejte se na následující příklad žádosti o vytvoření předplatného, které způsobí, že událost sestavení post selže https://myservice/event WebSite.CI .

Požádat

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

Důrazně doporučujeme používat zabezpečené adresy URL HTTPS pro zabezpečení privátních dat v objektu JSON.

Odpověď Viz následující odpověď na žádost o vytvoření předplatného:

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

Pokud požadavek na předplatné selže, získáte kód odpovědi HTTP 400 se zprávou, která obsahuje další podrobnosti.

Co se stane, když dojde k události?

Když dojde k události, vyhodnotí se všechna povolená předplatná v projektu a akce příjemce se provede pro všechna odpovídající předplatná.

Verze prostředků (pokročilé)

Správa verzí prostředků se dá použít v případě, že je rozhraní API ve verzi Preview. U většiny scénářů je určením 1.0 verze prostředku nejbezpečnější trasa.

Datová část události odeslaná určitým příjemcům, jako jsou Webhooky, Azure Service Bus a Azure Storage, zahrnuje reprezentaci subjektu prostředku JSON (například sestavení nebo pracovní položky). Reprezentace tohoto prostředku může mít různé formuláře nebo verze.

Můžete zadat verzi prostředku, který chcete odeslat do služby příjemce, prostřednictvím resourceVersion pole v předplatném. Verze prostředku je stejná jako verze rozhraní API. Nezadání verze prostředku znamená "nejnovější vydaná". Vždy byste měli zadat verzi prostředku, která zajišťuje konzistentní datovou část události v průběhu času.

Nejčastější dotazy

Otázka: Existují služby, které se dají přihlásit k odběru ručně?

Odpověď: Ano. Další informace o službách, ke kterým se můžete přihlásit z stránky pro správu projektu, najdete v části Přehled.

Otázka: Existují knihovny jazyka C#, které můžu použít k vytváření předplatných?

Ne, ale tady je ukázka, která vám pomůže začít.

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