Guia de início rápido - Inscrever-se em Eventos dos Serviços de Comunicação do Azure - An Azure Communication Services quickstart

Artigo
02/06/2024

Neste início rápido, você aprenderá a assinar eventos dos Serviços de Comunicação do Azure por meio do portal, da CLI do Azure, do PowerShell e do SDK do .NET.

Você pode configurar assinaturas de eventos para recursos dos Serviços de Comunicação por meio do portal do Azure ou da CLI do Azure, PowerShell ou com o SDK de Gerenciamento de Grade de Eventos do Azure.

Para este Guia de início rápido, percorremos o processo de configuração do webhook como assinante de eventos SMS dos Serviços de Comunicação do Azure. Para obter uma lista completa de eventos, consulte esta página.

Pré-requisitos

Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
Um recurso dos Serviços de Comunicação do Azure.
Crie um Webhook para receber eventos. Entrega de eventos Webhook.

Registrar o provedor de recursos da Grade de Eventos

Este artigo descreve como registrar o provedor de recursos de grade de eventos. Se você usou a Grade de Eventos antes na mesma assinatura, pule para a próxima seção.

No portal do Azure, execute as seguintes etapas:

No menu à esquerda, selecione Assinaturas.
Selecione a Subscrição que pretende utilizar para a Grelha de Eventos na lista de subscrições.
Na página Assinatura, selecione Provedores de recursos em Configurações no menu à esquerda.
Procure Microsoft.EventGrid e confirme se o Status não está registrado.
Selecione Microsoft.EventGrid na lista de provedores.
Selecione Registrar na barra de comandos.
Atualize para verificar se o status de Microsoft.EventGrid foi alterado para Registrado.

Criar subscrição de evento

Para criar uma assinatura de evento para os Serviços de Comunicação do Azure, use as etapas a seguir. Este artigo mostra como criar uma assinatura de evento para os Serviços de Comunicação do Azure para receber eventos via Webhook.

Para criar uma assinatura de evento para o recurso Serviços de Comunicação do Azure, primeiro entre no portal do Azure. No canto superior esquerdo da página, selecione o recurso Serviços de Comunicação.

Selecione na guia Eventos no menu à esquerda.
Selecione + Subscrição de Eventos.

Na página Criar Subscrição de Eventos , siga estes passos:

Insira um nome para a assinatura do evento.
Insira um nome para o nome do tópico Sistema.
Selecione os tipos de evento que você deseja receber na assinatura do evento.

Para obter mais informações sobre eventos dos Serviços de Comunicação, consulte Eventos dos Serviços de Comunicação
Selecione o tipo de ponto de extremidade como gancho da Web.
Selecione Configurar um ponto de extremidade
Insira o link para o webhook e selecione Confirmar seleção.
Na guia Filtros, adicione os nomes dos tipos de evento que deseja filtrar na assinatura e adicione filtros de atributo de contexto que deseja usar na assinatura. Em seguida, selecione Avançar: Recursos adicionais na parte inferior da página.
Para habilitar letras inativas e personalizar políticas de novas tentativas, selecione Recursos adicionais.
Quando terminar, selecione Criar.

Atualizar subscrição de eventos

Para atualizar uma assinatura de evento para os Serviços de Comunicação do Azure, use as etapas a seguir. Esta seção mostra como atualizar uma assinatura de evento para os Serviços de Comunicação do Azure para atualizar os eventos que você deseja receber via Webhook.

Para atualizar uma assinatura de evento para o recurso Serviços de Comunicação do Azure, primeiro entre no portal do Azure. No canto superior esquerdo da página, selecione o recurso Serviços de Comunicação.

Selecione a guia Eventos no menu à esquerda.
Selecione as Subscrições de Eventos e selecione a Subscrição de Eventos que pretende atualizar.
Na página Subscrição de Eventos, selecione no separador Filtros. Selecione os tipos de evento que você deseja receber na assinatura do evento.
Para habilitar letras inativas e personalizar políticas de novas tentativas, selecione Recursos adicionais.
Para atualizar o webhook para receber eventos, selecione Alterar ao lado do link do webhook e insira o novo ponto de extremidade do webhook.
Quando terminar, selecione Salvar,

Excluir assinatura de evento

Para excluir uma assinatura de evento para os Serviços de Comunicação do Azure, use as etapas a seguir.

Para excluir uma assinatura de evento para o recurso dos Serviços de Comunicação do Azure, primeiro entre no portal do Azure. No canto superior esquerdo da página, selecione o recurso Serviços de Comunicação.

Selecione na guia Eventos no menu à esquerda.
Selecione Assinaturas de evento e Selecione a assinatura de evento que deseja excluir.
Na página Subscrição do Evento, selecione o botão Eliminar na parte superior.

Próximos passos

Para obter uma lista de eventos dos Serviços de Comunicação, consulte Eventos dos Serviços de Comunicação.
Para obter uma lista de manipuladores de eventos suportados, consulte Manipuladores de eventos.
Para obter informações sobre entrega e tentativas de eventos, entrega e repetição de mensagens da Grade de Eventos.
Para obter uma introdução ao Event Grid, veja Sobre o Azure Event Grid.

Pré-requisitos

Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
Instalar a CLI do Azure
Um recurso dos Serviços de Comunicação do Azure
Crie um Webhook para receber eventos. Entrega de eventos Webhook

Registrar o provedor de recursos da Grade de Eventos

Este artigo descreve como registrar o provedor de recursos de grade de eventos. Se você usou a Grade de Eventos antes na mesma assinatura, pule para a próxima seção.

Execute o seguinte comando para registar o fornecedor:

az provider register --namespace Microsoft.EventGrid

Pode demorar algum tempo até que o registo termine. Para verificar o status, execute o seguinte comando:
```
az provider show --namespace Microsoft.EventGrid --query "registrationState"
```
Quando registrationState está Registered, está pronto para continuar.

Criar subscrição de evento

Para criar subscrições de eventos para o recurso dos Serviços de Comunicação do Azure, inicie sessão na CLI do Azure. Você pode entrar executando o az login comando do terminal e fornecendo suas credenciais. Execute o seguinte comando para criar a assinatura de evento para o recurso:

Para criar uma assinatura de evento usando a CLI do Azure, use o az eventgrid event-subscription create comando.

az eventgrid event-subscription create 
    --name EventsWebhookSubscription
    --source-resource-id /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>
    --included-event-types Microsoft.Communication.SMSReceived Microsoft.Communication.SMSDeliveryReportReceived
    --endpoint-type webhook 
    --endpoint https://azureeventgridviewer.azurewebsites.net/api/updates

Para obter uma lista de eventos dos Serviços de Comunicação, consulte Eventos dos Serviços de Comunicação.

Listar assinaturas de eventos

Para listar todas as assinaturas de eventos existentes configuradas para um recurso dos Serviços de Comunicação do Azure, usando a CLI do Azure, use o az eventgrid event-subscription list comando.

az eventgrid event-subscription list 
    --source-resource-id /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>

Atualizar subscrição de eventos

Para atualizar uma assinatura de evento existente usando a CLI do Azure, use o az eventgrid event-subscription update comando.

az eventgrid event-subscription update 
    --name EventsWebhookSubscription
    --source-resource-id /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>
    --included-event-types Microsoft.Communication.SMSReceived Microsoft.Communication.SMSDeliveryReportReceived Microsoft.Communication.ChatMessageReceived
    --endpoint-type webhook 
    --endpoint https://azureeventgridviewer.azurewebsites.net/api/updates

Excluir assinatura de evento

Para excluir uma assinatura de evento existente usando a CLI do Azure, use o az eventgrid event-subscription delete comando.

az eventgrid event-subscription delete 
    --name EventsWebhookSubscription 
    --source-resource-id /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>

Próximos passos

Para obter informações sobre outros comandos, consulte CLI da Grade de Eventos do Azure.

Pré-requisitos

Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
A versão mais recente do SDK do .NET Core para seu sistema operacional.
Obtenha a versão mais recente do SDK de Gerenciamento de Grade de Eventos do Microsoft Azure .NET.
Obtenha a versão mais recente da biblioteca de Identidades do Azure.
Um recurso dos Serviços de Comunicação do Azure.

Registrar o provedor de recursos da Grade de Eventos

Este artigo descreve como registrar o provedor de recursos de grade de eventos. Se você usou a Grade de Eventos antes na mesma assinatura, pule para a próxima seção.

No portal do Azure, execute as seguintes etapas:

No menu à esquerda, selecione Assinaturas.
Selecione a Subscrição que pretende utilizar para a Grelha de Eventos na lista de subscrições.
Na página Assinatura, selecione Provedores de recursos em Configurações no menu à esquerda.
Procure Microsoft.EventGrid e confirme se o Status não está registrado.
Selecione Microsoft.EventGrid na lista de provedores.
Selecione Registrar na barra de comandos.
Atualize para verificar se o status de Microsoft.EventGrid foi alterado para Registrado.

Instalando o SDK

Primeiro, instale a biblioteca de Gerenciamento de Grade de Eventos do Microsoft Azure para .NET com NuGet:

dotnet add package Azure.ResourceManager.EventGrid;

Inclua o SDK de Gerenciamento de Grade de Eventos em seu projeto C#:

using Microsoft.Azure.Management.EventGrid;
using Microsoft.Azure.Management.EventGrid.Models;

Autenticando com a biblioteca de Identidades do Azure

Pré-requisitos:

Crie um aplicativo e uma entidade de serviço do Microsoft Entra e configure um segredo de cliente ou certificado confiável emitido pela autoridade de certificação seguindo as instruções aqui.
Armazene o segredo ou o certificado no Cofre do Azure Keyvault.
Dê ao colaborador ou proprietário acesso à assinatura desse aplicativo seguindo as instruções aqui.
Leia mais sobre como autorizar o acesso aos recursos da Grade de Eventos aqui.

A biblioteca de Identidade do Azure fornece suporte à autenticação de token Microsoft Entra ID (Anteriormente Azure Ative Directory) no SDK do Azure. Ele fornece um conjunto de implementações TokenCredential, que podem ser usadas para construir clientes SDK do Azure que dão suporte à autenticação de token Microsoft Entra. Pode ler mais sobre o assunto aqui.

Inclua a biblioteca de cliente do Azure Identity para .NET com NuGet:

dotnet add package Azure.Identity;
dotnet add package Azure.Security.KeyVault.Secrets

Incluir a biblioteca de Identidade do Azure em seu projeto C#

using Microsoft.Azure.Identity;
using Azure.Security.KeyVault.Secrets

Você pode passar as credenciais secretas ou as credenciais de certificado para obter o token de acesso, com base em como sua entidade de serviço está configurada.

Obter token de acesso usando credencial secreta

Para obter as credenciais secretas, você precisa lê-las do Keyvault criado no Pré-requisito #2 usando SecretClient.

// Authenticate the Keyvault client with DefaultAzureCredential and get the secret.
SecretClient secretClient = new SecretClient(new Uri("https://myvault.vault.azure.net/"), new DefaultAzureCredential());
string clientSecret = await secretClient.GetSecretAsync(secretName).Value;

// Get access token using secret credentials
string[] scopes = { "https://management.azure.com/.default" };
var application = ConfidentialClientApplicationBuilder
                    .Create('your-servicePrincipal-appId')
                    .WithAuthority(authorityUri: new Uri(authority), validateAuthority: true)
                    .WithTenantId('your-tenant_id')
                    .WithClientSecret(clientSecret)
                    .Build();

var token = await application
                .AcquireTokenForClient(scopes)
                .ExecuteAsync();

Obter token de acesso usando a credencial de certificado

Para obter as credenciais do certificado, você precisa lê-lo do Keyvault criado no Pré-requisito #2 usando CertificateClient.

Leia mais sobre a autoridade de configuração do aplicativo Microsoft Entra aqui

// Authenticate the certificate client with DefaultAzureCredential and get the certificate.
CertificateClient certificateClient = new SecretClient(new Uri("https://myvault.vault.azure.net/"), new DefaultAzureCredential());
X509Certificat2 cert = await certificateClient.DownloadCertificateAsync(certificateName);

// Get access token using certificate credentials
string[] scopes = { "https://management.azure.com/.default" };
string authority = "https://login.microsoftonline.com/<tenant>/";
var application = ConfidentialClientApplicationBuilder
                    .Create('<servicePrincipal-appId>')
                    .WithAuthority(authorityUri: new Uri(authority), validateAuthority: true)
                    .WithTenantId("<tenantId>")
                    .WithCertificate(cert)
                    .Build();

var token = await application
                .AcquireTokenForClient(scopes)
                .WithSendX5C(true)
                .ExecuteAsync();

Autenticar EventGridManagementClient com token de acesso usando credenciais secretas ou de certificado

// Authenticate EventGridManagementClient with Microsoft Entra ID access token credential
eventGridClient = new EventGridManagementClient(new Uri("https://management.azure.com/"),
    new TokenCredentials(token.AccessToken));

eventGridClient.SubscriptionId = 'your_subscripiton_id';

Criar Subscrição de Evento

Este exemplo de código mostra como criar a assinatura de evento para o ponto de extremidade do assinante do webhook.

string webhookUri = $"<webhookUri>";
string resourceId="/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>";
string[] includedEventTypes = new string[]{ "Microsoft.Communication.SMSReceived", 
                                            "Microsoft.Communication.SMSDeliveryReportReceived"
                                            };

EventSubscription eventSubscription = new EventSubscription(
    name: "<eventSubscriptionName>",
    eventDeliverySchema: "EventGridSchema",
    filter: new EventSubscriptionFilter(
    includedEventTypes: includedEventTypes),
    destination: new WebHookEventSubscriptionDestination(webhookUri));

await eventGridClient.EventSubscriptions.CreateOrUpdateAsync(
    scope: resourceId,
    eventSubscriptionName: "<eventSubscriptionName>",
    eventSubscriptionInfo: eventSubscription);

Atualizar subscrição de eventos

Este exemplo de código mostra como atualizar a assinatura do evento para adicionar mais eventos que você deseja receber no ponto de extremidade do assinante do webhook.

string webhookUri = $"<webhookUri>";
string resourceId="/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>";
string[] additionalEventTypes = new string[]{ 
                                            "Microsoft.Communication.ChatMessageReceived"
                                        };

await eventGridClient.EventSubscriptions.UpdateAsync(
    scope: resourceId,
    eventSubscriptionName: "<eventSubscriptionName>",
    eventSubscriptionUpdateParameters: new EventSubscriptionUpdateParameters(
            filter: new EventSubscriptionFilter(includedEventTypes: additionalEventTypes)));

Excluir assinatura de evento

Este exemplo de código mostra como excluir a assinatura de evento para o ponto de extremidade do assinante do webhook.

string webhookUri = $"<webhookUri>";
string resourceId="/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>";

await eventGridClient.EventSubscriptions.DeleteAsync(
    scope: resourceId,
    eventSubscriptionName: "<eventSubscriptionName>");

Pré-requisitos

Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
Instalar o módulo Azure Az PowerShell
Um recurso dos Serviços de Comunicação do Azure
Crie um Webhook para receber eventos. Entrega de eventos Webhook

Registrar o provedor de recursos da Grade de Eventos

Este artigo descreve como registrar o provedor de recursos de grade de eventos. Se você usou a Grade de Eventos antes na mesma assinatura, pule para a próxima seção.

Execute o seguinte comando:

Register-AzResourceProvider -ProviderNamespace Microsoft.EventGrid

Pode demorar algum tempo para o registo terminar. Para ver o estado, execute:

Get-AzResourceProvider -ProviderNamespace Microsoft.EventGrid

Quando RegistrationStatus está Registered, está pronto para continuar.

Criar subscrição de evento

Primeiro, certifique-se de instalar o módulo Az.EventGrid Serviços de Comunicação do Azure usando o comando a seguir.

PS C:\> Install-Module Az.EventGrid

Entre na sua assinatura do Azure com o comando Connect-AzAccount e siga as instruções na tela:
```
Connect-AzAccount
```
Se sua identidade estiver associada a mais de uma assinatura, defina sua assinatura ativa como assinatura do recurso Web PubSub que você deseja mover.
```
$context = Get-AzSubscription -SubscriptionId <subscription-id>
Set-AzContext $context
```

Para criar uma assinatura de evento usando o Azure PowerShell, use o New-AzEventGridSubscription comando.

$includedEventTypes = "Microsoft.Communication.SMSReceived", "Microsoft.Communication.SMSDeliveryReportReceived"
New-AzEventGridSubscription 
    -EndpointType webhook
    -Endpoint https://azureeventgridviewer.azurewebsites.net/api/updates
    -EventSubscriptionName EventsWebhookSubscription 
    -IncludedEventType $includedEventTypes
    -ResourceId "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>"

Para obter uma lista de eventos dos Serviços de Comunicação, consulte Eventos dos Serviços de Comunicação.

Listar assinaturas de eventos

Para listar todas as assinaturas de eventos existentes configuradas para um recurso dos Serviços de Comunicação do Azure, usando o Azure PowerShell, use o Get-AzEventGridSubscription comando.

Get-AzEventGridSubscription 
    -ResourceId "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>"

Atualizar subscrição de eventos

Para atualizar uma assinatura de evento existente usando o Azure PowerShell, use o Update-AzEventGridSubscription comando.

$includedEventTypes = "Microsoft.Communication.SMSReceived", "Microsoft.Communication.SMSDeliveryReportReceived", "Microsoft.Communication.ChatMessageReceived"
Update-AzEventGridSubscription 
    -EventSubscriptionName ES2 
    -IncludedEventType $includedEventTypes
    -ResourceId "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>" 
    -Endpoint https://azureeventgridviewer2.azurewebsites.net/api/updates
    -SubjectEndsWith "phoneNumber"

Excluir assinatura de evento

Para excluir uma assinatura de evento existente usando o Azure PowerShell, use o Remove-AzEventGridSubscription comando.

Get-AzResource 
    -ResourceId "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>" | Remove-AzEventGridSubscription -EventSubscriptionName ES2

Próximos passos

Para obter informações sobre outros comandos, consulte Az.EventGrid PowerShell Module.

Partilhar via

Pré-requisitos

Registrar o provedor de recursos da Grade de Eventos

Criar subscrição de evento

Atualizar subscrição de eventos

Excluir assinatura de evento

Próximos passos

Pré-requisitos

Registrar o provedor de recursos da Grade de Eventos

Criar subscrição de evento

Listar assinaturas de eventos

Atualizar subscrição de eventos

Excluir assinatura de evento

Próximos passos

Pré-requisitos

Registrar o provedor de recursos da Grade de Eventos

Instalando o SDK

Autenticando com a biblioteca de Identidades do Azure

Pré-requisitos:

Criar Subscrição de Evento

Atualizar subscrição de eventos

Excluir assinatura de evento

Pré-requisitos

Registrar o provedor de recursos da Grade de Eventos

Criar subscrição de evento

Listar assinaturas de eventos

Atualizar subscrição de eventos

Excluir assinatura de evento

Próximos passos

Comentários

Recursos adicionais

Partilhar via

Guia de início rápido: inscrever-se em eventos dos Serviços de Comunicação do Azure

Pré-requisitos

Registrar o provedor de recursos da Grade de Eventos

Criar subscrição de evento

Atualizar subscrição de eventos

Excluir assinatura de evento

Próximos passos

Pré-requisitos

Registrar o provedor de recursos da Grade de Eventos

Criar subscrição de evento

Listar assinaturas de eventos

Atualizar subscrição de eventos

Excluir assinatura de evento

Próximos passos

Pré-requisitos

Registrar o provedor de recursos da Grade de Eventos

Instalando o SDK

Autenticando com a biblioteca de Identidades do Azure

Pré-requisitos:

Criar Subscrição de Evento

Atualizar subscrição de eventos

Excluir assinatura de evento

Pré-requisitos

Registrar o provedor de recursos da Grade de Eventos

Criar subscrição de evento

Listar assinaturas de eventos

Atualizar subscrição de eventos

Excluir assinatura de evento

Próximos passos

Comentários

Recursos adicionais