Guia de início rápido: publicar em tópicos de namespace e consumir eventos na Grade de Eventos do Azure

2025-06-23

Neste início rápido, você puxa a entrega usando o curl comando bash shell para publicar, receber e reconhecer eventos. Use os comandos da CLI do Azure para criar recursos da Grade de Eventos do Azure. Este artigo é adequado para um teste rápido da funcionalidade de entrega pull.

Para obter o código de exemplo que usa os SDKs do plano de dados, consulte estes recursos:

Para obter mais informações sobre o modelo de entrega pull, consulte Conceitos de namespace da Grade de Eventos do Azure e Pull delivery with HTTP articles.

Se não tiver uma conta do Azure, crie uma conta gratuita antes de começar.

Pré-requisitos

Utilize o ambiente Bash no Azure Cloud Shell. Para mais informações, veja Get started with Azure Cloud Shell.
Se preferir executar comandos de referência da CLI localmente, instale o CLI do Azure. Se estiver a usar Windows ou macOS, considere executar o Azure CLI num contentor Docker. Para obter mais informações, consulte Como executar a CLI do Azure em um contêiner do Docker.
- Se você estiver usando uma instalação local, entre na CLI do Azure usando o comando az login . Para concluir o processo de autenticação, siga os passos exibidos no seu terminal. Para outras opções de entrada, consulte Autenticar no Azure usando a CLI do Azure.
- Quando solicitado, instale a extensão do Azure CLI na primeira utilização. Para obter mais informações sobre extensões, consulte Usar e gerenciar extensões com a CLI do Azure.
- Execute az version para descobrir a versão e as bibliotecas dependentes que estão instaladas. Para atualizar para a versão mais recente, execute az upgrade.

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

Criar um grupo de recursos

Crie um grupo de recursos do Azure com o comando az group create. Use este grupo de recursos para conter todos os recursos criados neste artigo.

As etapas gerais para usar o Cloud Shell para executar comandos são:

Selecione Abrir Cloud Shell para ver uma janela do Azure Cloud Shell no painel direito.
Copie o comando e cole na janela do Azure Cloud Shell.
Pressione ENTER para executar o comando.

Declare uma variável para manter o nome de um grupo de recursos do Azure. Especifique um nome para o grupo de recursos substituindo <your-resource-group-name> pelo seu valor.
```
resource_group="<your-resource-group-name>"
```
Crie um grupo de recursos. Você pode alterar o local para qualquer local do Azure.
```
az group create --name $resource_group --location eastus
```

Habilitar o provedor de recursos da Grade de Eventos

Se esta for a primeira vez que você estiver usando 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, ficas pronto para continuar.

Criar um espaço de nomes

Um namespace de Grade de Eventos fornece um ponto de extremidade definido pelo usuário para o qual você posta seus eventos. O exemplo a seguir cria um namespace em seu grupo de recursos usando Bash no Azure Cloud Shell. O nome do namespace deve ser exclusivo porque faz parte de uma entrada DNS (Sistema de Nomes de Domínio). Um nome de namespace deve atender às seguintes regras:

Deve ter entre 3-50 caracteres.
Deve ser regionalmente único.
Apenas os caracteres permitidos são: a-z, A-Z, 0-9 e -
Não deve começar com prefixos de palavras-chave reservadas como Microsoft, Systemou EventGrid.

Declare uma variável para armazenar o nome do namespace do Grid de Eventos. Especifique um nome para o namespace substituindo <your-namespace-name> pelo seu valor.
```
namespace="<your-namespace-name>"
```

Crie um namespace. Talvez você queira alterar o local onde o implanta.

az eventgrid namespace create --resource-group $resource_group --name $namespace --location eastus

Criar um tópico de namespace

Crie um tópico que contenha todos os eventos publicados no endpoint do namespace.

Declare uma variável para manter o nome do tópico do namespace. Especifique um nome para o tópico de namespace substituindo <your-topic-name> pelo seu valor.
```
topic="<your-topic-name>"
```

Crie seu tópico de namespace:

az eventgrid namespace topic create --resource-group $resource_group --name $topic --namespace-name $namespace

Criar uma subscrição de evento

Crie uma assinatura de evento definindo seu modo de entrega como fila, que oferece suporte à entrega pull. Para obter mais informações sobre todas as opções de configuração, consulte API REST da Grade de Eventos do Azure.

Declare uma variável para conter o nome de uma assinatura de evento do seu tópico de namespace. Especifique um nome para a assinatura do evento substituindo <your-event-subscription-name> pelo seu valor.
```
event_subscription="<your-event-subscription-name>"
```

Crie uma assinatura de evento para o tópico de namespace.

az eventgrid namespace topic event-subscription create --resource-group $resource_group --topic-name $topic --name $event_subscription --namespace-name $namespace --delivery-configuration "{deliveryMode:Queue,queue:{receiveLockDurationInSeconds:300,maxDeliveryCount:4,eventTimeToLive:P1D}}"

Enviar eventos para o seu tópico

Envie um evento de exemplo para o tópico namespace seguindo as etapas nesta seção.

Listar chaves de acesso de namespace

Obtenha as chaves de acesso associadas ao namespace que você criou. Você precisa de um deles para autenticar ao publicar eventos. Para listar suas chaves, obtenha o ID completo do recurso de namespace. Execute o seguinte comando:
```
namespace_resource_id=$(az eventgrid namespace show --resource-group $resource_group --name $namespace --query "id" --output tsv)
```

Obtenha a primeira chave do namespace:

key=$(az eventgrid namespace list-key --resource-group $resource_group --namespace-name $namespace --query "key1" --output tsv)

Publicar um evento

Recupere o nome do host do namespace. Você o usa para compor o ponto de extremidade HTTP do namespace para o qual os eventos são enviados. As operações a seguir foram disponibilizadas pela primeira vez com a versão 2023-06-01-previewda API.
```
publish_operation_uri="https://"$(az eventgrid namespace show -g $resource_group -n $namespace --query "topicsConfiguration.hostname" --output tsv)"/topics/"$topic:publish?api-version=2023-06-01-preview
```

Crie um exemplo de evento compatível com CloudEvents :

event=' { "specversion": "1.0", "id": "'"$RANDOM"'", "type": "com.yourcompany.order.ordercreatedV2", "source" : "/mycontext", "subject": "orders/O-234595", "time": "'`date +%Y-%m-%dT%H:%M:%SZ`'", "datacontenttype" : "application/json", "data":{ "orderId": "O-234595", "url": "https://yourcompany.com/orders/o-234595"}} '

O elemento data serve como a carga útil do seu evento. Qualquer JSON bem formado pode ir para este campo. As propriedades que podem entrar em um evento também são conhecidas como atributos de contexto. Para obter mais informações, consulte CloudEvents.

Use CURL para enviar o evento para o tópico. CURL é um utilitário que envia os pedidos HTTP.

curl -X POST -H "Content-Type: application/cloudevents+json" -H "Authorization:SharedAccessKey $key" -d "$event" $publish_operation_uri

Receba o evento

Você recebe eventos do Event Grid usando um ponto de extremidade que se refere a uma subscrição de evento.

Componha o ponto de extremidade executando o seguinte comando:

receive_operation_uri="https://"$(az eventgrid namespace show --resource-group $resource_group --name $namespace --query "topicsConfiguration.hostname" --output tsv)"/topics/"$topic/eventsubscriptions/$event_subscription:receive?api-version=2023-06-01-preview

Envie uma solicitação para consumir o evento:

curl -X POST -H "Content-Type: application/json" -H "Authorization:SharedAccessKey $key" $receive_operation_uri

Reconhecer um evento

Depois de receber um evento, você passa esse evento para o seu aplicativo para processamento. Após processares com sucesso o teu evento, já não precisas que ele esteja na subscrição do evento. Para instruir a Grade de Eventos a eliminar o evento, deve reconhecê-lo utilizando o token de bloqueio que obteve na resposta da operação de receção.

Na secção anterior, recebeste uma resposta que inclui um objeto brokerProperties com uma propriedade lockToken. Copie o valor do token de bloqueio e defina-o em uma variável de ambiente:
```
lockToken="<paste-the-lock-token-here>"
```
Crie a carga útil da operação de reconhecimento, que especifica o token de bloqueio para o evento que você deseja ser reconhecido.
```
acknowledge_request_payload=' { "lockTokens": ["'$lockToken'"]} '
```

Prossiga com a criação da string com o URI da operação de confirmação:

acknowledge_operation_uri="https://"$(az eventgrid namespace show -g $resource_group -n $namespace --query "topicsConfiguration.hostname" --output tsv)"/topics/"$topic/eventsubscriptions/$event_subscription:acknowledge?api-version=2023-06-01-preview

Por fim, envie uma solicitação para confirmar o evento recebido:

curl -X POST -H "Content-Type: application/json" -H "Authorization:SharedAccessKey $key" -d "$acknowledge_request_payload" $acknowledge_operation_uri

Se a operação de confirmação for executada antes que o token de bloqueio expire (300 segundos conforme definido quando criamos a assinatura do evento), você verá uma resposta como o exemplo a seguir:

{"succeededLockTokens":["CiYKJDQ4NjY5MDEyLTk1OTAtNDdENS1BODdCLUYyMDczNTYxNjcyMxISChDZae43pMpE8J8ovYMSQBZS"],"failedLockTokens":[]}

Próximo passo

Para saber mais sobre o modelo de entrega pull, consulte Pull delivery with HTTP.