Creación de una suscripción de enlace de servicio mediante programación

  • Artículo

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

Con las API REST de suscripciones , puede crear mediante programación una suscripción que realice una acción en un servicio externo o de consumidor cuando se produzca un evento específico en un proyecto de Azure DevOps. Por ejemplo, puede crear una suscripción para notificar al servicio cuando se produce un error en una compilación.

Eventos admitidos:

  • Compilación completada
  • Código insertado (para proyectos de Git)
  • Creación o actualización de solicitudes de incorporación de cambios (para proyectos de Git)
  • Código protegido (proyectos de TFVC)
  • Elemento de trabajo creado, actualizado, eliminado, restaurado o comentado

Puede configurar filtros en las suscripciones para controlar qué eventos desencadenan una acción. Por ejemplo, puede filtrar el evento de compilación completada en función del estado de compilación. Para obtener un conjunto completo de eventos admitidos y opciones de filtro, consulte la Referencia de eventos.

Para obtener un conjunto completo de servicios y acciones de consumidor admitidos, consulte la Referencia del consumidor.

Requisitos previos

Para crear una suscripción, se requieren los siguientes datos:

  • Identificador de proyecto. Use la API REST de Project para obtener el identificador del proyecto.
  • Id. de evento y configuración. Consulte la referencia de eventos.
  • Identificadores y configuraciones de consumidor y acción. Consulte la referencia del consumidor.

Creación de la solicitud

Construya el cuerpo de la solicitud HTTP POST para crear la suscripción en función del identificador del proyecto, el evento, el consumidor y la acción.

Consulte la solicitud de ejemplo siguiente para crear una suscripción que hace que un evento de compilación se publique cuando https://myservice/event se produce un error en la compilación WebSite.CI .

Solicitar

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

Se recomienda encarecidamente usar direcciones URL HTTPS seguras para la seguridad de los datos privados en el objeto JSON.

Respuesta Consulte la siguiente respuesta a la solicitud para crear la suscripción:

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

Si se produce un error en la solicitud de suscripción, obtendrá un código de respuesta HTTP de 400 con un mensaje que tenga más detalles.

¿Qué ocurre cuando se produce el evento?

Cuando se produce un evento, se evalúan todas las suscripciones habilitadas en el proyecto y la acción del consumidor se realiza para todas las suscripciones coincidentes.

Versiones de recursos (avanzadas)

El control de versiones de recursos es aplicable cuando una API está en versión preliminar. En la mayoría de los escenarios, especificar 1.0 como la versión del recurso es la ruta más segura.

La carga de eventos enviada a determinados consumidores, como Webhooks, Azure Service Bus y Azure Storage, incluye una representación JSON del recurso sujeto (por ejemplo, una compilación o un elemento de trabajo). La representación de este recurso puede tener diferentes formularios o versiones.

Puede especificar la versión del recurso que desea haber enviado al servicio de consumidor a través del resourceVersion campo de la suscripción. La versión del recurso es la misma que la versión de la API. No especificar una versión de recurso significa "lanzamiento más reciente". Siempre debe especificar una versión de recurso, lo que garantiza una carga de eventos coherente a lo largo del tiempo.

Preguntas más frecuentes

P: ¿Hay servicios a los que puedo suscribirme manualmente?

A. Sí. Para obtener más información sobre los servicios a los que puede suscribirse desde la página de administración de un proyecto, consulte La información general.

P: ¿Hay bibliotecas de C# que puedo usar para crear suscripciones?

R: No, pero este es un ejemplo para ayudarle a empezar.

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