Como trabalhar com gatilhos e associações de Grade de Eventos no Azure Functions

Artigo
03/10/2024

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 ligações da Grade de Eventos. Para obter mais informações sobre o gatilho de Grade de Eventos e definições e exemplos de vinculação de saída, consulte um dos seguintes artigos de referência:

Subscrições de eventos

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 eventos especificam a URL do ponto de extremidade que invoca a função. Quando cria uma subscrição de evento a partir do separador Integração da sua função no portal do Azure, o URL é fornecido para si. Ao criar programaticamente uma assinatura de evento ou ao criar a assinatura de evento a partir 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ê deve obter das APIs REST do administrador do Functions.

URL do ponto de extremidade Webhook

O ponto de extremidade de URL para sua função acionada de Grade de Eventos depende da versão do tempo de execução de Funções. O exemplo seguinte mostra o padrão do URL específico da versão:

v2.x+
v1.x

https://{functionappname}.azurewebsites.net/runtime/webhooks/eventgrid?functionName={functionname}&code={systemkey}

https://{functionappname}.azurewebsites.net/admin/extensions/EventGridExtensionConfig?functionName={functionname}&code={systemkey}

Nota

Há uma versão do gatilho de armazenamento de Blob que também usa assinaturas de eventos. A URL do ponto de extremidade para esse tipo de gatilho de armazenamento de Blob tem um caminho de , enquanto o caminho para um gatilho de Grade de /runtime/webhooks/blobsEventos 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 tem de ser incluída no URL do ponto final de um acionador do Event Grid. 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):

v2.x+
v1.x

http://{functionappname}.azurewebsites.net/admin/host/systemkeys/eventgrid_extension?code={masterkey}

http://{functionappname}.azurewebsites.net/admin/host/systemkeys/eventgridextensionconfig_extension?code={masterkey}

Essa API REST é uma API de administrador, portanto, requer sua chave mestra de aplicativo de função. Não confunda a chave do sistema (para invocar uma função de gatilho da Grade de Eventos) com a chave mestra (para executar tarefas administrativas no aplicativo de função). Quando subscrever um tópico da Grelha de Eventos, certifique-se de que utiliza 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 ao seu aplicativo de função. Não compartilhe essa chave com terceiros nem a distribua em aplicativos cliente nativos.

Para obter mais informações, consulte Chaves de autorização no artigo de referência do gatilho HTTP.

Criar uma subscrição de evento

Você pode criar uma assinatura de evento no portal do Azure ou usando a CLI do Azure.

Portal
CLI do Azure

Para funções que você desenvolve no portal do Azure com o gatilho de Grade de Eventos, selecione Integração, escolha o Gatilho de Grade de Eventos e selecione Criar assinatura de Grade de Eventos.

Screenshot of connecting to a new event subscription to trigger in the portal.

Quando você seleciona esse link, o portal abre a página Criar Assinatura de Evento com o ponto de extremidade de gatilho atual já definido.

Screenshot of creating an event subscription with the function endpoint already defined.

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 criar uma assinatura usando a CLI do Azure, use o az eventgrid event-subscription create comando. Os exemplos usam a versão v2.x+ da URL e são gravados para serem executados no Azure Cloud Shell. Você precisará modificar os exemplos para executar a partir de um prompt de comando do Windows.

Este exemplo cria uma assinatura para uma conta de armazenamento de blob, com um espaço reservado para a chave do sistema:

az eventgrid resource event-subscription create -g myResourceGroup \
    --provider-namespace Microsoft.Storage --resource-type storageAccounts \
    --resource-name myblobstorage12345 --name myFuncSub \
    --included-event-types Microsoft.Storage.BlobCreated \
    --subject-begins-with /blobServices/default/containers/images/blobs/ \
    --endpoint https://mystoragetriggeredfunction.azurewebsites.net/runtime/webhooks/eventgrid?functionName=imageresizefunc&code=<key>

Para obter mais informações sobre como criar uma assinatura, consulte o início rápido do armazenamento de blob ou os outros inícios rápidos da Grade de Eventos.

Teste local com o aplicativo Web visualizador

Para testar um gatilho de Grade de Eventos localmente, você precisa obter solicitações HTTP de Grade de Eventos entregues de sua origem na nuvem para sua máquina local. Uma maneira de fazer isso é capturando solicitações on-line e reenviando-as manualmente em sua máquina local:

Crie um aplicativo Web visualizador que capture mensagens de eventos.
Crie uma assinatura de Grade de Eventos que envie eventos para o aplicativo visualizador.
Gere uma solicitação e copie o corpo da solicitação do aplicativo visualizador.
Publique manualmente a solicitação na URL do host local da sua função de gatilho de Grade de Eventos.

Quando terminar o teste, você poderá usar a mesma assinatura para produção atualizando o ponto de extremidade. Use o az eventgrid event-subscription update comando Azure CLI.

Você também pode usar o utilitário ngrok para encaminhar solicitações remotas para suas funções em execução local. Para obter mais informações, consulte este tutorial.

Criar um aplicativo Web visualizador

Para simplificar a captura de mensagens de eventos, você pode implantar um aplicativo Web pré-criado que exibe as mensagens de evento. A solução implementada inclui um plano do Serviço de Aplicações, uma aplicação Web do Serviço de Aplicações e o código de origem do GitHub.

Selecione Implementar no Azure para implementar a solução para a sua subscrição. No portal do Azure, indique os valores para os parâmetros.

A implementação pode demorar alguns minutos. Após a implementação ter sido concluída com êxito, verifique a aplicação Web para verificar se está em execução. Num browser, navegue para: https://<your-site-name>.azurewebsites.net

Vê o site, mas ainda não foram publicados eventos no mesmo.

View new site

Criar uma subscrição do Event Grid

Crie uma assinatura de Grade de Eventos do tipo que você deseja testar e forneça a URL do seu aplicativo Web como o ponto de extremidade para notificação de eventos. O ponto final para a aplicação Web tem de incluir o sufixo /api/updates/. Assim, o URL completo é https://<your-site-name>.azurewebsites.net/api/updates

Para obter 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.

Gerar um pedido

Acione um evento que gerará tráfego HTTP para o ponto de extremidade do seu aplicativo Web. Por exemplo, se você criou uma assinatura de armazenamento de blob, carregue ou exclua um blob. Quando uma solicitação aparecer em seu aplicativo Web, copie o corpo da solicitação.

O pedido de validação da subscrição será recebido primeiro; Ignore todas as solicitações de validação e copie a solicitação de evento.

Copy request body from web app

Postar manualmente a solicitação

Execute a função Grade de Eventos localmente. Os Content-Type cabeçalhos e aeg-event-type devem ser definidos manualmente, enquanto todos os outros valores podem ser deixados como padrão.

Use uma ferramenta como Postman ou curl para criar uma solicitação HTTP POST:

Defina um Content-Type: application/json cabeçalho.
Defina um aeg-event-type: Notification cabeçalho.
Cole os dados RequestBin no corpo da solicitação.

Poste no URL da sua função de gatilho de grade de eventos.

v2.x+
v1.x

http://localhost:7071/runtime/webhooks/eventgrid?functionName={FUNCTION_NAME}

http://localhost:7071/admin/extensions/EventGridExtensionConfig?functionName={FUNCTION_NAME}

O functionName parâmetro deve ser o nome especificado no FunctionName atributo.

As capturas de tela a seguir mostram os cabeçalhos e o corpo da solicitação no Postman:

Headers in Postman

Request body in Postman

A função de gatilho Grade de Eventos executa e mostra logs semelhantes ao exemplo a seguir:

Sample Event Grid trigger function logs

Próximos passos

Para saber mais sobre a Grade de Eventos com Funções, consulte os seguintes artigos: