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

Artigo
02/20/2024

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

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

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> por um valor desejado.
```
resource_group="<your-resource-group-name>"
```
Crie um grupo de recursos. Altere a localização como achar melhor.
```
az group create --name $resource_group --location eastus
```

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 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, System ou EventGrid.

Declare uma variável para manter o nome do namespace da Grade de Eventos. Especifique um nome para o namespace substituindo <your-namespace-name> por um valor desejado.
```
namespace="<your-namespace-name>"
```
Crie um namespace. Talvez você queira alterar o local onde 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 manter 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 desejado.
```
topic="<your-topic-name>"
```

Crie seu tópico de namespace:

az eventgrid namespace topic create -g $resource_group -n $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 a API REST mais recente do plano de controle de grade de eventos.

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

Crie uma assinatura de evento para o tópico 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 seu tópico

Agora, 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ê usa um deles para autenticar ao publicar eventos. Para listar suas chaves, você precisa primeiro do ID de recurso de namespace completo. Obtenha-o executando o seguinte comando:
```
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. 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 data elemento é a carga útil do seu evento. Qualquer JSON bem formado pode ir para este campo. Para obter mais informações sobre propriedades (também conhecidas como atributos de contexto) que podem ir em um evento, consulte as especificações do 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 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

Reconhecer um evento

Depois de receber um evento, você passa esse evento para o seu aplicativo para processamento. Depois de processar o evento com sucesso, você não precisa mais que ele esteja na assinatura do evento. Para instruir a Grade de Eventos a excluir o evento, você o reconhece usando seu token de bloqueio que você obteve na resposta da operação de recebimento.

Na etapa anterior, você deve ter recebido uma resposta que inclui um brokerProperties objeto com uma lockToken propriedade. Copie o valor do token de bloqueio e defina-o em uma variável de ambiente:
```
lockToken="<paste-the-lock-token-here>"
```
Agora, 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 cadeia de caracteres com o URI da operação de reconhecimento:

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óximos passos

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