Creare una sottoscrizione hook del servizio a livello di codice
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
Usando le API REST delle sottoscrizioni , è possibile creare a livello di codice una sottoscrizione che esegue un'azione su un servizio esterno/consumer quando si verifica un evento specifico in un progetto Azure DevOps. Ad esempio, è possibile creare una sottoscrizione per notificare al servizio quando una compilazione ha esito negativo.
Eventi supportati:
- Compilazione completata
- Codice inviato (nei progetti Git)
- Creazione o aggiornamento della richiesta pull (per i progetti Git)
- Codice inserito (progetti TFVC)
- Elemento di lavoro creato, aggiornato, eliminato, ripristinato o commentato
È possibile configurare filtri per le sottoscrizioni per controllare quali eventi attivano un'azione. Ad esempio, è possibile filtrare l'evento di compilazione completato in base allo stato di compilazione. Per un set completo di eventi supportati e opzioni di filtro, vedere la Guida agli eventi.
Per un set completo di servizi e azioni supportati per il consumatore, vedere il riferimento al consumatore .
Prerequisiti
| Categoria | Requisiti |
|---|---|
| di accesso a Project | membro del progetto. |
| Dati | - Progetto ID. Usare l'API REST del progetto per ottenere l'ID del progetto. - ID evento e impostazioni. Consultare il riferimento all'evento. - ID e impostazioni del consumatore e dell'azione. Vedere le informazioni di riferimento consumer. |
Creare la richiesta
Costruire il corpo della richiesta HTTP POST per creare la sottoscrizione in base all'ID progetto, all'evento, al consumer e all'azione.
Consultare il seguente esempio di richiesta per la creazione di una sottoscrizione che provoca l'invio di un evento di compilazione a https://myservice/event quando la compilazione WebSite.CI non riesce.
Richiesta
{
"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"
},
}
È consigliabile usare URL HTTPS sicuri per la sicurezza dei dati privati nell'oggetto JSON.
Risposta Vedere la risposta seguente alla richiesta di creazione della sottoscrizione:
{
"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 la richiesta di sottoscrizione non riesce, viene visualizzato un codice di risposta HTTP pari a 400 con un messaggio con altri dettagli.
Cosa accade quando si verifica l'evento?
Quando si verifica un evento, vengono valutate tutte le sottoscrizioni abilitate nel progetto e l'azione consumer viene eseguita per tutte le sottoscrizioni corrispondenti.
Versioni delle risorse (avanzate)
Il controllo delle versioni delle risorse è applicabile quando un'API è in anteprima. Per la maggior parte degli scenari, specificare 1.0 come versione della risorsa è l'opzione più sicura.
Il payload dell'evento inviato a determinati consumer, ad esempio Webhooks, Azure Service Bus e Azure Storage, include una rappresentazione JSON della risorsa oggetto (ad esempio, una build o un elemento di lavoro). La rappresentazione di questa risorsa può avere forme o versioni diverse.
È possibile specificare la versione della risorsa che si vuole inviare al servizio consumer tramite il campo resourceVersion nella sottoscrizione.
La versione della risorsa è la stessa della versione dell'API . Se non si specifica una versione della risorsa, significa "ultima versione rilasciata". È consigliabile specificare sempre una versione della risorsa, che garantisce un payload di eventi coerente nel tempo.
Domande frequenti
D: Sono disponibili servizi che è possibile sottoscrivere manualmente?
R: Sì. Per altre informazioni sui servizi a cui è possibile eseguire la sottoscrizione dalla pagina di amministrazione di un progetto, vedere panoramica .
D: Sono disponibili librerie C# che è possibile usare per creare sottoscrizioni?
R: No, ma ecco un esempio per iniziare.
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; }
}
}