Gatilho da Grade de Eventos do Azure para o Azure Functions

Use o gatilho de funções para responder a um evento enviado por uma Origem da Grade de Eventos. Você precisa ter uma assinatura de evento da origem para receber eventos. Para saber como criar uma assinatura de evento, confira Criar uma assinatura. Para obter informações sobre a instalação e a configuração de associação, confira a visão geral.

Observação

Não há suporte nativo para os gatilhos da Grade de Eventos em um balanceador de carga interno do Ambiente do Serviço de Aplicativo (ASE). O gatilho usa uma solicitação HTTP que não pode acessar o aplicativo de funções sem um gateway na rede virtual.

Importante

Este artigo usa guias para dar suporte a várias versões do modelo de programação Node.js. O modelo v4 normalmente está disponível e foi projetado para oferecer uma experiência mais flexível e intuitiva para desenvolvedores de JavaScript e TypeScript. Para obter mais detalhes sobre como funciona o modelo v4, consulte o Guia do desenvolvedor do Node.js para o Azure Functions. Para saber mais sobre as diferenças entre os modelos v3 e a v4, consulte o Guia de migração.

O Azure Functions dá suporte a dois modelos de programação para Python. A maneira como você define suas associações depende do modelo de programação escolhido.

v2

O modelo de programação v2 do Python permite que você defina associações usando decoradores diretamente no código de função do Python. Para saber mais, confira o Guia do desenvolvedor do Python.

v1

O modelo de programação v1 do Python requer que você defina as associações em um arquivo function.json separado na pasta de funções. Para saber mais, confira o Guia do desenvolvedor do Python.

Este artigo dá suporte a ambos os modelos de programação.

Exemplo

Para ver um exemplo de gatilho HTTP, confira Receber eventos para um ponto de extremidade HTTP.

O tipo do parâmetro de entrada usado com um gatilho da Grade de Eventos depende destes três fatores:

• Versão do runtime do Functions
• Versão de extensão da associação
• Modalidade da função C#.

A função C# pode ser criada por meio de um dos seguintes modos C#:

• Modelo de trabalho isolado: função C# compilada executada em um processo de trabalho que está isolado do runtime. É necessário um processo de trabalho isolado para dar suporte às funções C# executadas nas versões LTS e não LTS do .NET e do .NET Framework. As extensões para funções do processo de trabalho isoladas usam namespaces Microsoft.Azure.Functions.Worker.Extensions.*.
• Modelo em processo: função C# compilada no mesmo processo que o runtime do Functions. Em uma variação desse modelo, o Functions pode ser executado usando scripts C#, que é compatível principalmente com a edição do portal C#. As extensões para funções dentro do processo usam namespaces Microsoft.Azure.WebJobs.Extensions.*.

Importante

O suporte para o modelo em processo terminará em 10 de novembro de 2026. É altamente recomendável que você migre seus aplicativos para o modelo de trabalho isolado para obter suporte completo.

Modelo de trabalho isolado

Ao executar sua função C# em um processo de trabalho isolado, você precisa definir um tipo personalizado para propriedades de evento. O exemplo a seguir define uma classe MyEventType.

    public class MyEventType
    {
        public string Id { get; set; }

        public string Topic { get; set; }

        public string Subject { get; set; }

        public string EventType { get; set; }

        public DateTime EventTime { get; set; }

        public IDictionary<string, object> Data { get; set; }
    }
}

O exemplo a seguir mostra como o tipo personalizado é usado no gatilho e em uma associação de saída da Grade de Eventos:

public static class EventGridFunction
{
    [Function(nameof(EventGridFunction))]
    [EventGridOutput(TopicEndpointUri = "MyEventGridTopicUriSetting", TopicKeySetting = "MyEventGridTopicKeySetting")]
    public static MyEventType Run([EventGridTrigger] MyEventType input, FunctionContext context)
    {
        var logger = context.GetLogger(nameof(EventGridFunction));

        logger.LogInformation(input.Data.ToString());

        var outputEvent = new MyEventType()
        {
            Id = "unique-id",
            Subject = "abc-subject",
            Data = new Dictionary<string, object>
            {
                { "myKey", "myValue" }
            }
        };

        return outputEvent;
    }
}

Modelo em processo

O exemplo a seguir mostra uma função do Functions versão 4.x que usa um parâmetro de associação CloudEvent:

using Azure.Messaging;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
using Microsoft.Extensions.Logging;

namespace Company.Function
{
    public static class CloudEventTriggerFunction
    {
        [FunctionName("CloudEventTriggerFunction")]
        public static void Run(
            ILogger logger,
            [EventGridTrigger] CloudEvent e)
        {
            logger.LogInformation("Event received {type} {subject}", e.Type, e.Subject);
        }
    }
}

O exemplo a seguir mostra uma função do Functions versão 4.x que usa um parâmetro de associação EventGridEvent:

using Microsoft.Azure.WebJobs;
using Azure.Messaging.EventGrid;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
using Microsoft.Extensions.Logging;

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

O exemplo a seguir mostra uma função que usa um parâmetro de associação JObject:

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
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));
        }
    }
}

Esta seção contém os seguintes exemplos:

• Gatilho de grade de eventos, parâmetro de cadeia de caracteres
• Gatilho de grade de eventos, parâmetro POJO

Os exemplos a seguir mostram a associação de gatilho em Java que usam a associação e geram um evento, primeiro recebendo o evento como String e o segundo como um POJO.

Gatilho de Grade de Eventos, parâmetro de cadeia de caracteres

  @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

Este exemplo usa o POJO a seguir, que representa as propriedades de nível superior de uma grade de eventos:

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. Esse processo permite que a função acesse as propriedades do evento de forma orientada a objeto.

  @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);
  }

Na biblioteca de runtime de funções Java, use a anotação EventGridTrigger em parâmetros cujo valor virá do Hub de Eventos. Parâmetros com essas anotações fazem com que a função seja executada quando um evento é recebido. Essa anotação pode ser usada com tipos nativos do Java, POJOs ou valores que permitem valor nulos usando Optional<T>.

Modelo v4

O exemplo a seguir mostra uma função TypeScript de acionamento de grade de eventos.

import { app, EventGridEvent, InvocationContext } from '@azure/functions';

export async function eventGridTrigger1(event: EventGridEvent, context: InvocationContext): Promise<void> {
    context.log('Event grid function processed event:', event);
}

app.eventGrid('eventGridTrigger1', {
    handler: eventGridTrigger1,
});

Modelo v3

Os exemplos de TypeScript não estão documentados para o modelo v3.

Modelo v4

O exemplo a seguir mostra uma função JavaScript de acionamento de grade de eventos.

const { app } = require('@azure/functions');

app.eventGrid('eventGridTrigger1', {
    handler: (event, context) => {
        context.log('Event grid function processed event:', event);
    },
});

Modelo v3

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.

Aqui estão os dados de associação no arquivo function.json:

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

Aqui está o código JavaScript:

module.exports = async 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));
};

O exemplo a seguir mostra como configurar uma associação de gatilho da Grade de Eventos no arquivo function.json.

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

O evento Grade de Eventos é disponibilizado para a função por meio de um parâmetro nomeado eventGridEvent, conforme mostrado no seguinte exemplo do PowerShell.

param($eventGridEvent, $TriggerMetadata)

# Make sure to pass hashtables to Out-String so they're logged correctly
$eventGridEvent | Out-String | Write-Host

O exemplo a seguir mostra uma associação de gatilho de Grade de Eventos e uma função do Python que usa a associação. O exemplo depende do modelo de programação v1 ou v2 do Python que você usa.

v2

import logging
import json
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="eventGridTrigger")
@app.event_grid_trigger(arg_name="event")
def eventGridTest(event: func.EventGridEvent):
    result = json.dumps({
        'id': event.id,
        'data': event.get_json(),
        'topic': event.topic,
        'subject': event.subject,
        'event_type': event.event_type,
    })

    logging.info('Python EventGrid trigger processed an event: %s', result)

v1

Aqui estão os dados de associação no arquivo function.json:

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

Aqui está o código Python:

import json
import logging

import azure.functions as func

def main(event: func.EventGridEvent):

    result = json.dumps({
        'id': event.id,
        'data': event.get_json(),
        'topic': event.topic,
        'subject': event.subject,
        'event_type': event.event_type,
    })

    logging.info('Python EventGrid trigger processed an event: %s', result)

Atributos

As bibliotecas C# em processo e de processo de trabalho isolado usam o atributo EventGridTrigger. Em vez disso, o script C# usa um arquivo de configuração function.json, conforme descrito no guia do script C# .

Modelo de trabalho isolado

Aqui está um atributo EventGridTrigger em uma assinatura de método:

[Function(nameof(EventGridFunction))]
[EventGridOutput(TopicEndpointUri = "MyEventGridTopicUriSetting", TopicKeySetting = "MyEventGridTopicKeySetting")]
public static MyEventType Run([EventGridTrigger] MyEventType input, FunctionContext context)
{

Modelo em processo

Aqui está um atributo EventGridTrigger em uma assinatura de método:

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

Anotações

A anotação EventGridTrigger permite configurar declarativamente uma associação de Grade de Eventos fornecendo valores de configuração. Confira as seções exemplo e configuração para obter mais detalhes.

Configuração

Modelo v4

Atualmente, o objeto options transmitido para o método app.eventGrid() não dá suporte a nenhuma propriedade do modelo v4.

Modelo v3

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json.

Propriedade	Descrição
tipo	Obrigatório – deve ser definido como eventGridTrigger.
direction	Obrigatório – deve ser definido como in.
name	Obrigatório - o nome da variável usado no código de função para o parâmetro que recebe os dados de eventos.

Configuração

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json. Não há parâmetros ou propriedades do construtor para definir o atributo EventGridTrigger.

Propriedade function.json	Descrição
tipo	Obrigatório – deve ser definido como eventGridTrigger.
direction	Obrigatório – deve ser definido como in.
name	Obrigatório - o nome da variável usado no código de função para o parâmetro que recebe os dados de eventos.

Consulte a Seção de exemplo para obter exemplos completos.

Uso

O gatilho da Grade de Eventos usa uma solicitação HTTP de webhook, que pode ser configurada com as mesmas definições host.json usadas pelo Gatilho HTTP.

Os tipos específicos com suporte pelo gatilho da Grade de Eventos dependem da versão de runtime do Functions, da versão do pacote de extensão e da modalidade de C# usada.

Extensão v3.x

As funções da biblioteca de classes C# em processo são compatíveis com os seguintes tipos:

• Azure.Messaging.CloudEvent
• Azure.Messaging.EventGrid
• Newtonsoft.Json.Linq.JObject
• System.String

Extensão v2.x

As funções da biblioteca de classes C# em processo são compatíveis com os seguintes tipos:

• Microsoft.Azure.EventGrid.Models.EventGridEvent
• Newtonsoft.Json.Linq.JObject
• System.String

Funções 1.x

As funções da biblioteca de classes C# em processo são compatíveis com os seguintes tipos:

• Newtonsoft.Json.Linq.JObject
• System.String

Extensão v3.x

Quando você quiser que a função processe um único evento, o gatilho da Grade de Eventos pode ser vinculado aos seguintes tipos:

Type	Descrição
Tipos serializáveis JSON	O Functions tenta desserializar os dados JSON do evento em um tipo de objeto CLR básico simples antigo (POCO).
string	O evento como uma cadeia de caracteres.
BinaryData1	Os bytes da mensagem de evento.
CloudEvent1	O objeto de evento. Use quando a Grade de Eventos estiver configurada para produzir resultados usando o esquema CloudEvents.
EventGridEvent1	O objeto de evento. Use quando a Grade de Eventos estiver configurada para produzir resultados usando o esquema Grade de Eventos.

Quando você quiser que a função processe um lote de eventos, o gatilho da Grade de Eventos pode ser vinculado aos seguintes tipos:

Type	Descrição
CloudEvent[]1, EventGridEvent[]1, string[], BinaryData[]1	Uma matriz de eventos do lote. Cada entrada representa um evento.

¹ Para usar esses tipos, você precisa consultar asMicrosoft.Azure.Functions.Worker.Extensions.EventGrid 3.3.0 ou posterior e as dependências comuns para vinculações de dados do tipo SDK.

Extensão v2.x

Exige que você defina um tipo personalizado ou use uma cadeia de caracteres. Consulte a Seção de exemplo para obter exemplos de como usar um tipo de parâmetro personalizado.

Funções 1.x

A versão 1.x do Functions não dá suporte a processos de trabalho isolados.

A instância de evento da Grade de Eventos está disponível por meio do parâmetro associado ao atributo EventGridTrigger, com o tipo EventSchema.

A instância da Grade de Eventos está disponível por meio do parâmetro configurado na propriedade de name do arquivo function.json.

A instância da Grade de Eventos está disponível por meio do parâmetro configurado na propriedade de name do arquivo function.json, com o tipo func.EventGridEvent.

Esquema do evento

Os dados de uma Grade de Eventos são recebidos como um objeto JSON no corpo de uma solicitação HTTP. O JSON é semelhante ao exemplo a seguir:

[{
  "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. A Grade de Eventos envia sempre uma matriz e pode enviar mais de um evento na matriz. O runtime invoca sua função uma vez para cada elemento da matriz.

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. O exemplo mostrado é para um evento de armazenamento de Blobs.

Para obter explicações sobre as propriedades comuns e específicas de evento, consulte Propriedades do evento na documentação da Grade de Eventos.

Próximas etapas

• Se você tiver dúvidas, envie um problema para a equipe aqui
• Enviar um evento de Grade de Eventos