Início Rápido: Encaminhar eventos personalizados para o ponto de extremidade da Web com a CLI do Azure e com a Grade de Eventos

Artigo
01/10/2024

A Grade de Eventos do Azure é um serviço de eventos para a nuvem. Neste artigo, você usa a CLI do Azure para criar um tópico personalizado, assinar esse tópico e disparar o evento para exibir o resultado.

Normalmente, você envia eventos para um ponto de extremidade que processa os dados de evento e realiza ações. No entanto, para simplificar este artigo, você enviará os eventos para um aplicativo Web que coleta e exibe as mensagens.

Ao concluir, você verá que os dados do evento foram enviados para um aplicativo Web.

Screenshot showing the Event Grid Viewer sample with a sample event.

Caso você não tenha uma assinatura do Azure, crie uma conta gratuita do Azure antes de começar.

Pré-requisitos

Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Início Rápido para Bash no Azure Cloud Shell.
Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Para execuções no Windows ou no macOS, considere executar a CLI do Azure em um contêiner do Docker. Para obter mais informações, confira Como executar a CLI do Azure em um contêiner do Docker.
- Se estiver usando uma instalação local, entre com a CLI do Azure usando o comando az login. Para concluir o processo de autenticação, siga as etapas exibidas no terminal. Para ver outras opções de entrada, confira Conectar-se com a CLI do Azure.
- Quando solicitado, instale a extensão da CLI do Azure no primeiro uso. Para obter mais informações sobre extensões, confira Usar extensões com a CLI do Azure.
- Execute az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para fazer a atualização para a versão mais recente, execute az upgrade.

Este artigo exige a versão 2.0.70 ou posterior da CLI do Azure. Se você está usando o Azure Cloud Shell, a versão mais recente já está instalada.

Criar um grupo de recursos

Os tópicos de Grade de Eventos são recursos do Azure e devem ser colocados em um grupo de recursos do Azure. O grupo de recursos do Azure é uma coleção lógica na qual os recursos do Azure são implantados e gerenciados.

Crie um grupo de recursos com o comando az group create. O exemplo a seguir cria um grupo de recursos chamado gridResourceGroup no local westus2. Se você selecionar Experimentar, verá a janela do Azure Cloud Shell no painel direito. Em seguida, selecione Copiar para copiar o comando e colá-lo na janela do Azure Cloud Shell e pressione ENTER para executar o comando. Se desejar, altere o nome do grupo de recursos e o local.

az group create --name gridResourceGroup --location westus2

Habilitar o provedor de recursos da Grade de Eventos

Se você ainda não tiver usado a Grade de Eventos em sua assinatura do Azure, talvez seja necessário registrar o provedor de recursos desse serviço. Execute o seguinte comando para registrar o provedor:
```
az provider register --namespace Microsoft.EventGrid
```
A conclusão do registro pode demorar um pouco. Para verificar o status, execute o seguinte comando:
```
az provider show --namespace Microsoft.EventGrid --query "registrationState"
```
Quando registrationState for Registered, você está pronto para continuar.

Criar um tópico personalizado

Um tópico de Grade de Eventos fornece um ponto de extremidade definido pelo usuário no qual você posta seus eventos. O exemplo a seguir cria o tópico personalizado em seu grupo de recursos usando Bash no Azure Cloud Shell. Substitua <your-topic-name> por um nome exclusivo para o tópico. O nome do tópico personalizado deve ser exclusivo porque faz parte da entrada DNS (Sistema de Nomes de Domínio). Além disso, ela deve ter entre 3 e 50 caracteres e conter apenas valores a-z, A-Z, 0-9 e "-"

Copie o comando a seguir, especifique um nome para o tópico e pressione ENTER para executar o comando.
```
topicname=<your-topic-name>
```

Use o comando az eventgrid topic create para criar um tópico personalizado.

az eventgrid topic create --name $topicname -l westus2 -g gridResourceGroup

Criar um ponto de extremidade de mensagem

Antes de assinar o tópico personalizado, vamos criar o ponto de extremidade para a mensagem do evento. Normalmente, o ponto de extremidade executa ações com base nos dados de evento. Para simplificar esse início rápido, implante um aplicativo web predefinido que exiba as mensagens do evento. A solução implantada inclui um plano do Serviço de Aplicativo, um aplicativo Web do Aplicativo do Serviço de e o código-fonte do GitHub.

Copie o comando a seguir, especifique um nome para o aplicativo Web (visualizador da Grade de Eventos de exemplo) e pressione ENTER para executar o comando. Substitua <your-site-name> por um nome exclusivo para o aplicativo Web. O nome do aplicativo Web deve ser exclusivo, pois é parte de uma entrada DNS.
```
sitename=<your-site-name>
```

Execute o az deployment group create para implantar seu aplicativo Web usando um modelo do Azure Resource Manager.

az deployment group create \
  --resource-group gridResourceGroup \
  --template-uri "https://raw.githubusercontent.com/Azure-Samples/azure-event-grid-viewer/master/azuredeploy.json" \
  --parameters siteName=$sitename hostingPlanName=viewerhost

A implantação pode levar alguns minutos para ser concluída. Depois que a implantação for bem-sucedida, exiba seu aplicativo Web para garantir que ele esteja em execução. Em um navegador da Web, navegue até: https://<your-site-name>.azurewebsites.net

Você deve ver o site sem mensagens exibidas no momento.

Você assina um tópico da Grade de Eventos para indicar à Grade de Eventos quais eventos você deseja acompanhar e para onde enviá-los. O exemplo a seguir assina o tópico personalizado que você criou e transmite a URL do seu aplicativo Web como o ponto de extremidade para notificação de eventos.

O ponto de extremidade para seu aplicativo Web deve incluir o sufixo /api/updates/.

Copie o comando a seguir, substitua $sitename pelo nome do aplicativo Web criado na etapa anterior e pressione ENTER para executar o comando.
```
endpoint=https://$sitename.azurewebsites.net/api/updates
```

Execute o comando a seguir para obter a ID do recurso do tópico que você criou.

topicresourceid=$(az eventgrid topic show --resource-group gridResourceGroup --name $topicname --query "id" --output tsv)

Execute o comando a seguir para criar uma assinatura para o tópico personalizado usando o ponto de extremidade.
```
az eventgrid event-subscription create \
  --source-resource-id $topicresourceid \
  --name demoViewerSub \
  --endpoint $endpoint      
```
Exiba novamente o seu aplicativo Web e observe que um evento de validação de assinatura foi enviado a ele. Selecione o ícone de olho para expandir os dados de evento. A Grade de Eventos envia o evento de validação de modo que o ponto de extremidade possa verificar se ele deseja receber os dados de evento. O aplicativo Web inclui o código para validar a assinatura.

Enviar um evento para o tópico personalizado

Vamos disparar um evento para ver como a Grade de Eventos distribui a mensagem para o ponto de extremidade. Primeiro, vamos obter a URL e a chave para o tópico personalizado.

endpoint=$(az eventgrid topic show --name $topicname -g gridResourceGroup --query "endpoint" --output tsv)
key=$(az eventgrid topic key list --name $topicname -g gridResourceGroup --query "key1" --output tsv)

Para simplificar este artigo, use dados de evento de exemplo para enviar ao tópico personalizado. Normalmente, um aplicativo ou serviço do Azure enviaria os dados de evento. O exemplo a seguir cria os dados de evento de exemplo:

event='[ {"id": "'"$RANDOM"'", "eventType": "recordInserted", "subject": "myapp/vehicles/motorcycles", "eventTime": "'`date +%Y-%m-%dT%H:%M:%S%z`'", "data":{ "make": "Ducati", "model": "Monster"},"dataVersion": "1.0"} ]'

O elemento data do JSON é a carga do evento. Qualquer JSON bem formado pode ficar nesse campo. Você também pode usar o campo de assunto para roteamento e filtragem avançados.

CURL é um utilitário que envia solicitações HTTP. Neste artigo, use o CURL para enviar o evento ao tópico.

curl -X POST -H "aeg-sas-key: $key" -d "$event" $endpoint

Você disparou o evento, e a Grade de Eventos enviou a mensagem para o ponto de extremidade configurado durante a assinatura. Exiba seu aplicativo Web para ver o evento que você acabou de enviar.

[{
  "id": "1807",
  "eventType": "recordInserted",
  "subject": "myapp/vehicles/motorcycles",
  "eventTime": "2017-08-10T21:03:07+00:00",
  "data": {
    "make": "Ducati",
    "model": "Monster"
  },
  "dataVersion": "1.0",
  "metadataVersion": "1",
  "topic": "/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.EventGrid/topics/{topic}"
}]

Limpar os recursos

Caso planeje continuar a trabalhar com esse evento ou com o aplicativo visualizador de evento, não limpe os recursos criados neste artigo. Caso contrário, use os comandos a seguir para excluir os recursos criados por você neste artigo.

az group delete --name gridResourceGroup

Próximas etapas

Agora que você sabe como criar tópicos e assinaturas de evento, saiba mais sobre como a Grade de Eventos pode ajudá-lo:

Confira os exemplos a seguir para saber mais sobre como publicar e consumir eventos na Grade de Eventos usando diferentes linguagens de programação.