Compartilhar via

Criar uma assinatura de gancho de serviço programaticamente

  • Artigo

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

Ao usar as APIs REST de Assinaturas , você pode criar programaticamente uma assinatura que executa uma ação em um serviço externo ou de consumidor quando um evento específico ocorre em um projeto do Azure DevOps. Por exemplo, você pode criar uma assinatura para notificar seu serviço quando um build falhar.

Eventos com suporte:

  • Build concluído
  • Código enviado por push (para projetos do Git)
  • Criação ou atualização da solicitação pull (para projetos do Git)
  • Código verificado (projetos TFVC)
  • Item de trabalho criado, atualizado, excluído, restaurado ou com comentários

Você pode configurar filtros em suas assinaturas para controlar quais eventos disparam uma ação. Por exemplo, você pode filtrar o evento de build concluído com base no status de build. Para obter um conjunto completo de eventos com suporte e opções de filtro, consulte a Referência de evento.

Para obter um conjunto completo de serviços e ações de consumidor com suporte, consulte a Referência do consumidor.

Pré-requisitos

Categoria Requisitos
Acesso ao Projeto Membro do projeto.
Dados - ID do projeto. Use a API REST do Projeto para obter a ID do projeto.
– ID do evento e configurações. Consulte a Referência de evento.
– IDs e configurações do consumidor e da ação. Consulte a Referência do consumidor.

Criar a solicitação

Construa o corpo da solicitação HTTP POST para criar a assinatura com base na ID do projeto, no evento, no consumidor e na ação.

Consulte o exemplo de solicitação a seguir para criar uma assinatura que faça com que um evento de build use POST para https://myservice/event quando o build WebSite.CI falhar.

Solicitação

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

É altamente recomendável usar URLs HTTPS seguras para a segurança dos dados privados no objeto JSON.

Resposta Veja a seguinte resposta à solicitação para criar a assinatura:

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

Se a solicitação de assinatura falhar, você receberá um código de resposta HTTP 400 com uma mensagem que tenha mais detalhes.

O que acontece quando o evento ocorre?

Quando ocorre um evento, todas as assinaturas habilitadas no projeto são avaliadas e a ação do consumidor é executada para todas as assinaturas correspondentes.

Versões de recurso (avançadas)

O controle de versão de recursos é aplicável quando uma API está em versão prévia. Para a maioria dos cenários, especificar 1.0 como a versão do recurso é a rota mais segura.

O conteúdo do evento enviado para determinados consumidores, como Webhooks, Barramento de Serviço do Azure e Armazenamento do Azure, inclui uma representação JSON do recurso em questão (por exemplo, um item de build ou de trabalho). A representação desse recurso pode ter diferentes formulários ou versões.

Você pode especificar a versão do recurso que deseja ter enviado para o serviço do consumidor por meio do campo resourceVersion na assinatura. A versão do recurso é a mesma que a versão da API . Não especificar uma versão do recurso significa "lançamento mais recente". Você sempre deve especificar uma versão de recurso, o que garante uma carga de evento consistente ao longo do tempo.

Perguntas frequentes

P: Há serviços aos quais posso assinar manualmente?

R: Sim. Para obter mais informações sobre os serviços a que você pode se inscrever na página de administração de um projeto, consulte a Visão Geral.

P: Existem bibliotecas C# que posso usar para criar assinaturas?

R: Não, mas aqui está um exemplo para ajudá-lo a começar.

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