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

Criar uma assinatura 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.

Obter a 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}

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

Obter a chave do sistema

O ponto de extremidade da 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 na URL do ponto de extremidade de um gatilho da Grade de Eventos. A seção a seguir explica como obter a chave do sistema.

Você também pode obter a chave mestra para seu aplicativo de funções de Funções>Chaves do aplicativo no portal.

Para obter mais informações, consulte Trabalhar com chaves de acesso no Azure Functions.

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

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

Criar a assinatura

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

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 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:

1. Criar um aplicativo Web visualizador que captura as mensagens de evento.
2. Criar uma assinatura da Grade de Eventos que envia eventos para o aplicativo visualizador.
3. Gerar uma solicitação e copiar o corpo da solicitação do aplicativo visualizador.
4. Postar manualmente a solicitação para a URL localhost da sua função de gatilho da 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 mantém seus dados seguros. Para obter mais informações, confira Ferramentas de teste para HTTP.

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.

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

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

  • v2.x+
  • v1. x

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

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

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:

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