Gatilho de Grade de Eventos do Azure para o Azure Functions

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

Nota

Os gatilhos de Grade de Eventos não são suportados nativamente em um ASE (Ambiente de Serviço de Aplicativo) do balanceador de carga interno. O gatilho usa uma solicitação HTTP que não pode alcançar o aplicativo de função sem um gateway para a rede virtual.

Importante

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

O Azure Functions suporta dois modelos de programação para Python. A maneira como você define suas ligações depende do modelo de programação escolhido.

v2

O modelo de programação Python v2 permite definir ligações usando decoradores diretamente em seu código de função Python. Para obter mais informações, consulte o guia do desenvolvedor do Python.

v1

O modelo de programação Python v1 requer que você defina ligações em um arquivo function.json separado na pasta de funções. Para obter mais informações, consulte o guia do desenvolvedor do Python.

Este artigo suporta ambos os modelos de programação.

Exemplo

Para obter um exemplo de gatilho HTTP, consulte Receber eventos para um ponto de extremidade HTTP.

O tipo do parâmetro de entrada usado com um gatilho de grade de eventos depende destes três fatores:

• Versão do tempo de execução do Functions
• Versão da extensão de vinculação
• Modalidade da função C#.

Uma função C# pode ser criada usando um dos seguintes modos C#:

• Modelo de trabalho isolado: função C# compilada que é executada em um processo de trabalho isolado do tempo de execução. O processo de trabalho isolado é necessário para suportar funções C# em execução nas versões LTS e não-LTS .NET e .NET Framework. As extensões para funções isoladas do processo de trabalho usam Microsoft.Azure.Functions.Worker.Extensions.* namespaces.
• Modelo em processo: função C# compilada que é executada no mesmo processo que o tempo de execução do Functions. Em uma variação desse modelo, as funções podem ser executadas usando scripts em C#, que são suportados principalmente para edição de portal em C#. As extensões para funções em processo usam Microsoft.Azure.WebJobs.Extensions.* namespaces.

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 total.

Modelo de trabalhador 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 MyEventType classe.

    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 de 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 Functions versão 4.x que usa um CloudEvent parâmetro de ligação:

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 Functions versão 4.x que usa um EventGridEvent parâmetro de ligação:

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 JObject parâmetro de ligação:

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 String
• Gatilho de grade de eventos, parâmetro POJO

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

Gatilho de grade de eventos, parâmetro String

  @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 seguinte POJO, representando as propriedades de nível superior de um evento Event Grid:

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;

}

Após a chegada, a carga JSON do evento é desserializada no EventSchema POJO para uso pela função. Esse processo permite que a função acesse as propriedades do evento de forma orientada a objetos.

  @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 tempo de execução de funções Java, use a EventGridTrigger anotação em parâmetros cujo valor viria da Grade de Eventos. Os parâmetros com essas anotações fazem com que a função seja executada quando um evento chega. Essa anotação pode ser usada com tipos Java nativos, POJOs ou valores anuláveis usando Optional<T>.

Modelo v4

O exemplo a seguir mostra uma função TypeScript de gatilho 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 gatilho 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 ligação de gatilho em um arquivo function.json e uma função JavaScript que usa a ligação.

Aqui estão os dados de ligaçã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 de Grade de Eventos no arquivo function.json .

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

O evento Event Grid é disponibilizado para a função por meio de um parâmetro chamado eventGridEvent, conforme mostrado no exemplo do PowerShell a seguir.

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 ligação de gatilho de Grade de Eventos e uma função Python que usa a ligação. O exemplo depende se você usa o modelo de programação Python v1 ou v2.

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 ligaçã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# do processo de trabalho em processo e isoladas usam o atributo EventGridTrigger. Em vez disso, o script C# usa um arquivo de configuração function.json, conforme descrito no guia de script C#.

Modelo de trabalhador isolado

Aqui está um EventGridTrigger atributo 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 EventGridTrigger atributo 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. Consulte as seções de exemplo e configuração para obter mais detalhes.

Configuração

Modelo v4

O options objeto passado para o método atualmente não suporta nenhuma propriedade para o app.eventGrid() modelo v4.

Modelo v3

A tabela a seguir explica as propriedades de configuração de associação definidas no arquivo function.json .

Property	Descrição
type	Obrigatório - deve ser definido como eventGridTrigger.
direção	Obrigatório - deve ser definido como in.
Designação	Obrigatório - o nome da variável usada no código de função para o parâmetro que recebe os dados do evento.

Configuração

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

function.json propriedade	Description
type	Obrigatório - deve ser definido como eventGridTrigger.
direção	Obrigatório - deve ser definido como in.
Designação	Obrigatório - o nome da variável usada no código de função para o parâmetro que recebe os dados do evento.

Consulte a seção Exemplo para obter exemplos completos.

Utilização

O gatilho de Grade de Eventos usa uma solicitação HTTP de webhook, que pode ser configurada usando as mesmas configurações de host.json que o Gatilho HTTP.

O tipo de parâmetro suportado pelo gatilho Event Grid depende da versão de tempo de execução do Functions, da versão do pacote de extensão e da modalidade C# usada.

Extensão v3.x

As funções da biblioteca de classes C# em processo suportam 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 suportam 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 suportam os seguintes tipos:

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

Extensão v3.x

Quando você deseja que a função processe um único evento, o gatilho Grade de Eventos pode se vincular aos seguintes tipos:

Tipo	Description
Tipos serializáveis JSON	Functions tenta desserializar os dados JSON do evento em um tipo de objeto CLR (POCO) simples.
string	O evento como uma cadeia de caracteres.
BinaryData1	Os bytes da mensagem do evento.
CloudEvent1	O objeto do evento. Use quando a Grade de Eventos estiver configurada para entrega usando o esquema CloudEvents.
EventGridEvent1	O objeto do evento. Use quando a Grade de Eventos estiver configurada para entregar usando o esquema de Grade de Eventos.

Quando você deseja que a função processe um lote de eventos, o gatilho Grade de Eventos pode se vincular aos seguintes tipos:

Tipo	Description
CloudEvent[]1º, EventGridEvent[]1º, string[], BinaryData[]1	Uma matriz de eventos do lote. Cada entrada representa um evento.

1 Para usar esses tipos, você precisa fazer referência a Microsoft.Azure.Functions.Worker.Extensions.EventGrid 3.3.0 ou posterior e às dependências comuns para associações de tipo SDK.

Extensão v2.x

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

Funções 1.x

O Functions versão 1.x não suporta o processo de trabalho isolado.

A instância do evento Event Grid está disponível por meio do parâmetro associado ao atributo, digitado EventGridTrigger como um EventSchemaarquivo .

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

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

Esquema de eventos

Os dados de um evento de 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 sempre envia uma matriz e pode enviar mais de um evento na matriz. O tempo de execução invoca sua função uma vez para cada elemento da matriz.

As propriedades de nível superior nos dados JSON do evento são as mesmas entre todos os tipos de evento, enquanto o data conteúdo da propriedade é específico para cada tipo de evento. O exemplo mostrado é para um evento de armazenamento de blob.

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

Próximos passos

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