Guia de início rápido: rotear eventos personalizados para o ponto de extremidade da Web com a CLI do Azure e a Grade de Eventos

Artigo
01/10/2024

O Azure Event Grid é um serviço de eventos para a cloud. Neste artigo, a CLI do Azure serve para criar um tópico personalizado, subscrever o tópico personalizado e acionar o evento para ver o resultado.

Normalmente, envia eventos para um ponto final que processa os dados de eventos e efetua ações. No entanto, para simplificar este artigo, vai enviar eventos para uma aplicação Web que recolhe e apresenta as mensagens.

Quando tiver terminado, verá que os dados do evento foram enviados para a aplicação Web.

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

Se não tiver uma subscrição 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, consulte Guia de início rápido para Bash no Azure Cloud Shell.
Se preferir executar comandos de referência da CLI localmente, instale a CLI do Azure. Se estiver a utilizar o Windows ou macOS, considere executar a CLI do Azure num contentor Docker. Para obter mais informações, consulte Como executar a CLI do Azure em um contêiner do Docker.
- Se estiver a utilizar uma instalação local, inicie sessão no CLI do Azure ao utilizar o comando az login. Para concluir o processo de autenticação, siga os passos apresentados no seu terminal. Para outras opções de entrada, consulte Entrar com a CLI do Azure.
- Quando solicitado, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre as extensões, veja Utilizar extensões com o CLI do Azure.
- Execute o comando az version para localizar a versão e as bibliotecas dependentes instaladas. Para atualizar para a versão mais recente, execute o comando az upgrade.

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

Criar um grupo de recursos

Os tópicos do Event Grid são recursos do Azure e têm de ser colocados num grupo de recursos do Azure. Um grupo de recursos é uma coleção lógica na qual os recursos do Azure são implementados e geridos.

Crie um grupo de recursos com o comando az group create. O exemplo seguinte cria um grupo de recursos com o nome gridResourceGroup na localização 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. Altere o nome do grupo de recursos e o local, se desejar.

az group create --name gridResourceGroup --location westus2

Habilitar o provedor de recursos da Grade de Eventos

Se você não tiver usado anteriormente a Grade de Eventos em sua assinatura do Azure, talvez seja necessário registrar o provedor de recursos da Grade de Eventos. 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 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 seu 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, ele deve estar entre 3-50 caracteres e conter apenas os 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 az eventgrid topic create comando para criar um tópico personalizado.

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

Criar um ponto final de mensagem

Antes de subscrever o tópico personalizado, vamos criar o ponto final para a mensagem de evento. Normalmente, o ponto final executa as ações com base nos dados do evento. Para simplificar esse início rápido, implante um aplicativo Web pré-criado que exibe as mensagens do evento. A solução implementada inclui um plano do Serviço de Aplicações, uma aplicação Web do Serviço de Aplicações e o código de origem do GitHub.

Copie o comando a seguir, especifique um nome para o aplicativo Web (exemplo de Visualizador de Grade de Eventos) e pressione ENTER para executar o comando. Substitua <your-site-name> por um nome exclusivo para a aplicação Web. O nome da aplicação Web deve ser exclusivo, porque faz parte da entrada DNS.
```
sitename=<your-site-name>
```

Execute o para implantar o az deployment group create 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. Após a implementação ter sido concluída com êxito, verifique a aplicação Web para verificar se está em execução. Num browser, navegue para: https://<your-site-name>.azurewebsites.net

Deverá ver o site sem mensagens atualmente apresentadas.

Você se inscreve em um tópico da Grade de Eventos para informar à Grade de Eventos quais eventos deseja acompanhar e para onde enviar esses eventos. O exemplo seguinte subscreve o tópico personalizado que criou e transmite o URL da aplicação Web como o ponto final para a notificação de eventos.

O ponto final para a aplicação Web tem de 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 seguinte comando 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      
```
Verifique a aplicação Web novamente e repare que um evento de validação de subscrição foi enviado para a mesma. Selecione o ícone do olho para expandir os dados do evento. O Event Grid envia o evento de validação para que o ponto final possa verificar que pretende receber dados de eventos. A aplicação Web inclui código para validar a subscrição.

Enviar um evento para o tópico personalizado

Vamos acionar um evento para ver como o Event Grid distribui a mensagem para o ponto final. Em primeiro lugar, vamos obter o URL e a chave do 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, vai utilizar dados do evento de exemplo para enviar para o tópico personalizado. Normalmente, uma aplicação ou serviço do Azure enviaria os dados do evento. O exemplo seguinte cria dados do 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 é o payload do evento. Qualquer JSON bem formado pode ir para este campo. Também pode utilizar o campo do assunto para encaminhamento e filtragem avançados.

CURL é um utilitário que envia os pedidos HTTP. Neste artigo, utilize o CURL para enviar o evento para o tópico.

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

Acionou o evento e o Event Grid enviou a mensagem para o ponto final que configurou ao subscrever. Verifique a aplicação Web para ver o evento que acabámos 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}"
}]

Clean up resources (Limpar recursos)

Se quiser continuar a trabalhar com este evento ou com a aplicação de visualizador de eventos, não limpe os recursos criados neste artigo. Caso contrário, utilize o comando seguinte para eliminar os recursos que criou neste artigo.

az group delete --name gridResourceGroup

Próximos passos

Agora que sabe como criar tópicos e subscrições de eventos, saiba mais sobre o que o Event Grid pode ajudá-lo a fazer:

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