Desencadenador de Azure Event Grid para Azure Functions

Use el desencadenador de funciones para responder a un evento enviado por un origen de Event Grid. Debe tener una suscripción de eventos al origen para recibir eventos. Para obtener información sobre cómo crear una suscripción de eventos, consulte Creación de una suscripción. Para obtener información sobre la instalación y configuración de enlaces, consulte la información general.

Nota

No se admiten de forma nativa desencadenadores de Event Grid en un equilibrador de carga interno de App Service Environment (ASE). El desencadenador usa una solicitud HTTP que no puede acceder a la aplicación de funciones sin una puerta de enlace en la red virtual.

Importante

En este artículo se usan pestañas para admitir varias versiones del modelo de programación de Node.js. El modelo v4 está disponible de forma general y está diseñado para que los desarrolladores de JavaScript y TypeScript tengan una experiencia más flexible e intuitiva. Para más detalles acerca de cómo funciona el modelo v4, consulte la Guía para desarrolladores de Node.js de Azure Functions. Para obtener más información acerca de las diferencias entre v3 y v4, consulte la Guía de migración.

Azure Functions admite dos modelos de programación para Python. La forma en que defina los enlaces depende del modelo de programación seleccionado.

El modelo de programación de Python v2 permite definir enlaces mediante decoradores directamente en el código de función de Python. Para más información, consulte la Guía para desarrolladores de Python.

En este artículo se admiten los modelos de programación.

Ejemplo

Para ver un ejemplo de un desencadenador HTTP, consulte Recepción de eventos en un punto de conexión HTTP.

El tipo del parámetro de entrada utilizado con un desencadenador de Event Grid depende de estos tres factores:

  • Versiones del entorno en tiempo de ejecución de Functions
  • Versión de la extensión de enlace
  • Modalidad de la función de C#.

Se puede crear una función C# mediante uno de los siguientes modos de C#:

  • Modelo de trabajo aislado: función compilada en C# que se ejecuta en un proceso trabajador aislado del tiempo de ejecución. Se requiere un proceso de trabajo aislado para admitir funciones de C# ejecutándose en versiones de .NET que son y no son LTS y .NET Framework. Las extensiones para las funciones de proceso de trabajo aisladas usan espacios de nombres Microsoft.Azure.Functions.Worker.Extensions.*.
  • Modelo en curso: función C# compilada que se ejecuta en el mismo proceso que el tiempo de ejecución de Functions. En una variación de este modelo, Functions se puede ejecutar mediante el scripting de C#, que se admite principalmente para la edición del portal de C#. Las extensiones para funciones en proceso utilizan espacios de nombres Microsoft.Azure.WebJobs.Extensions.*.

Al ejecutar la función de C# en un proceso de trabajo aislado, debe definir un tipo personalizado para las propiedades del evento. En el ejemplo siguiente se define una clase 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; }
    }
}

En el ejemplo siguiente se muestra cómo se usa el tipo personalizado en el desencadenador y en un enlace de salida de Event Grid:

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

En esta sección se incluyen los ejemplos siguientes:

En los siguientes ejemplos, se muestra un enlace de desencadenador de Java que utiliza el enlace y genera un evento. El evento se recibe primero como String y después como POJO.

Desencadenador de Event Grid, parámetro de cadena

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

Desencadenador de Event Grid, parámetro POJO

En este ejemplo se usa el siguiente objeto POJO, que representa las propiedades de nivel superior de un evento de 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;

}

Al llegar, la carga útil JSON del evento se deserializa en el POJO EventSchema para que la función pueda usarla. Este proceso permite que la función obtenga acceso a las propiedades del evento de manera que esté orientada a los 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);
  }

En la biblioteca en tiempo de ejecución de funciones de Java, utilice la anotación EventGridTrigger en los parámetros cuyo valor provendría de Event Grid. Los parámetros con estas anotaciones hacen que la función se ejecuta cuando llega un evento. Esta anotación se puede usar con tipos nativos de Java, POJO o valores que aceptan valores NULL mediante Optional<T>.

En el ejemplo siguiente, se muestra una función TypeScript del desencadenador de Event Grid.

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

En el ejemplo siguiente, se muestra una función JavaScript del desencadenador de Event Grid.

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

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

En el ejemplo siguiente se muestra cómo configurar un enlace de desencadenador de Event Grid en el archivo function.json.

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

El evento de Event Grid se pone a disposición de la función por medio de un parámetro denominado eventGridEvent, como se muestra en el siguiente ejemplo de PowerShell.

param($eventGridEvent, $TriggerMetadata)

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

En el ejemplo siguiente se muestra un enlace de desencadenador de Event Grid y una función de Python que usa el enlace. El ejemplo depende de si usa el modelo de programación de Python v1 o 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)

Atributos

Las bibliotecas de C# en proceso y de proceso de trabajo aislado usan el atributo EventGridTrigger. En su lugar, el script de C# usa un archivo de configuración function.json como se describe en la Guía de scripting de C#.

A continuación, se muestra un atributo EventGridTrigger en una signatura de método:

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

anotaciones

La anotación EventGridTrigger permite configurar mediante declaración un enlace de Event Grid con valores de configuración. Para más información, consulte las secciones Ejemplo y Configuración.

Configuración

El objeto options pasado al método app.eventGrid() actualmente no admite ninguna propiedad para el modelo v4.

Configuración

En la siguiente tabla se explican las propiedades de configuración de enlace que se establecen en el archivo function.json. No hay parámetros de constructor ni propiedades que establecer en el atributo EventGridTrigger.

Propiedad de function.json Descripción
type Requerida: se debe establecer en eventGridTrigger.
direction Requerida: se debe establecer en in.
name Requerido: el nombre de la variable que se utiliza en el código de función para el parámetro que recibe los datos del evento.

Consulte la sección de ejemplos para ver ejemplos completos.

Uso

El desencadenador de Event Grid usa una solicitud HTTP de webhook, que se puede configurar con la misma configuración host.json que el desencadenador HTTP.

El tipo de parámetro admitido por el desencadenador de Event Grid depende de la versión del tiempo de ejecución de Functions, la versión del paquete de extensión y la modalidad de C# utilizada.

Cuando quiera que la función procese un único evento, el desencadenador de Event Grid puede enlazarse a los siguientes tipos:

Tipo Descripción
Tipos serializables con JSON Functions intenta deserializar los datos JSON del evento en un tipo de objeto CLR estándar (POCO).
string El evento como una cadena.
BinaryData1 Bytes del mensaje de evento.
CloudEvent1 El objeto de evento. Usar cuando Event Grid esté configurado para hacer entregas mediante el esquema CloudEvents.
EventGridEvent1 El objeto de evento. Usar cuando Event Grid esté configurado para hacer entregas mediante el esquema de Event Grid.

Cuando quiera que la función procese un lote de eventos, el desencadenador de Event Grid puede enlazarse a los siguientes tipos:

Tipo Descripción
CloudEvent[]1,
EventGridEvent[]1,
string[],
BinaryData[]1
Una matriz de eventos del lote. Cada entrada representa un evento.

1 Para utilizar estos tipos, debe hacer referencia a Microsoft.Azure.Functions.Worker.Extensions.EventGrid 3.3.0 o posterior y a las dependencias comunes para los enlaces de tipo SDK.

La instancia del evento de Event Grid está disponible mediante el parámetro asociado al atributo EventGridTrigger, con el tipo EventSchema.

La instancia de Event Grid está disponible mediante el parámetro configurado en la propiedad name del archivo function.json.

La instancia de Event Grid está disponible mediante el parámetro configurado en la propiedad name del archivo function.json, con el tipo func.EventGridEvent.

Esquema del evento

Los datos para un evento de Event Grid se reciben como un objeto JSON en el cuerpo de una solicitud HTTP. El código JSON es similar al del siguiente ejemplo:

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

El ejemplo que se muestra es una matriz de un elemento. Event Grid siempre envía una matriz y puede enviar más de un evento en la matriz. El entorno en tiempo de ejecución invoca la función una vez para cada elemento de matriz.

Las propiedades de nivel superior en los datos JSON del evento son las mismas entre todos los tipos de eventos, mientras que el contenido de la propiedad data es específico para cada tipo de evento. El ejemplo mostrado es para un evento de almacenamiento de blobs.

Para obtener una explicación de las propiedades comunes y específicas de eventos, consulte Propiedades de evento en la documentación de Event Grid.

Pasos siguientes