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

  • Artículo
  • 4 minutos para leer

Azure DevOps Services | Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018 - TFS 2017

Con las API REST de suscripciones, puede crear mediante programación una suscripción que realice una acción en un servicio externo (consumidor) cuando se produzca un evento específico en un proyecto. 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 pushed (para proyectos de Git)
  • creación o actualización de solicitudes de extracción (para proyectos de Git)
  • código activado (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 de consumidor.

Creación de una suscripción para un proyecto

Para crear una suscripción para un evento, elija qué consumidor usar y la acción que desea realizar. Cree una solicitud HTTP POST a la dirección URL de suscripciones de la organización Azure DevOps con el evento, el consumidor y la acción que se debe realizar para la suscripción.

Antes de empezar

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

  • Id. de proyecto (use la API REST Project para obtener el identificador del proyecto)
  • Id. de evento y configuración (consulte la referencia de eventos)
  • valores y los valores de los valores y los valores de los valores 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, el evento, el consumidor y la acción del proyecto.

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

{
    "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 proteger las direcciones URL HTTPS para la seguridad de los datos privados en el objeto JSON.

Esta es la respuesta a la solicitud para crear la suscripción:

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

Si se produce un error en la solicitud de suscripción, se devuelve un código de respuesta HTTP 400 con un mensaje con 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 se realiza la acción del consumidor para todas las suscripciones correspondientes.

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 web hooks, Azure Service Bus, Azure Storage) incluye una representación JSON del recurso de asunto (por ejemplo, una compilación o un elemento de trabajo). La representación de este recurso puede tener diferentes formas (o versiones). Puede especificar la versión del recurso que desea enviar 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 api. No especificar una versión de recurso significa "última versión publicada". Siempre debe especificar una versión de recurso: esto garantiza una carga de eventos coherente a lo largo del tiempo.

Preguntas y respuestas

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

A. Sí. Estos son los servicios a los que puede suscribirse desde la página de administración de un proyecto.

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

A. No, pero este es un ejemplo que le ayudará a empezar a trabajar.

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

            if (result == null)
                return String.Empty;

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