Criar uma assinatura de gancho de serviço programaticamente

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

Você pode usar uma assinatura para executar uma ação em um serviço externo ou de consumidor quando ocorre um evento específico em um projeto do Azure DevOps. Por exemplo, uma assinatura pode notificar seu serviço quando uma compilação falhar.

Para criar uma assinatura programaticamente, você pode usar as APIs REST de Assinaturas. Este artigo fornece uma solicitação de exemplo e um código de exemplo para criar uma assinatura.

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 Eventos do Service Hook. – IDs e configurações do consumidor e da ação. Consulte os consumidores de gancho de serviço.

Eventos compatíveis

O Azure DevOps oferece suporte para vários eventos de gatilho. Os exemplos incluem os seguintes eventos:

Build concluído
Código enviado por push (para projetos do Git)
Solicitação pull criada ou atualizada (para projetos do Git)
Check-in de código (para projetos do Team Foundation Version Control)
Item de trabalho criado, atualizado, excluído, restaurado ou com comentários

Para controlar quais eventos disparam uma ação, você pode configurar filtros em suas assinaturas. 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 eventos de gancho de serviço.
Para obter um conjunto completo de serviços e ações de consumidor com suporte, consulte os consumidores de gancho de serviço.

Criar uma solicitação

Ao criar uma assinatura, você usa o corpo de uma solicitação HTTP POST para especificar a ID do projeto, o evento, o consumidor, a ação e as configurações relacionadas.

Você pode usar a solicitação a seguir para criar uma assinatura para um evento de conclusão de build. Neste exemplo, quando o WebSite.CI build falha, a assinatura envia uma solicitação POST para https://myservice/event.

Solicitação

{
    "publisherId": "tfs",
    "eventType": "build.complete",
    "resourceVersion": "1.0",
    "consumerId": "webHooks",
    "consumerActionId": "httpRequest",
    "publisherInputs": {
        "buildStatus": "failed",
        "definitionName": "WebSite.CI",
        "projectId": "11bb11bb-cc22-dd33-ee44-55ff55ff55ff",
    },
    "consumerInputs": {
        "url": " https://myservice/event"
    },
}

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

Resposta

A solicitação para criar a assinatura gera uma resposta semelhante à seguinte:

{
    "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": "22cc22cc-dd33-ee44-ff55-66aa66aa66aa"
    },
    "createdDate": "2014-03-28T16:10:06.523Z",
    "modifiedBy": {
        "id": "22cc22cc-dd33-ee44-ff55-66aa66aa66aa"
    },
    "modifiedDate": "2014-04-25T18:15:26.053Z",
    "publisherInputs": {
        "buildStatus": "failed",
        "definitionName": "WebSite.CI",
        "hostId": "d3d3d3d3-eeee-ffff-aaaa-b4b4b4b4b4b4",
        "projectId": "11bb11bb-cc22-dd33-ee44-55ff55ff55ff",
        "tfsSubscriptionId": "ffff5f5f-aa6a-bb7b-cc8c-dddddd9d9d9d"
    },
    "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 um evento ocorre, todas as assinaturas habilitadas no projeto são avaliadas. Em seguida, 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 a determinados consumidores inclui uma representação JSON de um recurso sujeito. Por exemplo, o conteúdo enviado para webhooks, Barramento de Serviço do Azure e Armazenamento do Azure inclui informações sobre uma construção ou tarefa. A representação desse recurso pode ter vários formulários ou versões.

Você pode especificar a versão do recurso que deseja enviar para o serviço do consumidor por meio do resourceVersion campo na assinatura.

A versão do recurso é a mesma que a versão da API . Se você não especificar uma versão do recurso, a versão latest releasedmais recente será usada. Para ajudar a garantir uma carga de evento consistente ao longo do tempo, especifique sempre uma versão do recurso.

Perguntas frequentes

R: Sim. Para obter mais informações sobre os serviços aos quais você pode assinar a partir de uma página de administração de projeto, consulte Integrar com ganchos de serviço.

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

R: Não, mas aqui está um exemplo para ajudá-lo a começar. Para autenticação no Azure DevOps, o código a seguir usa um PAT (token de acesso pessoal) armazenado no Azure Key Vault. Em um ambiente de produção, use um método de autenticação mais seguro. Para obter mais informações, consulte Escolher o mecanismo de autenticação correto.

using Azure.Identity;
using Azure.Security.KeyVault.Secrets;
using Microsoft.VisualStudio.Services.Common;
using Microsoft.VisualStudio.Services.ServiceHooks.WebApi;
using Microsoft.VisualStudio.Services.WebApi;

namespace CreateServiceHookSubscription
{
    internal class Program
    {
        // Create a service hook subscription to send a message to an Azure Service Bus queue when code is pushed to a Git repository.

        static async Task Main(string[] args)
        {
            // Get the secrets from the key vault.
            string keyVaultURI = "https://<key-vault-name>.vault.azure.net/";
            var secretClient = new SecretClient(new Uri(keyVaultURI), new DefaultAzureCredential());
            string personalAccessTokenSecretName = "<personal-access-token-secret-name>";
            string serviceBusConnectionStringSecretName = "<Service-Bus-connection-string-secret-name>";
            KeyVaultSecret personalAccessTokenSecret = await secretClient.GetSecretAsync(personalAccessTokenSecretName);
            KeyVaultSecret serviceBusConnectionStringSecret = await secretClient.GetSecretAsync(serviceBusConnectionStringSecretName);

            // Set up the connection parameters for Azure DevOps.
            var azureDevOpsOrganizationURL = new Uri("https://dev.azure.com/<Azure-DevOps-organization-name>/");
            string azureDevOpsTeamProjectID = "<Azure-DevOps-team-project-ID>";
            string azureDevOpsPersonalAccessToken = personalAccessTokenSecret.Value;

            // Set up the event parameters.
            string eventPublisherID = "tfs";
            string eventID = "git.push";
            string eventDescription = "Any stage in any release";
            string resourceVersion = "1.0";

            // Set up the consumer parameters.
            string consumerID = "azureServiceBus";
            string consumerActionID = "serviceBusQueueSend";
            string serviceBusNamespace = "<Service-Bus-namespace>";
            string serviceBusQueueName = "<Service-Bus-queue-name>";
            string consumerActionDescription = $"Send a message to the Service Bus {serviceBusQueueName} queue in the {serviceBusNamespace} namespace.";
            string serviceBusConnectionString = serviceBusConnectionStringSecret.Value;

            // Configure the subscription.
            var subscription = new Subscription()
            {
                PublisherId = eventPublisherID,
                PublisherInputs = new Dictionary<string, string>
                {
                    ["projectId"] = azureDevOpsTeamProjectID
                },
                EventType = eventID,
                EventDescription = eventDescription,
                ResourceVersion = resourceVersion,
                ActionDescription = consumerActionDescription,
                ConsumerActionId = consumerActionID,
                ConsumerId = consumerID,
                ConsumerInputs = new Dictionary<string, string>
                {
                    ["connectionString"] = serviceBusConnectionString,
                    ["queueName"] = serviceBusQueueName
                }
            };

            // Connect to the Azure DevOps organization and get a service hook client.
            var azureDevOpsCredentials = new VssBasicCredential(azureDevOpsPersonalAccessToken, string.Empty);
            var azureDevOpsConnection = new VssConnection(azureDevOpsOrganizationURL, azureDevOpsCredentials);
            var serviceHookClient = azureDevOpsConnection.GetClient<ServiceHooksPublisherHttpClient>();

            // Create the subscription.
            var createdSubscription = await serviceHookClient.CreateSubscriptionAsync(subscription);
            Console.WriteLine($"A subscription was created that has ID {createdSubscription.Id}.");
        }
    }
}

Comentários

Esta página foi útil?

Last updated on 2025-12-17