Gatilho de Grade de Eventos para o Azure FunctionsEvent Grid trigger for Azure Functions

Este artigo explica como manipular com eventos de Grade de Eventos no Azure Functions.This article explains how to handle Event Grid events in Azure Functions.

A Grade de Eventos é um serviço do Azure que envia solicitações HTTP para notificá-lo sobre eventos que acontecem nos publicadores.Event Grid is an Azure service that sends HTTP requests to notify you about events that happen in publishers. Um publicador é o serviço ou recurso que origina o evento.A publisher is the service or resource that originates the event. Por exemplo, uma conta de armazenamento de Blobs do Azure é um publicador, e uma exclusão ou upload de blob é um evento.For example, an Azure blob storage account is a publisher, and a blob upload or deletion is an event. Alguns serviços do Azure têm suporte interno para publicar eventos na Grade de Eventos.Some Azure services have built-in support for publishing events to Event Grid.

Os manipuladores de eventos recebem e processam eventos.Event handlers receive and process events. O Azure Functions é um dos vários serviços doAzure que possuem suporte interno para manipular eventos da Grande de Eventos.Azure Functions is one of several Azure services that have built-in support for handling Event Grid events. Neste artigo, você aprende a usar um gatilho de Grade de Eventos para invocar uma função quando um evento é recebido da Grade de Eventos.In this article, you learn how to use an Event Grid trigger to invoke a function when an event is received from Event Grid.

Se você preferir, é possível utilizar um gatilho HTTP para manipular eventos da Grade de Eventos, consultado Usar um gatilho HTTP como um gatilho de Grade de Eventos, posteriormente neste artigo.If you prefer, you can use an HTTP trigger to handle Event Grid Events; see Use an HTTP trigger as an Event Grid trigger later in this article. No momento, não é possível usar um gatilho da Grade de Eventos para um aplicativo do Azure Functions quando o evento é entregue no esquema CloudEvents.Currently, you can't use an Event Grid trigger for an Azure Functions app when the event is delivered in the CloudEvents schema. Em vez disso, use um gatilho HTTP.Instead, use an HTTP trigger.

Essas são as informações de referência para desenvolvedores do Azure Functions.This is reference information for Azure Functions developers. Se for novo no Azure Functions, comece com os seguintes recursos:If you're new to Azure Functions, start with the following resources:

Pacotes - Functions 2. xPackages - Functions 2.x

O gatilho de grade de eventos é fornecido no Microsoft.Azure.WebJobs.Extensions.EventGrid pacote NuGet, versão 2. x.The Event Grid trigger is provided in the Microsoft.Azure.WebJobs.Extensions.EventGrid NuGet package, version 2.x. O código-fonte do pacote está no repositório GitHub azure-functions-eventgrid-extension.Source code for the package is in the azure-functions-eventgrid-extension GitHub repository.

A tabela a seguir informa como adicionar suporte para essa associação em cada ambiente de desenvolvimento.The following table tells how to add support for this binding in each development environment.

Ambiente de desenvolvimentoDevelopment environment Para adicionar suporte emTo add support in
Funções 2.xFunctions 2.x
Desenvolvimento local - biblioteca de classes do C#Local development - C# class library Instalar o pacoteInstall the package
Desenvolvimento local - script do C#, JavaScript, F#, Java e PythonLocal development - C# script, JavaScript, F#, Java and Python Registrar a extensãoRegister the extension
Desenvolvimento de portalPortal development Instalar ao adicionar uma associação de saídaInstall when adding output binding

Para saber como atualizar as extensões de associação existentes no portal sem precisar republicar o projeto de aplicativo de funções, consulte Atualizar as extensões.To learn how to update existing binding extensions in the portal without having to republish your function app project, see Update your extensions.

Pacotes - Functions 1. xPackages - Functions 1.x

O gatilho de grade de eventos é fornecido no Microsoft.Azure.WebJobs.Extensions.EventGrid pacote NuGet, versão 1. x.The Event Grid trigger is provided in the Microsoft.Azure.WebJobs.Extensions.EventGrid NuGet package, version 1.x. O código-fonte do pacote está no repositório GitHub azure-functions-eventgrid-extension.Source code for the package is in the azure-functions-eventgrid-extension GitHub repository.

A tabela a seguir informa como adicionar suporte para essa associação em cada ambiente de desenvolvimento.The following table tells how to add support for this binding in each development environment.

Ambiente de desenvolvimentoDevelopment environment Para adicionar suporte emTo add support in
Funções 1.xFunctions 1.x
Desenvolvimento local - biblioteca de classes do C#Local development - C# class library Instalar o pacoteInstall the package
Desenvolvimento local - Script do C#, JavaScript, F#Local development - C# script, JavaScript, F# AutomáticoAutomatic
Desenvolvimento de portalPortal development AutomáticoAutomatic

ExemploExample

Consulte o exemplo específico do idioma para um gatilho de Grade de Eventos:See the language-specific example for an Event Grid trigger:

Para um exemplo de gatilho HTTP, consulte Como usar o gatilho HTTP, posteriormente neste artigo.For an HTTP trigger example, see How to use HTTP trigger later in this article.

C# (2.x)C# (2.x)

O exemplo a seguir mostra um funções 2. x função C# que associa a EventGridEvent:The following example shows a Functions 2.x C# function that binds to EventGridEvent:

using Microsoft.Azure.EventGrid.Models;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;

namespace Company.Function
{
    public static class EventGridTriggerCSharp
    {
        [FunctionName("EventGridTest")]
        public static void EventGridTest([EventGridTrigger]EventGridEvent eventGridEvent, ILogger log)
        {
            log.LogInformation(eventGridEvent.Data.ToString());
        }
    }
}

Para obter mais informações, confira Pacotes, Atributos, Configuração e Uso.For more information, see Packages, Attributes, Configuration, and Usage.

C# (Versão 1.x)C# (Version 1.x)

O exemplo a seguir mostra um funções 1. x função C# que associa a JObject:The following example shows a Functions 1.x C# function that binds to JObject:

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
using Microsoft.Azure.WebJobs.Host;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using Microsoft.Extensions.Logging;

namespace Company.Function
{
    public static class EventGridTriggerCSharp
    {
        [FunctionName("EventGridTriggerCSharp")]
        public static void Run([EventGridTrigger]JObject eventGridEvent, ILogger log)
        {
            log.LogInformation(eventGridEvent.ToString(Formatting.Indented));
        }
    }
}

Exemplo 2 de C# scriptC# script example

O exemplo a seguir mostra uma associação de gatilho em um arquivo function.json e uma função de script de C# que usa a associação.The following example shows a trigger binding in a function.json file and a C# script function that uses the binding.

Aqui estão os dados de associação no arquivo function.json:Here's the binding data in the function.json file:

{
  "bindings": [
    {
      "type": "eventGridTrigger",
      "name": "eventGridEvent",
      "direction": "in"
    }
  ],
  "disabled": false
}

Script C# (Versão 2.x)C# script (Version 2.x)

Aqui está o código de script de 2. x C# funções que associa a EventGridEvent:Here's Functions 2.x C# script code that binds to EventGridEvent:

#r "Microsoft.Azure.EventGrid"
using Microsoft.Azure.EventGrid.Models;
using Microsoft.Extensions.Logging;

public static void Run(EventGridEvent eventGridEvent, ILogger log)
{
    log.LogInformation(eventGridEvent.Data.ToString());
}

Para obter mais informações, confira Pacotes, Atributos, Configuração e Uso.For more information, see Packages, Attributes, Configuration, and Usage.

Script C# (Versão 1.x)C# script (Version 1.x)

Aqui está o código de script de 1. x C# funções que associa a JObject:Here's Functions 1.x C# script code that binds to JObject:

#r "Newtonsoft.Json"

using Newtonsoft.Json;
using Newtonsoft.Json.Linq;

public static void Run(JObject eventGridEvent, TraceWriter log)
{
    log.Info(eventGridEvent.ToString(Formatting.Indented));
}

Exemplo de JavaScriptJavaScript example

O exemplo a seguir mostra uma associação de gatilho em um arquivo function.json e uma função JavaScript que usa a associação.The following example shows a trigger binding in a function.json file and a JavaScript function that uses the binding.

Aqui estão os dados de associação no arquivo function.json:Here's the binding data in the function.json file:

{
  "bindings": [
    {
      "type": "eventGridTrigger",
      "name": "eventGridEvent",
      "direction": "in"
    }
  ],
  "disabled": false
}

Aqui está o código JavaScript:Here's the JavaScript code:

module.exports = function (context, eventGridEvent) {
    context.log("JavaScript Event Grid function processed a request.");
    context.log("Subject: " + eventGridEvent.subject);
    context.log("Time: " + eventGridEvent.eventTime);
    context.log("Data: " + JSON.stringify(eventGridEvent.data));
    context.done();
};

Exemplo de PythonPython example

O exemplo a seguir mostra uma associação de gatilhos em um arquivo function.json e uma função Python que usa a associação.The following example shows a trigger binding in a function.json file and a Python function that uses the binding.

Aqui estão os dados de associação no arquivo function.json:Here's the binding data in the function.json file:

{
  "bindings": [
    {
      "type": "eventGridTrigger",
      "name": "event",
      "direction": "in"
    }
  ],
  "disabled": false,
  "scriptFile": "__init__.py"
}

Confira o código Python:Here's the Python code:

import logging
import azure.functions as func


def main(event: func.EventGridEvent):
    logging.info("Python Event Grid function processed a request.")
    logging.info("  Subject: %s", event.subject)
    logging.info("  Time: %s", event.event_time)
    logging.info("  Data: %s", event.get_json())

Gatilho - exemplos JavaTrigger - Java examples

Esta seção contém os seguintes exemplos:This section contains the following examples:

Os exemplos a seguir mostram a associação de gatilho em um arquivo function.JSON e funções Java que usam a associação e imprimem um evento, primeiro recebendo o evento como String e o segundo como um POJO.The following examples show trigger binding in a function.json file and Java functions that use the binding and print out an event, first receiving the event as String and second as a POJO.

{
  "bindings": [
    {
      "type": "eventGridTrigger",
      "name": "eventGridEvent",
      "direction": "in"
    }
  ]
}

Gatilho de grade de eventos, parâmetro de cadeia de caracteres (Java)Event Grid trigger, String parameter (Java)

  @FunctionName("eventGridMonitorString")
  public void logEvent(
    @EventGridTrigger(
      name = "event"
    ) 
    String content, 
    final ExecutionContext context) {
      context.getLogger().info("Event content: " + content);      
  }

Gatilho de grade de eventos, parâmetro POJO (Java)Event Grid trigger, POJO parameter (Java)

Este exemplo usa o POJO a seguir, que representa as propriedades de nível superior de uma grade de eventos:This example uses the following POJO, representing the top-level properties of an Event Grid event:

import java.util.Date;
import java.util.Map;

public class EventSchema {

  public String topic;
  public String subject;
  public String eventType;
  public Date eventTime;
  public String id;
  public String dataVersion;
  public String metadataVersion;
  public Map<String, Object> data;

}

Na chegada, o conteúdo JSON do evento fica sem serialização no POJO EventSchema para uso pela função.Upon arrival, the event's JSON payload is de-serialized into the EventSchema POJO for use by the function. Isso permite que a função acesse as propriedades do evento de forma orientada a objeto.This allows the function to access the event's properties in an object-oriented way.

  @FunctionName("eventGridMonitor")
  public void logEvent(
    @EventGridTrigger(
      name = "event"
    ) 
    EventSchema event, 
    final ExecutionContext context) {
      context.getLogger().info("Event content: ");
      context.getLogger().info("Subject: " + event.subject);
      context.getLogger().info("Time: " + event.eventTime); // automatically converted to Date by the runtime
      context.getLogger().info("Id: " + event.id);
      context.getLogger().info("Data: " + event.data);
  }

No biblioteca de runtime de funções Java, use o EventGridTrigger anotação em parâmetros cujo valor virá do EventGrid.In the Java functions runtime library, use the EventGridTrigger annotation on parameters whose value would come from EventGrid. Parâmetros com essas anotações fazem com que a função seja executada quando um evento chega.Parameters with these annotations cause the function to run when an event arrives. Essa anotação pode ser usada com tipos nativos do Java, POJOs ou valores que permitem valor nulos usando Optional<T>.This annotation can be used with native Java types, POJOs, or nullable values using Optional<T>.

AtributosAttributes

Em bibliotecas de classes de C#, utilize o atributo EventGridTrigger.In C# class libraries, use the EventGridTrigger attribute.

Aqui está um atributo EventGridTrigger em uma assinatura de método:Here's an EventGridTrigger attribute in a method signature:

[FunctionName("EventGridTest")]
public static void EventGridTest([EventGridTrigger] JObject eventGridEvent, ILogger log)
{
    ...
}

Para ver um exemplo completo, confira o exemplo de C#.For a complete example, see C# example.

ConfiguraçãoConfiguration

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json.The following table explains the binding configuration properties that you set in the function.json file. Não há parâmetros ou propriedades do construtor para definir o atributo EventGridTrigger.There are no constructor parameters or properties to set in the EventGridTrigger attribute.

Propriedade function.jsonfunction.json property DESCRIÇÃODescription
tipotype Obrigatório – deve ser definido como eventGridTrigger.Required - must be set to eventGridTrigger.
directiondirection Obrigatório – deve ser definido como in.Required - must be set to in.
namename Obrigatório - o nome da variável usado no código de função para o parâmetro que recebe os dados de eventos.Required - the variable name used in function code for the parameter that receives the event data.

UsoUsage

Para C# e F# funções no Azure funciona 1. x, você pode usar os seguintes tipos de parâmetro para o disparador de grade de eventos:For C# and F# functions in Azure Functions 1.x, you can use the following parameter types for the Event Grid trigger:

  • JObject
  • string

Para C# e F# funções nas funções do Azure 2. x, você também tem a opção de usar o seguinte tipo de parâmetro para o disparador de grade de eventos:For C# and F# functions in Azure Functions 2.x, you also have the option to use the following parameter type for the Event Grid trigger:

  • Microsoft.Azure.EventGrid.Models.EventGridEvent- Define propriedades para os campos comuns a todos os tipos de eventos.Microsoft.Azure.EventGrid.Models.EventGridEvent- Defines properties for the fields common to all event types.

Observação

Em funções v1 se você tentar associar ao Microsoft.Azure.WebJobs.Extensions.EventGrid.EventGridEvent, o compilador exibirá uma mensagem "substituído" e avisá-lo para usar Microsoft.Azure.EventGrid.Models.EventGridEvent em vez disso.In Functions v1 if you try to bind to Microsoft.Azure.WebJobs.Extensions.EventGrid.EventGridEvent, the compiler will display a "deprecated" message and advise you to use Microsoft.Azure.EventGrid.Models.EventGridEvent instead. Para usar o tipo mais recente, fazer referência a Microsoft.Azure.EventGrid NuGet empacotar e qualificar totalmente o EventGridEvent nome do tipo, prefixando-o com Microsoft.Azure.EventGrid.Models.To use the newer type, reference the Microsoft.Azure.EventGrid NuGet package and fully qualify the EventGridEvent type name by prefixing it with Microsoft.Azure.EventGrid.Models. Para obter informações sobre como fazer referência a pacotes do NuGet em uma função de script C#, consulte pacotes usando o NuGetFor information about how to reference NuGet packages in a C# script function, see Using NuGet packages

Para funções JavaScript, o parâmetro nomeado pela propriedade function.json name tem uma referência ao objeto de evento.For JavaScript functions, the parameter named by the function.json name property has a reference to the event object.

Esquema do eventoEvent schema

Os dados de uma Grade de Eventos são recebidos como um objeto JSON no corpo de uma solicitação HTTP.Data for an Event Grid event is received as a JSON object in the body of an HTTP request. O JSON é semelhante ao exemplo a seguir:The JSON looks similar to the following example:

[{
  "topic": "/subscriptions/{subscriptionid}/resourceGroups/eg0122/providers/Microsoft.Storage/storageAccounts/egblobstore",
  "subject": "/blobServices/default/containers/{containername}/blobs/blobname.jpg",
  "eventType": "Microsoft.Storage.BlobCreated",
  "eventTime": "2018-01-23T17:02:19.6069787Z",
  "id": "{guid}",
  "data": {
    "api": "PutBlockList",
    "clientRequestId": "{guid}",
    "requestId": "{guid}",
    "eTag": "0x8D562831044DDD0",
    "contentType": "application/octet-stream",
    "contentLength": 2248,
    "blobType": "BlockBlob",
    "url": "https://egblobstore.blob.core.windows.net/{containername}/blobname.jpg",
    "sequencer": "000000000000272D000000000003D60F",
    "storageDiagnostics": {
      "batchId": "{guid}"
    }
  },
  "dataVersion": "",
  "metadataVersion": "1"
}]

O exemplo mostrado é uma matriz de um elemento.The example shown is an array of one element. A Grade de Eventos envia sempre uma matriz e pode enviar mais de um evento na matriz.Event Grid always sends an array and may send more than one event in the array. O runtime invoca sua função uma vez para cada elemento da matriz.The runtime invokes your function once for each array element.

As propriedades de nível superior nos dados JSON de evento serão as mesmas entre todos os tipos de eventos, enquanto os conteúdos da propriedade data estiverem especificados para cada tipo de evento.The top-level properties in the event JSON data are the same among all event types, while the contents of the data property are specific to each event type. O exemplo mostrado é para um evento de armazenamento de Blobs.The example shown is for a blob storage event.

Para obter explicações sobre as propriedades comuns e específicas de evento, consulte Propriedades do evento na documentação da Grade de Eventos.For explanations of the common and event-specific properties, see Event properties in the Event Grid documentation.

O tipo EventGridEvent define apenas as propriedades de nível superior; a propriedade Data é um JObject.The EventGridEvent type defines only the top-level properties; the Data property is a JObject.

Criar uma assinaturaCreate a subscription

Para iniciar o recebimento de solicitações HTTP de Grade de Eventos, crie uma assinatura na Grade de Eventos que especifique a URL do ponto de extremidade que invoca a função.To start receiving Event Grid HTTP requests, create an Event Grid subscription that specifies the endpoint URL that invokes the function.

Portal do AzureAzure portal

Para as funções que você desenvolve no Portal do Azure com o gatilho de Grade de Eventos, selecione Adicionar assinatura da Grade de Eventos.For functions that you develop in the Azure portal with the Event Grid trigger, select Add Event Grid subscription.

Criar assinatura no portal

Ao selecionar esse link, o portal abrirá a página Criar Assinatura de Evento com a URL do ponto de extremidade preenchida.When you select this link, the portal opens the Create Event Subscription page with the endpoint URL prefilled.

URL do ponto de extremidade preenchida

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.For more information about how to create subscriptions by using the Azure portal, see Create custom event - Azure portal in the Event Grid documentation.

CLI do AzureAzure CLI

Para criar uma assinatura usando a CLI do Azure, use o comando az eventgrid event-subscription create.To create a subscription by using the Azure CLI, use the az eventgrid event-subscription create command.

O comando requer a URL do ponto de extremidade que invoca a função.The command requires the endpoint URL that invokes the function. O exemplo a seguir mostra o padrão de URL específico da versão:The following example shows the version-specific URL pattern:

runtime versão 2.xVersion 2.x runtime

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

runtime versão 1.xVersion 1.x runtime

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

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.The system key is an authorization key that has to be included in the endpoint URL for an Event Grid trigger. A seção a seguir explica como obter a chave do sistema.The following section explains how to get the system key.

Apresentamos aqui um exemplo que assina em uma conta de armazenamento de Blobs (com um espaço reservado para a chave do sistema):Here's an example that subscribes to a blob storage account (with a placeholder for the system key):

runtime versão 2.xVersion 2.x runtime

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>

runtime versão 1.xVersion 1.x runtime

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/admin/extensions/EventGridExtensionConfig?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.For more information about how to create a subscription, see the blob storage quickstart or the other Event Grid quickstarts.

Obter a chave do sistemaGet the system key

Você pode obter a chave do sistema usando a seguinte API (HTTP GET):You can get the system key by using the following API (HTTP GET):

runtime versão 2.xVersion 2.x runtime

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

runtime versão 1.xVersion 1.x runtime

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

Esta é uma API de administração, por isso, requer sua chave mestre do aplicativo.This is an admin API, so it requires your function app master key. 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).Don't confuse the system key (for invoking an Event Grid trigger function) with the master key (for performing administrative tasks on the function app). Ao assinar em um tópico da Grade de Eventos, certifique-se de usar a chave do sistema.When you subscribe to an Event Grid topic, be sure to use the system key.

Aqui, está um exemplo da resposta que fornece a chave do sistema:Here's an example of the response that provides the system key:

{
  "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.You can get the master key for your function app from the Function app settings tab in the portal.

Importante

A chave mestra fornece acesso de administrador para seu aplicativo de funções.The master key provides administrator access to your function app. Não compartilhe essa chave com terceiros ou distribua-a em aplicativos clientes nativos.Don't share this key with third parties or distribute it in native client applications.

Para obter mais informações, consulte Chaves de autorização no artigo de referência de gatilho HTTP.For more information, see Authorization keys in the HTTP trigger reference article.

Como alternativa, você mesmo pode enviar uma HTTP PUT para especificar o valor da chave.Alternatively, you can send an HTTP PUT to specify the key value yourself.

Teste local com o aplicativo Web visualizadorLocal testing with viewer web app

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.To test an Event Grid trigger locally, you have to get Event Grid HTTP requests delivered from their origin in the cloud to your local machine. Uma maneira de fazer isso é capturar solicitações online e manualmente reenviá-las em sua máquina local:One way to do that is by capturing requests online and manually resending them on your local machine:

  1. Criar um aplicativo Web visualizador que captura as mensagens de evento.Create a viewer web app that captures event messages.
  2. Criar uma assinatura da Grade de Eventos que envia eventos para o aplicativo visualizador.Create an Event Grid subscription that sends events to the viewer app.
  3. Gerar uma solicitação e copiar o corpo da solicitação do aplicativo visualizador.Generate a request and copy the request body from the viewer app.
  4. Postar manualmente a solicitação para a URL localhost da sua função de gatilho da Grade de Eventos.Manually post the request to the localhost URL of your Event Grid trigger function.

Quando terminar de testar, você poderá usar a mesma assinatura para a produção atualizando o ponto de extremidade.When you're done testing, you can use the same subscription for production by updating the endpoint. Use o comando da CLI do Azureaz eventgrid event-subscription update.Use the az eventgrid event-subscription update Azure CLI command.

Criar um aplicativo Web visualizadorCreate a viewer web app

Para simplificar as mensagens de evento de captura, implante um aplicativo Web predefinido que exibe as mensagens de evento.To simplify capturing event messages, you can deploy a pre-built web app that displays the event messages. 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.The deployed solution includes an App Service plan, an App Service web app, and source code from GitHub.

Selecione Implantar no Azure para implantar a solução na sua assinatura.Select Deploy to Azure to deploy the solution to your subscription. No portal do Azure, forneça os valores para os parâmetros.In the Azure portal, provide values for the parameters.

A implantação pode levar alguns minutos para ser concluída.The deployment may take a few minutes to complete. Depois que a implantação for bem-sucedida, exiba seu aplicativo Web para garantir que ele esteja em execução.After the deployment has succeeded, view your web app to make sure it's running. Em um navegador da Web, navegue até: https://<your-site-name>.azurewebsites.netIn a web browser, navigate to: https://<your-site-name>.azurewebsites.net

Você verá o site, mas nenhum evento ainda estará publicado.You see the site but no events have been posted to it yet.

Exibir novo site

Criar uma assinatura na Grade de EventosCreate an Event Grid subscription

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.Create an Event Grid subscription of the type you want to test, and give it the URL from your web app as the endpoint for event notification. O ponto de extremidade para seu aplicativo Web deve incluir o sufixo /api/updates/.The endpoint for your web app must include the suffix /api/updates/. Portanto, a URL completa é https://<your-site-name>.azurewebsites.net/api/updatesSo, the full URL is 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.For information about how to create subscriptions by using the Azure portal, see Create custom event - Azure portal in the Event Grid documentation.

Gerar uma solicitaçãoGenerate a request

Dispare um evento que gerará tráfego HTTP para o ponto de extremidade do aplicativo Web.Trigger an event that will generate HTTP traffic to your web app endpoint. Por exemplo, se você criou uma assinatura de armazenamento de Blobs, faça upload ou exclua um blob.For example, if you created a blob storage subscription, upload or delete a blob. Quando uma solicitação for exibida no aplicativo Web, copie o corpo da solicitação.When a request shows up in your web app, copy the request body.

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.The subscription validation request will be received first; ignore any validation requests, and copy the event request.

Copiar o corpo da solicitação do aplicativo Web

Postar manualmente a solicitaçãoManually post the request

Execute sua função de Grade de Eventos localmente.Run your Event Grid function locally.

Use uma ferramenta como Postman ou curl para criar uma solicitação HTTP POST:Use a tool such as Postman or curl to create an HTTP POST request:

  • Defina um cabeçalho Content-Type: application/json.Set a Content-Type: application/json header.
  • Defina um cabeçalho aeg-event-type: Notification.Set an aeg-event-type: Notification header.
  • Cole os dados RequestBin no corpo da solicitação.Paste the RequestBin data into the request body.
  • Poste para a URL da sua função de gatilho de grade de eventos.Post to the URL of your Event Grid trigger function.
    • Para 2. x, use o seguinte padrão:For 2.x use the following pattern:

      http://localhost:7071/runtime/webhooks/eventgrid?functionName={FUNCTION_NAME}
      
    • Para uso de 1. x:For 1.x use:

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

O parâmetro functionName deverá ser o nome especificado no atributo FunctionName.The functionName parameter must be the name specified in the FunctionName attribute.

As capturas de tela a seguir mostram os cabeçalhos e o corpo da solicitação em Postman:The following screenshots show the headers and request body in Postman:

Cabeçalhos em Postman

Corpo da solicitação em Postman

A função de gatilho da Grade de Eventos executa e mostra logs semelhantes ao exemplo a seguir:The Event Grid trigger function executes and shows logs similar to the following example:

Amostra de logs da função de gatilho de Grade de Eventos

Teste local com ngrokLocal testing with ngrok

Outra maneira de testar um gatilho de Grade de Eventos localmente é automatizar a conexão HTTP entre a Internet e o computador de desenvolvimento.Another way to test an Event Grid trigger locally is to automate the HTTP connection between the Internet and your development computer. Você pode fazer isso com uma ferramenta como ngrok:You can do that with a tool like ngrok:

  1. Criar um ponto de extremidade ngrok.Create an ngrok endpoint.
  2. Executar a função de gatilho de Grade de Eventos .Run the Event Grid trigger function.
  3. Criar uma assinatura na Grade de Eventos que envia eventos para o ponto de extremidade ngrok.Create an Event Grid subscription that sends events to the ngrok endpoint.
  4. Disparar um evento.Trigger an event.

Quando terminar de testar, você poderá usar a mesma assinatura para a produção atualizando o ponto de extremidade.When you're done testing, you can use the same subscription for production by updating the endpoint. Use o comando da CLI do Azureaz eventgrid event-subscription update.Use the az eventgrid event-subscription update Azure CLI command.

Criar um ponto de extremidade ngrokCreate an ngrok endpoint

Faça o download do ngrok.exe do ngrok e execute com o seguinte comando:Download ngrok.exe from ngrok, and run with the following command:

ngrok http -host-header=localhost 7071

O parâmetro -host-header é necessário porque o runtime das funções espera solicitações do localhost quando é executado no localhost.The -host-header parameter is needed because the functions runtime expects requests from localhost when it runs on localhost. 7071 é o número de porta padrão quando o runtime é executado localmente.7071 is the default port number when the runtime runs locally.

O comando cria saída semelhante à seguinte:The command creates output like the following:

Session Status                online
Version                       2.2.8
Region                        United States (us)
Web Interface                 http://127.0.0.1:4040
Forwarding                    http://263db807.ngrok.io -> localhost:7071
Forwarding                    https://263db807.ngrok.io -> localhost:7071

Connections                   ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00

Você usará o URL https://{subdomain}.ngrok.io para sua inscrição na grade de eventos.You'll use the https://{subdomain}.ngrok.io URL for your Event Grid subscription.

Executar a função de gatilho de Grade de EventosRun the Event Grid trigger function

A URL ngrok não recebe tratamento especial pela Grade de Eventos, portanto, sua função deverá ser executada localmente quando a assinatura for criada.The ngrok URL doesn't get special handling by Event Grid, so your function must be running locally when the subscription is created. Caso contrário, a resposta de validação não será enviada e a criação da assinatura falhará.If it isn't, the validation response doesn't get sent and the subscription creation fails.

Criar uma assinaturaCreate a subscription

Crie uma assinatura de grade de eventos do tipo que você deseja testar e forneça seu ponto de extremidade ngrok.Create an Event Grid subscription of the type you want to test, and give it your ngrok endpoint.

Use este padrão de terminal para Funções 2.x:Use this endpoint pattern for Functions 2.x:

https://{SUBDOMAIN}.ngrok.io/runtime/webhooks/eventgrid?functionName={FUNCTION_NAME}

Use este padrão de terminal para Funções 1.x:Use this endpoint pattern for Functions 1.x:

https://{SUBDOMAIN}.ngrok.io/admin/extensions/EventGridExtensionConfig?functionName={FUNCTION_NAME}

O parâmetro {FUNCTION_NAME} deverá ser o nome especificado no atributo FunctionName.The {FUNCTION_NAME} parameter must be the name specified in the FunctionName attribute.

Aqui, está um exemplo usando a CLI do Azure:Here's an example using the Azure CLI:

az eventgrid event-subscription create --resource-id /subscriptions/aeb4b7cb-b7cb-b7cb-b7cb-b7cbb6607f30/resourceGroups/eg0122/providers/Microsoft.Storage/storageAccounts/egblobstor0122 --name egblobsub0126 --endpoint https://263db807.ngrok.io/runtime/webhooks/eventgrid?functionName=EventGridTrigger

Para obter informações sobre como criar uma assinatura, consulte Criar uma assinatura, posteriormente neste artigo.For information about how to create a subscription, see Create a subscription earlier in this article.

Disparar um eventoTrigger an event

Dispare um evento que gerará tráfego HTTP para o ponto de extremidade ngrok.Trigger an event that will generate HTTP traffic to your ngrok endpoint. Por exemplo, se você criou uma assinatura de armazenamento de Blobs, faça upload ou exclua um blob.For example, if you created a blob storage subscription, upload or delete a blob.

A função de gatilho da Grade de Eventos executa e mostra logs semelhantes ao exemplo a seguir:The Event Grid trigger function executes and shows logs similar to the following example:

Amostra de logs da função de gatilho de Grade de Eventos

Use um gatilho HTTP como um gatilho de Grade de EventosUse an HTTP trigger as an Event Grid trigger

Os eventos da Grade de Eventos são recebidos como solicitações HTTP, para que você possa manipular eventos usando um gatilho HTTP em vez de um gatilho de Grade de Eventos.Event Grid events are received as HTTP requests, so you can handle events by using an HTTP trigger instead of an Event Grid trigger. Um possível motivo para isso é obter mais controle sobre a URL do ponto de extremidade que invoca a função.One possible reason for doing that is to get more control over the endpoint URL that invokes the function. Outro motivo é quando você precisa receber eventos no esquema CloudEvents.Another reason is when you need to receive events in the CloudEvents schema. Atualmente, o gatilho da Grade de Eventos não dá suporte ao esquema CloudEvents.Currently, the Event Grid trigger doesn't support the CloudEvents schema. Os exemplos desta seção mostram soluções para o esquema da Grade de Eventos e o esquema CloudEvents.The examples in this section show solutions for both Event Grid schema and CloudEvents schema.

Se você usar um gatilho HTTP, será necessário gravar o código para o que o gatilho da Grade de Eventos automaticamente:If you use an HTTP trigger, you have to write code for what the Event Grid trigger does automatically:

Para obter informações sobre a URL a ser utilizada para invocar a função localmente ou quando for executada no Azure, consulte a documentação de referência de associação de gatilho HTTPFor information about the URL to use for invoking the function locally or when it runs in Azure, see the HTTP trigger binding reference documentation

Esquema da Grade de EventosEvent Grid schema

O código C# de exemplo a seguir para um gatilho HTTP simula o comportamento do gatilho da Grade de Eventos.The following sample C# code for an HTTP trigger simulates Event Grid trigger behavior. Use este exemplo para eventos entregues no esquema da Grade de Eventos.Use this example for events delivered in the Event Grid schema.

[FunctionName("HttpTrigger")]
public static async Task<HttpResponseMessage> Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post")]HttpRequestMessage req,
    ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    var messages = await req.Content.ReadAsAsync<JArray>();

    // If the request is for subscription validation, send back the validation code.
    if (messages.Count > 0 && string.Equals((string)messages[0]["eventType"],
        "Microsoft.EventGrid.SubscriptionValidationEvent",
        System.StringComparison.OrdinalIgnoreCase))
    {
        log.LogInformation("Validate request received");
        return req.CreateResponse<object>(new
        {
            validationResponse = messages[0]["data"]["validationCode"]
        });
    }

    // The request is not for subscription validation, so it's for one or more events.
    foreach (JObject message in messages)
    {
        // Handle one event.
        EventGridEvent eventGridEvent = message.ToObject<EventGridEvent>();
        log.LogInformation($"Subject: {eventGridEvent.Subject}");
        log.LogInformation($"Time: {eventGridEvent.EventTime}");
        log.LogInformation($"Event data: {eventGridEvent.Data.ToString()}");
    }

    return req.CreateResponse(HttpStatusCode.OK);
}

O código JavaScript de exemplo a seguir para um gatilho HTTP simula o comportamento do gatilho da Grade de Eventos.The following sample JavaScript code for an HTTP trigger simulates Event Grid trigger behavior. Use este exemplo para eventos entregues no esquema da Grade de Eventos.Use this example for events delivered in the Event Grid schema.

module.exports = function (context, req) {
    context.log('JavaScript HTTP trigger function processed a request.');

    var messages = req.body;
    // If the request is for subscription validation, send back the validation code.
    if (messages.length > 0 && messages[0].eventType == "Microsoft.EventGrid.SubscriptionValidationEvent") {
        context.log('Validate request received');
        var code = messages[0].data.validationCode;
        context.res = { status: 200, body: { "ValidationResponse": code } };
    }
    else {
        // The request is not for subscription validation, so it's for one or more events.
        // Event Grid schema delivers events in an array.
        for (var i = 0; i < messages.length; i++) {
            // Handle one event.
            var message = messages[i];
            context.log('Subject: ' + message.subject);
            context.log('Time: ' + message.eventTime);
            context.log('Data: ' + JSON.stringify(message.data));
        }
    }
    context.done();
};

O código de manipulação de eventos está dentro do loop através da matriz messages.Your event-handling code goes inside the loop through the messages array.

Esquema CloudEventsCloudEvents schema

O código C# de exemplo a seguir para um gatilho HTTP simula o comportamento do gatilho da Grade de Eventos.The following sample C# code for an HTTP trigger simulates Event Grid trigger behavior. Use este exemplo para eventos entregues no esquema CloudEvents.Use this example for events delivered in the CloudEvents schema.

[FunctionName("HttpTrigger")]
public static async Task<HttpResponseMessage> Run([HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)]HttpRequestMessage req, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    var requestmessage = await req.Content.ReadAsStringAsync();
    var message = JToken.Parse(requestmessage);

    if (message.Type == JTokenType.Array)
    {
        // If the request is for subscription validation, send back the validation code.
        if (string.Equals((string)message[0]["eventType"],
        "Microsoft.EventGrid.SubscriptionValidationEvent",
        System.StringComparison.OrdinalIgnoreCase))
        {
            log.LogInformation("Validate request received");
            return req.CreateResponse<object>(new
            {
                validationResponse = message[0]["data"]["validationCode"]
            });
        }
    }
    else
    {
        // The request is not for subscription validation, so it's for an event.
        // CloudEvents schema delivers one event at a time.
        log.LogInformation($"Source: {message["source"]}");
        log.LogInformation($"Time: {message["eventTime"]}");
        log.LogInformation($"Event data: {message["data"].ToString()}");
    }

    return req.CreateResponse(HttpStatusCode.OK);
}

O código JavaScript de exemplo a seguir para um gatilho HTTP simula o comportamento do gatilho da Grade de Eventos.The following sample JavaScript code for an HTTP trigger simulates Event Grid trigger behavior. Use este exemplo para eventos entregues no esquema CloudEvents.Use this example for events delivered in the CloudEvents schema.

module.exports = function (context, req) {
    context.log('JavaScript HTTP trigger function processed a request.');

    var message = req.body;
    // If the request is for subscription validation, send back the validation code.
    if (message.length > 0 && message[0].eventType == "Microsoft.EventGrid.SubscriptionValidationEvent") {
        context.log('Validate request received');
        var code = message[0].data.validationCode;
        context.res = { status: 200, body: { "ValidationResponse": code } };
    }
    else {
        // The request is not for subscription validation, so it's for an event.
        // CloudEvents schema delivers one event at a time.
        var event = JSON.parse(message);
        context.log('Source: ' + event.source);
        context.log('Time: ' + event.eventTime);
        context.log('Data: ' + JSON.stringify(event.data));
    }
    context.done();
};

Próximas etapasNext steps