Publicar nos tópicos de namespace e consumir eventos na Grade de Eventos do Azure

Artigo
02/20/2024

Este artigo fornece uma rápida introdução à entrega por pull usando o comando curl shell do bash para publicar, receber e reconhecer eventos. Os recursos da Grade de Eventos são criados usando os comandos da CLI. Este artigo é adequado para um teste rápido da funcionalidade de entrega de pull. Para obter o código de exemplo usando os SDKs do plano de dados, consulte .NET ou os exemplos do Java. No Java, fornecemos o código de exemplo em dois artigos: inícios rápidos de publicar eventos e receber eventos. Para obter mais informações sobre o modelo de entrega por pull, consulte os artigos de conceitos e visão geral da entrega por pull.

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 saber mais, 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

Crie um grupo de recursos do Azure com o comando az group create. Você usa 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 e cole o comando 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> por um valor de sua preferência.
```
resource_group="<your-resource-group-name>"
```
Crie um grupos de recursos. Altere o local conforme desejar.
```
az group create --name $resource_group --location eastus
```

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 namespace

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

Ele deve ter entre 3 e 50 caracteres.
Ele deve ser exclusivo da região.
Os únicos caracteres permitidos são a-z, A-Z, 0-9 e -
Não deve começar com prefixos de palavra-chave reservados, como Microsoft, System ou 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> por um valor de sua preferência.
```
namespace="<your-namespace-name>"
```

Criar um namespace. O ideal é alterar o local em que ele é implantado.

az eventgrid namespace create -g $resource_group -n $namespace -l eastus

Criar um tópico de namespace

Crie um tópico que seja usado para conter 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> por um valor de sua preferência.
```
topic="<your-topic-name>"
```

Crie o tópico de namespace:

az eventgrid namespace topic create -g $resource_group -n $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 Grade de Eventos mais recente do painel de controle.

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> por um valor de sua preferência.
```
event_subscription="<your-event-subscription-name>"
```

Criar uma assinatura de evento para o tópico do namespace:

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

Enviar eventos para o tópico

Agora, envie um evento de exemplo para o tópico do namespace seguindo as etapas nesta seção.

Listar as chaves de acesso de namespace

Obtenha as chaves de acesso associadas ao namespace que você criou. Você usará uma delas para autenticação ao publicar eventos. Para listar suas chaves, você precisa primeiro da ID completa do recurso do namespace. Obtenha-o executando o comando a seguir:
```
namespace_resource_id=$(az eventgrid namespace show -g $resource_group -n $namespace --query "id" --output tsv)
```

Obtenha a primeira chave do namespace:

key=$(az eventgrid namespace list-key -g $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 serão enviados. As operações a seguir foram disponibilizadas pela primeira vez com a versão 2023-06-01-preview da 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 é o conteúdo do evento. Qualquer JSON bem formado pode ficar nesse campo. Para obter mais informações em propriedades (também conhecidas como atributos de contexto) que podem ser usadas em um evento, consulte as especificações CloudEvents.

Use o CURL para enviar o evento para o tópico. 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 esse ponto de extremidade executando o seguinte comando:

receive_operation_uri="https://"$(az eventgrid namespace show -g $resource_group -n $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

Confirmar um evento

Depois de receber um evento, você transmite esse evento para seu aplicativo para processamento. Depois de processar o evento com sucesso, você não precisará mais desse evento na 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 etapa anterior, você deveria ter recebido 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>"
```
Agora, compile o conteúdo da operação de confirmação, que especifica o token de bloqueio 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 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 a do exemplo a seguir:

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

Próximas etapas

Para saber mais sobre o modelo de entrega por pull, consulte Visão geral da entrega por pull.

Compartilhar via