Como trabalhar com gatilhos e associações da Grade de Eventos no Azure Functions
O Azure Functions fornece integração interna com a Grade de Eventos do Azure usando gatilhos e associações. Este artigo mostra como configurar e avaliar localmente o gatilho e as associações da Grade de Eventos. Para obter mais informações sobre definições e exemplos de associação de saída e gatilho da Grade de Eventos, consulte um dos seguintes artigos de referência:
- Visão geral das associações de Grade de Eventos do Azure
- Gatilho da Grade de Eventos do Azure para o Azure Functions
- Associação de saída da Grade de Eventos do Azure para Azure Functions
Assinaturas de evento
Para começar a receber solicitações HTTP da Grade de Eventos, você precisa de uma assinatura para eventos gerados pela Grade de Eventos. As assinaturas de evento especificam a URL do ponto de extremidade que invoca a função. Quando você cria uma assinatura de evento na guia Integração da função no portal do Azure, a URL é fornecida. Ao criar uma assinatura de evento programaticamente ou ao criar a assinatura de evento da Grade de Eventos, você precisará fornecer o ponto de extremidade. A URL do ponto de extremidade contém uma chave do sistema, que você precisa obter das APIs REST do administrador do Functions.
URL do ponto de extremidade do webhook
O ponto de extremidade de URL da função disparada pela Grade de Eventos depende da versão do runtime do Functions. O exemplo a seguir mostra o padrão de URL específico da versão:
https://{functionappname}.azurewebsites.net/runtime/webhooks/eventgrid?functionName={functionname}&code={systemkey}
Observação
Há uma versão do gatilho de Armazenamento de Blobs que também usa assinaturas de evento. A URL do ponto de extremidade para esse tipo de gatilho de Armazenamento de Blobs tem um caminho de /runtime/webhooks/blobs, enquanto o caminho para um gatilho da Grade de Eventos seria /runtime/webhooks/EventGrid. Para obter uma comparação das opções de processamento de blobs, consulte Gatilho em um contêiner de blob.
Chave do sistema
O ponto de extremidade de URL que você constrói inclui o valor da chave do sistema. A chave do sistema é uma chave de autorização que deve ser incluída na URL do ponto de extremidade para um gatilho de Grade de Eventos. A seção a seguir explica como obter a chave do sistema.
Você pode obter a chave do sistema usando a seguinte API (HTTP GET):
http://{functionappname}.azurewebsites.net/admin/host/systemkeys/eventgrid_extension?code={masterkey}
Essa API REST é uma API de administrador e, por isso, requer sua chave mestre do aplicativo. Não confunda a chave do sistema (para invocar uma função de gatilho de grade de eventos) com a chave mestra (para executar tarefas administrativas no aplicativo de funções). Ao assinar em um tópico da Grade de Eventos, certifique-se de usar a chave do sistema.
Aqui, está um exemplo da resposta que fornece a chave do sistema:
{
"name": "eventgridextensionconfig_extension",
"value": "{the system key for the function}",
"links": [
{
"rel": "self",
"href": "{the URL for the function, without the system key}"
}
]
}
Você pode obter a chave mestra para seu aplicativo de função na guia Configurações do aplicativo de função no portal.
Importante
A chave mestra fornece acesso de administrador para seu aplicativo de funções. Não compartilhe essa chave com terceiros ou distribua-a em aplicativos clientes nativos.
Para obter mais informações, consulte Chaves de autorização no artigo de referência de gatilho HTTP.
Criar uma assinatura de evento
Você pode criar uma assinatura de evento no portal do Azure ou usando a CLI do Azure.
Para as funções que você desenvolve no portal do Azure com o gatilho de Grade de Eventos, selecione Integração, escolha Gatilho da Grade de Eventos e selecione Criar assinatura de Grade de Eventos.
Ao selecionar esse link, o portal abrirá a página Criar Assinatura de Evento com o ponto de extremidade de gatilho atual já definido.
Para obter mais informações sobre como criar assinaturas usando o Portal do Azure, consulte Criar evento personalizado - Portal do Azure na documentação da Grade de Eventos.
Para obter mais informações sobre como criar uma assinatura, consulte o Guia de início rápido do armazenamento de blobs ou outros guias de início rápido da Grade de Eventos.
Teste local com o aplicativo Web visualizador
Para testar um gatilho de Grade de Eventos localmente, você deve receber solicitações HTTP de Grade de Eventos entre suas origens na nuvem para sua máquina local. Uma maneira de fazer isso é capturar solicitações online e manualmente reenviá-las em sua máquina local:
- Criar um aplicativo Web visualizador que captura as mensagens de evento.
- Criar uma assinatura da Grade de Eventos que envia eventos para o aplicativo visualizador.
- Gerar uma solicitação e copiar o corpo da solicitação do aplicativo visualizador.
- Postar manualmente a solicitação para a URL localhost da sua função de gatilho da Grade de Eventos.
Quando terminar de testar, você poderá usar a mesma assinatura para a produção atualizando o ponto de extremidade. Use o comando az eventgrid event-subscription update da CLI do Azure.
Você também pode usar o utilitário ngrok para encaminhar solicitações remotas às funções em execução local. Para obter mais informações, confira este tutorial.
Criar um aplicativo Web visualizador
Para simplificar as mensagens de evento de captura, implante um aplicativo Web predefinido que exibe as mensagens de 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.
Selecione Implantar no Azure para implantar a solução na sua assinatura. No portal do Azure, forneça os valores para os parâmetros.
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ê verá o site, mas nenhum evento ainda estará publicado.
Criar uma assinatura na Grade de Eventos
Crie uma assinatura da Grade de Eventos do tipo que você deseja testar e forneça a ela a URL do aplicativo Web como o ponto de extremidade para a notificação de eventos. O ponto de extremidade para seu aplicativo Web deve incluir o sufixo /api/updates/. Portanto, a URL completa é https://<your-site-name>.azurewebsites.net/api/updates
Para obter mais informações sobre como criar assinaturas usando o portal do Azure, confira Criar um evento personalizado – portal do Azure na documentação da Grade de Eventos.
Gerar uma solicitação
Dispare um evento que gerará tráfego HTTP para o ponto de extremidade do aplicativo Web. Por exemplo, se você criou uma assinatura de armazenamento de Blobs, faça upload ou exclua um blob. Quando uma solicitação for exibida no aplicativo Web, copie o corpo da solicitação.
A solicitação de validação de assinatura será recebida primeiro. Ignore quaisquer solicitações de validação e copie a solicitação de evento.
Postar manualmente a solicitação
Execute sua função de Grade de Eventos localmente. É necessário configurar os cabeçalhos Content-Type e aeg-event-type manualmente, enquanto todos os outros valores podem ser deixados conforme o padrão.
Use uma ferramenta como Postman ou curl para criar uma solicitação HTTP POST:
Defina um cabeçalho
Content-Type: application/json.Defina um cabeçalho
aeg-event-type: Notification.Cole os dados RequestBin no corpo da solicitação.
Poste na URL da sua função de gatilho de Grade de Eventos.
O parâmetro functionName deverá ser o nome especificado no atributo FunctionName.
As capturas de tela a seguir mostram os cabeçalhos e o corpo da solicitação em Postman:
A função de gatilho da Grade de Eventos executa e mostra logs semelhantes ao exemplo a seguir:
Próximas etapas
Para saber mais sobre a Grade de Eventos, consulte os artigos a seguir: