Enviar eventos do Gerenciamento de API para a Grade de Eventos

APLICA-SE A: Consumo | Desenvolvedor | Básico | Padrão | Premium

O Gerenciamento de API integra-se com a Grade de Eventos do Azure para que você possa enviar notificações de eventos para outros serviços e disparar processos de downstream. O Event Grid é um serviço de roteamento de eventos totalmente gerenciado que usa um modelo de publicação-assinatura. O Event Grid tem suporte interno para serviços do Azure, como Azure Functions e Aplicativos Lógicos do Azure, e pode entregar alertas de eventos a serviços que não sejam do Azure usando webhooks.

Você pode assinar os seguintes tipos de eventos de Gerenciamento de API:

• Eventos do plano de controle: esses eventos são gerados quando você cria, atualiza ou exclui determinados recursos de Gerenciamento de API. Por exemplo, você pode receber um evento quando um novo usuário ou novo produto é criado em sua instância de Gerenciamento de API.
• Eventos do plano de dados (versão prévia): esses eventos são gerados durante a operação do gateway de Gerenciamento de API. Atualmente, o Gerenciamento de API pode gerar eventos para os disjuntores de back-end e para o ciclo de vida dos tokens de acesso do gateway auto-hospedado.

Para obter uma lista completa de eventos disponíveis, consulte o esquema da Grade de Eventos para Gerenciamento de API.

Por exemplo, usando a integração com a Grade de Eventos, você pode criar um aplicativo que atualiza um banco de dados, criar uma conta de cobrança e enviar uma notificação por email sempre que um usuário for adicionado à sua instância de Gerenciamento de API.

Neste artigo, você se inscreve em eventos do Event Grid na sua instância do Gerenciamento de API, dispara os eventos e os envia para um endpoint que processa os dados. Para simplificar, você envia eventos para um exemplo de aplicativo Web que coleta e exibe as mensagens:

Pré-requisitos

• Use 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. 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 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 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.

• Se você ainda não tem uma instância do serviço de Gerenciamento de API, conclua o seguinte guia de início rápido: Criar uma instância de Gerenciamento de API do Azure
• Habilite uma identidade gerenciada atribuída pelo sistema na instância do Gerenciamento de API.
• Crie um grupo de recursos se você ainda não tiver um onde implantar o endpoint de exemplo.

Criar um endpoint de evento

Nesta seção, você usa um modelo do Resource Manager para implantar um exemplo de aplicativo Web pré-criado no Serviço de Aplicativo do Azure. Posteriormente, você assina os eventos da Grade de Eventos do Gerenciamento de API e especifica esse aplicativo como o ponto de extremidade para o qual os eventos são enviados.

Para implantar o exemplo de aplicativo, você pode usar a CLI do Azure, o Azure PowerShell ou o portal do Azure. O exemplo a seguir usa o comando az deployment group create na CLI do Azure.

• Defina RESOURCE_GROUP_NAME como o nome de um grupo de recursos existente

• Defina SITE_NAME como um nome exclusivo para o seu aplicativo Web

  O nome do site deve ser exclusivo no Azure porque faz parte do FQDN (nome de domínio totalmente qualificado) do aplicativo Web. Em uma seção posterior, você navega para o FQDN do aplicativo em um navegador da Web para exibir os eventos.

RESOURCE_GROUP_NAME=<your-resource-group-name>
SITE_NAME=<your-site-name>

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

Depois que a implantação for realizada com êxito (isso pode demorar alguns minutos), abra um navegador e navegue até o aplicativo da Web para verificar se está em execução:

https://<your-site-name>.azurewebsites.net

Você deve ver o aplicativo de exemplo renderizado sem nenhuma mensagem de evento exibida.

Registrar o provedor de recursos do Event Grid

A menos que você tenha usado a Grade de Eventos antes, será necessário registrar o provedor de recursos da Grade de Eventos. Se você usou a Grade de Eventos antes, vá para a próxima seção.

No portal do Azure, siga estas etapas:

1. No menu à esquerda, selecione Assinaturas.

2. Selecione a assinatura que você deseja usar para a Grade de Eventos na lista de assinaturas.

3. Na página Assinatura , em Configurações no menu à esquerda, selecione Provedores de recursos.

4. Pesquise por Microsoft.EventGrid e confirme que o Status é Não registrado.

5. Selecione Microsoft.EventGrid na lista de provedores.

6. Na barra de comandos, selecione Registrar.

   

7. Atualize para garantir que o status de Microsoft.EventGrid foi alterado para Registrado.

   

Inscrever-se em eventos de Gerenciamento de API

Na Grade de Eventos, você assina um tópico para informar quais eventos quer acompanhar e para onde enviá-los. Aqui, você cria uma assinatura para eventos em sua instância do Gerenciamento de API.

1. No portal do Azure, navegue até a instância do Gerenciamento de API.

2. Selecione Eventos > + Assinatura de Evento.

3. Na guia Básico:

   • Insira um Nome descritivo para a assinatura de evento.
   • Em Tipos de eventos, selecione um ou mais tipos de eventos de Gerenciamento de API para enviar à Grade de Eventos. Para o exemplo neste artigo, selecione pelo menos Microsoft.APIManagement.ProductCreated
   • Em Detalhes do Ponto de Extremidade, selecione o tipo de evento Web Hook, clique em Selecionar um ponto de extremidade e insira a URL do seu aplicativo Web seguida por api/updates. Exemplo: https://myapp.azurewebsites.net/api/updates.
   • Selecione Confirmar seleção.

4. Deixe as configurações nas guias restantes com seus valores padrão e, em seguida, selecione Criar.

   

Acionar e exibir eventos

Agora que o aplicativo de exemplo está em execução e você inscreveu sua instância do Gerenciamento de API no Event Grid, já pode gerar eventos.

Por exemplo, crie um produto em sua instância do Gerenciamento de API. Se a sua assinatura de evento inclui o evento Microsoft.APIManagement.ProductCreated, a criação do produto dispara um evento que é enviado ao endpoint do aplicativo Web.

Navegue até o aplicativo Web do Visualizador da Grade de Eventos, e você verá o evento ProductCreated. Selecione o botão ao lado do evento para mostrar os detalhes.

Esquema de evento do Event Grid

Os dados de evento do Gerenciamento de API incluem o resourceUri, que identifica o recurso de Gerenciamento de API que disparou o evento. Para obter detalhes sobre o esquema de mensagem de evento do Gerenciamento de API, confira a documentação da Grade de Eventos:

Esquema de eventos da Grade de Eventos do Azure para o Gerenciamento de API

Conteúdo relacionado

• Saiba mais sobre como se inscrever em eventos.