Início Rápido: Publicar em tópicos de namespace e consumir eventos na Grade de Eventos do Azure

2025-06-24

Neste guia de início rápido, você fará a entrega por pull usando o comando bash shell do curl para publicar, receber e reconhecer eventos. Use 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 de 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 por pull, consulte os artigos Conceitos de namespace da Grade de Eventos do Azure e Entrega com pull usando HTTP.

Se você ainda 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 obter mais informações, confira Introdução ao Azure Cloud Shell.
Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Se você estiver executando 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 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 as etapas exibidas em seu terminal. Para obter outras opções de entrada, consulte Autenticar no Azure usando 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 e gerenciar extensões com a CLI do Azure.
- Execute o comando az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para atualizar 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ê usar 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 esse 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 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 namespace

Um namespace da Grade de Eventos fornece um ponto de extremidade definido pelo usuário ao qual você posta seus eventos. O exemplo a seguir cria um namespace em seu grupo de recursos usando o 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 e 50 caracteres.
Deve ser regionalmente exclusivo.
Somente caracteres permitidos são: a-z, A-Z, 0-9 e -
Ele não deve começar com prefixos de palavra-chave reservados, como Microsoft, Systemou EventGrid.

Declare uma variável para manter o nome do seu namespace de Grade 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 em que 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 contém todos os eventos publicados no ponto de extremidade do namespace.

Declare uma variável para manter o nome do tópico do namespace. Especifique um nome para o tópico do 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 assinatura de evento

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

Declare uma variável para manter o nome de uma assinatura de evento em 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 do 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 tópico

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

Listar chaves de acesso do namespace

Obtenha as chaves de acesso associadas ao namespace que você criou. Você precisa de um deles para se autenticar ao publicar eventos. Para listar suas chaves, obtenha a ID completa do recurso do namespace. Execute o comando a seguir:
```
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. Use-o 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 evento compatível com CloudEvents de exemplo:

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 é o conteúdo do evento. Qualquer JSON bem formado pode ficar nesse 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.

Utilize CURL para enviar o evento para o tópico. O cURL é um utilitário que envia solicitações HTTP.

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

Receber o evento

Você recebe eventos da Grade de Eventos usando um ponto de extremidade que se refere a uma assinatura de evento.

Componha o endpoint 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 seu aplicativo para processamento. Depois de processar seu evento com êxito, você não precisará mais desse evento para estar em sua assinatura de evento. Para instruir a Grade de Eventos a excluir o evento, você o confirma usando o token de bloqueio que obteve na resposta da operação de recebimento.

Na seção anterior, você recebeu 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 o conteúdo da operação de confirmação, que especifica o lock token para o evento que você deseja confirmar.
```
acknowledge_request_payload=' { "lockTokens": ["'$lockToken'"]} '
```

Prossiga com a compilação da cadeia de caracteres 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 reconhecer 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 do token de bloqueio expirar (300 segundos conforme definido quando criamos a assinatura de evento), você deverá ver uma resposta como o exemplo a seguir:

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

Próxima etapa

Para saber mais sobre o modelo de entrega pull, consulte a entrega pull usando HTTP.