Como trabalhar com gatilhos e associações de 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 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:

• Visão geral das ligações da Grade de Eventos do Azure
• Gatilho de Grade de Eventos do Azure para o Azure Functions
• Vinculação de saída da Grade de Eventos do Azure para o Azure Functions

Criar uma subscrição 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 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.

Obter o URL do ponto de extremidade do 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+

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

v1.x

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.

Obter a chave do sistema

O ponto de extremidade de URL que você constrói inclui um valor de chave do sistema. A chave do sistema é uma chave de autorização, específica para o webhook da Grade de Eventos, que deve ser incluída em uma solicitação para a URL do ponto de extremidade para um gatilho de Grade de Eventos. A seção a seguir explica como obter a chave do sistema.

Também pode obter a chave mestra para a sua aplicação de funções a partir das teclas da aplicação Funções>no portal.

Atenção

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 Trabalhar com chaves de acesso no Azure Functions.

Você pode obter a chave do sistema do seu aplicativo de função usando as seguintes APIs de administrador (HTTP GET):

v2.x+

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

v1.x

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}"
    }
  ]
}

Criar a subscrição

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

Portal

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.

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.

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.

CLI do Azure

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:

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

Para enviar uma solicitação de postagem HTTP, você precisa de uma ferramenta de teste HTTP. Certifique-se de escolher uma ferramenta que mantenha seus dados seguros. Para obter mais informações, consulte Ferramentas de teste HTTP.

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.

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.

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.

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 sua ferramenta de teste HTTP 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.

• Envie uma solicitação HTTP POST para o ponto de extremidade que inicia manualmente o gatilho da Grade de Eventos.

  v2.x+

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

  v1.x

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

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

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

Próximos passos

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

• Associações da Grade de Eventos do Azure para o Azure Functions
• Tutorial: Automatizar o redimensionamento de imagens carregadas usando a Grade de Eventos