Compartilhar via

Entregar eventos para webhooks usando tópicos de namespace — CLI do Azure (versão prévia)

  • Artigo

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

Observação

A extensão Grade de Eventos do Azure CLI ainda não tem suporte para namespaces e nenhum dos recursos que ela contém. Usaremos o recurso da CLI do Azure para criar recursos da Grade de Eventos.

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 obter mais informações, 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.

Habilitar o provedor de recursos da Grade de Eventos

  1. 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

  2. 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 grupos 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.

  1. 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>"

    location="<your-resource-group-location>"

  2. Crie um grupos de recursos. Altere o local conforme desejar.

    az group create --name $resource_group --location $location

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 -
  • Ele não deve começar com prefixos de palavra-chave reservados, como Microsoft, System ou EventGrid.

  1. 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>"

  2. Criar um namespace. O ideal é alterar o local em que 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 conter todos os eventos publicados no ponto de extremidade do namespace.

  1. 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>"

  2. Crie o tópico de namespace:

    az eventgrid namespace topic create -g $resource_group -n $topic --namespace-name $namespace

Criar um ponto de extremidade de mensagem

Antes de fazer a assinatura do tópico do namespace, vamos criar o ponto de extremidade para a mensagem do evento. Normalmente, o ponto de extremidade executa ações com base nos dados de evento. Para simplificar esse início rápido, implante um aplicativo web predefinido que exiba as mensagens do evento. A solução implantada inclui um plano do Serviço de Aplicativo, um aplicativo Web do Aplicativo do Serviço de e o código-fonte do GitHub.

  1. Copie o comando a seguir, especifique um nome para o aplicativo Web (visualizador da Grade de Eventos de exemplo) e pressione ENTER para executar o comando. Substitua <your-site-name> por um nome exclusivo para o aplicativo Web. O nome do aplicativo Web deve ser exclusivo, pois é parte de uma entrada DNS.

    sitename="<your-site-name>"

  2. Execute o az deployment group create para implantar seu aplicativo Web usando um modelo do Azure Resource Manager.

    az deployment group create \
  --resource-group $resource_group \
  --template-uri "https://raw.githubusercontent.com/Azure-Samples/azure-event-grid-viewer/master/azuredeploy.json" \
  --parameters siteName=$sitename hostingPlanName=viewerhost

A implantação pode levar alguns minutos para ser concluída. Depois que a implantação for bem-sucedida, exiba seu aplicativo Web para garantir que ele esteja em execução. Em um navegador da web, navegue até: https://<your-site-name>.azurewebsites.net Você deve ver o site sem mensagens exibidas no momento.

Entregar eventos para o webhook do Visualizador da Grade de Eventos do Azure

Crie uma assinatura de evento de entrega por push para o namespace usando o webhook para o Visualizador da Grade de Eventos do Azure.

  1. Defina uma variável para abrigar o nome da assinatura do evento.

    event_subscription="<your_event_subscription_name>"

  2. Substitua EVENTGRIDWEBSITENAME pelo nome do site do Visualizador da Grade de Eventos. Por exemplo: contosoegridviewer.

    az resource create --api-version 2024-06-01-preview --resource-group $resource_group --namespace Microsoft.EventGrid --resource-type eventsubscriptions --name $event_subscription --parent namespaces/$namespace/topics/$topic --location $location --properties "{\"eventDeliverySchema\": \"CloudEventSchemaV1_0\",\"deliveryConfiguration\":{\"deliveryMode\":\"Push\",\"push\":{\"destination\":{\"endpointType\":\"WebHook\",\"properties\":{\"endpointUrl\":\"https:\/\/$sitename.azurewebsites.net\/api/updates\"}}}}}"

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

  1. 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)

  2. 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

  1. 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

  2. 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.

  3. 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

Verifique se o Visualizador da Grade de Eventos do Azure recebeu o evento

Verifique se o aplicativo web do Visualizador da Grade de Eventos do Azure mostra os eventos recebidos da Grade de Eventos.

Captura de tela mostrando o Visualizador da Grade de Eventos do Azure com uma amostra de evento recebido.

Conteúdo relacionado

Neste início rápido, você usou um webhook como manipulador de eventos. Para obter um início rápido que usa um hub de eventos do Azure como um manipulador de eventos, confira Distribuir eventos para Hubs de Eventos do Azure usando tópicos de namespace.