Entregar eventos aos Hubs de Eventos do Azure usando tópicos de namespace - CLI do Azure (visualização)

Artigo
02/23/2024

O artigo fornece instruções passo a passo para publicar eventos na Grade de Eventos do Azure no formato JSON CloudEvents e entregar esses eventos usando o modelo de entrega por push. Para ser específico, use a CLI e a Curl do Azure para publicar eventos em um tópico de namespace na Grade de Eventos e enviar esses eventos de uma assinatura de evento para um destino de manipulador de Hubs de Eventos. Para obter mais informações sobre o modelo de entrega por push, consulte Visão geral da entrega por push.

Nota

Namespaces, tópicos de namespace e assinaturas de eventos associados a tópicos de namespace estão inicialmente disponíveis nas seguintes regiões: Leste dos EUA, Centro dos EUA, Centro-Sul dos EUA, Oeste dos EUA 2, Leste Asiático, Sudeste Asiático, Norte da Europa, Europa Ocidental, Norte dos Emirados Árabes Unidos.
A extensão de Grade de Eventos da CLI do Azure ainda não oferece suporte a namespaces e a nenhum dos recursos que ela contém. Usaremos o recurso da CLI do Azure para criar recursos da Grade de Eventos.
Atualmente, os namespaces da Grade de Eventos do Azure dão suporte à autenticação de token e chaves de acesso SAS (Assinaturas de Acesso Compartilhado).

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 você estiver usando uma instalação local, entre na CLI do Azure usando o az login comando. 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.

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

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 $location
```

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 um novo recurso de Hubs de Eventos

Crie um recurso de Hubs de Eventos que seja usado como destino do manipulador para o tópico de namespace assinatura de entrega por push.

Declare uma variável para manter o nome do namespace Hubs de Eventos.
```
eventHubsNamespace="<your-event-hubs-namespace-name>"
```

Criar o espaço de nomes dos Hubs de Eventos.

az eventhubs namespace create --resource-group $resource_group --name $eventHubsNamespace --location $location

Declare uma variável para manter o nome do hub de eventos.
```
eventHubsEventHub="<your-event-hub-name>"
```

Execute o seguinte comando para criar um hub de eventos no namespace.

az eventhubs eventhub create --resource-group $resource_group --namespace-name $eventHubsNamespace --name $eventHubsEventHub

Entregar eventos a Hubs de Eventos usando identidade gerenciada

Para entregar eventos a hubs de eventos em seu namespace de Hubs de Eventos usando identidade gerenciada, siga estas etapas:

Habilite a identidade gerenciada atribuída pelo sistema ou pelo usuário: namespaces. Continue lendo a próxima seção para descobrir como habilitar a identidade gerenciada usando a CLI do Azure.
Adicione a identidade à função Remetente de Dados dos Hubs de Eventos do Azure no namespace Hubs de Eventos, continue lendo a próxima seção para descobrir como adicionar a atribuição de função.
Habilite a configuração Permitir que serviços confiáveis da Microsoft ignorem esse firewall em seu namespace de Hubs de Eventos.
Configure a assinatura de eventos que usa um hub de eventos como ponto de extremidade para usar a identidade gerenciada atribuída pelo sistema ou pelo usuário.

Nota

A entrega de eventos aos Hubs de Eventos do Azure está atualmente em pré-visualização.

Habilitar identidade gerenciada no namespace Grade de Eventos

Habilite a identidade gerenciada atribuída ao sistema no namespace Grade de Eventos.

az eventgrid namespace update --resource-group $resource_group --name $namespace --identity {type:systemassigned}

Adicionar atribuição de função em Hubs de Eventos para a identidade gerenciada da Grade de Eventos

Obtenha o ID principal da identidade gerenciada do sistema de namespace da Grade de Eventos.

principalId=$(az eventgrid namespace show --resource-group $resource_group --name $namespace --query identity.principalId -o tsv)

Obtenha a ID do recurso do hub de eventos dos Hubs de Eventos.

eventHubResourceId=$(az eventhubs eventhub show --resource-group $resource_group --namespace-name $eventHubsNamespace --name $eventHubsEventHub --query id -o tsv)

Adicione atribuição de função em Hubs de Eventos para a identidade gerenciada do sistema de Grade de Eventos.

az role assignment create --role "Azure Event Hubs Data Sender" --assignee $principalId --scope $eventHubResourceId

Criar uma subscrição de evento

Crie uma nova assinatura de evento de entrega por push.

event_subscription="<your_event_subscription_name>"

az resource create --api-version 2023-06-01-preview --resource-group $resource_group --namespace Microsoft.EventGrid --resource-type eventsubscriptions --name $event_subscription --parent namespaces/$namespace/topics/$topic --location $location --properties "{\"deliveryConfiguration\":{\"deliveryMode\":\"Push\",\"push\":{\"maxDeliveryCount\":10,\"deliveryWithResourceIdentity\":{\"identity\":{\"type\":\"SystemAssigned\"},\"destination\":{\"endpointType\":\"EventHub\",\"properties\":{\"resourceId\":\"$eventHubResourceId\"}}}}}}"

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
```
Navegue até a página Namespace de Hubs de Eventos no portal do Azure, atualize a página e verifique se o contador de mensagens de entrada no gráfico indica que um evento foi recebido.

Próximos passos

Neste artigo, você criou e configurou o namespace Grade de Eventos e os recursos dos Hubs de Eventos. Para obter instruções passo a passo para receber eventos de um hub de eventos, consulte estes tutoriais: