Compartilhar via


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.

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.

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

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

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

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

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

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

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.

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)

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

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)
{

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

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

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.

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.

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

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