Escribir funciones basadas en eventos

En Cloud Run Functions, se usan funciones basadas en eventos cuando se quiere que una función se invoque automáticamente en respuesta a un evento que se produzca en el entorno de nube.

Hay dos formas de implementar funciones basadas en eventos. La forma de usarlo depende del tiempo de ejecución del lenguaje que elijas:

Funciones de CloudEvent

Las funciones de CloudEvent se basan en CloudEvents, una especificación estándar del sector para describir datos de eventos de forma común. Puedes consultar más información sobre la especificación de CloudEvents en el repositorio de GitHub de CloudEvents. El proyecto CloudEvents también proporciona un conjunto de SDKs de CloudEvents para ayudarte a trabajar con objetos CloudEvents en tu código.

En el siguiente ejemplo se muestra un archivo de origen de función de CloudEvents básico para cada tiempo de ejecución. Consulta la sección Estructura del directorio de origen para obtener información sobre dónde encontrar el código fuente.

C# 

using CloudNative.CloudEvents;
using Google.Cloud.Functions.Framework;
using System.Threading;
using System.Threading.Tasks;

namespace MyProject
{
    // Define a class that implements the ICloudEventFunction<T> interface
    public class MyCloudEventFunction : ICloudEventFunction<CloudEventDataType>
    {
        // Implement the HandleAsync() method to handle CloudEvents
        public Task HandleAsync(CloudEvent cloudEvent, CloudEventDataType data, CancellationToken cancellationToken)
        {
            // Your code here
            // The data argument represents the CloudEvent data payload

            // Signal function completion
            return Task.CompletedTask;
        }
    }
}

En los tiempos de ejecución de .NET, se usa el Functions Framework para .NET para implementar una clase de controlador de CloudEvents con la interfaz ICloudEventFunction<T>. El método HandleAsync() acepta un objeto CloudEvent y la carga útil de datos de CloudEvent asociada como argumentos.

El tipo del argumento de carga útil de datos de CloudEvent, que en el ejemplo anterior se muestra como CloudEventDataType, debe corresponder al tipo de evento que gestiona la función. La biblioteca .NET de Google CloudEvents proporciona tipos de datos para los distintos eventos admitidos por Google.

El punto de entrada de la función es el nombre completo de la clase de controlador de CloudEvent, incluido el espacio de nombres. En este ejemplo, el punto de entrada es MyProject.MyCloudEventFunction.

Ruby 

require "functions_framework"

# Register a CloudEvent function with the Functions Framework
FunctionsFramework.cloud_event "my_cloudevent_function" do |cloud_event|
  # Your code here
  # Access the CloudEvent data payload via cloud_event.data
end

En Ruby, se registra una función de controlador de CloudEvent con el Functions Framework para Ruby. Tu función de controlador debe aceptar un objeto CloudEvents Event como argumento.

El punto de entrada de la función es el nombre con el que el controlador se registra en Functions Framework. En este ejemplo, el punto de entrada es my_cloudevent_function.

PHP 

<?php

use CloudEvents\V1\CloudEventInterface;
use Google\CloudFunctions\FunctionsFramework;

// Register a CloudEvent function with the Functions Framework
FunctionsFramework::cloudEvent('myCloudEventFunction', 'myCloudEventHandler');

// Define your CloudEvent handler
function myCloudEventHandler(CloudEventInterface $event): void
{
    // Your code here
    // Access the CloudEvent data payload via $event->getData()
}

En PHP, se registra una función de controlador de CloudEvents con el framework de funciones de PHP. Tu función de controlador debe aceptar un argumento que cumpla la interfaz CloudEventInterface.

El punto de entrada de la función es el nombre con el que el controlador se registra en Functions Framework. En este ejemplo, el punto de entrada es myCloudEventFunction.

En el caso de las funciones de CloudEvent, los datos de eventos se transfieren a tu función en el formato CloudEvents, con una carga útil de datos de CloudEvent correspondiente al tipo de evento que activa tu función. Consulta la sección Activadores de Cloud Run Functions para obtener información sobre los activadores, los tipos de eventos y los formatos de datos de eventos asociados admitidos.

El repositorio Eventos de Google contiene recursos para trabajar con CloudEvents emitidos por Google.

Funciones en segundo plano

Las funciones basadas en eventos de los tiempos de ejecución de Node.js, Python, Go y Java esperan argumentos diferentes de las funciones de CloudEvents. Este estilo antiguo de función basada en eventos se denomina función en segundo plano.

En el siguiente ejemplo se muestra un archivo de origen de función en segundo plano básico para cada tiempo de ejecución. Consulta la sección Estructura del directorio de origen para obtener información sobre dónde encontrar el código fuente.

Node.js 

// Define and export an event handler
exports.myBackgroundFunction = (eventData, context, callback) => {
  // Your code here
  // The eventData argument represents the event data payload

  // Optionally signal function completion:
  callback();
};

En Node.js, define y exporta una función que gestione los datos de eventos. Cloud Run Functions pasa los siguientes argumentos a tu función de controlador:

  • eventData: objeto que representa la carga útil de datos del evento. Su formato depende del tipo de evento.
  • context: objeto que contiene metadatos sobre el evento.
  • callback: función opcional a la que puedes llamar para indicar que se ha completado. El primer argumento de esta retrollamada se interpreta como una señal de error. No envíes ningún argumento o envía un primer argumento null para indicar que la operación se ha realizado correctamente.

El punto de entrada de la función es el nombre del controlador de eventos exportado. En este ejemplo, el punto de entrada es myBackgroundFunction.

Python 

# Define an event handler
def my_background_function(event_data, context):
  # Your code here
  # The event_data argument represents the event data payload

En Python, se define una función que gestiona los datos de eventos. Cloud Run Functions pasa los siguientes argumentos a tu función de controlador:

  • event_data: un diccionario que representa la carga útil de datos del evento. Su formato depende del tipo de evento.
  • context: objeto que contiene metadatos sobre el evento.

El punto de entrada de la función es el nombre de la función de controlador. En este ejemplo, el punto de entrada es my_background_function.

Go 

package mybackgroundfunction

import (
    "context"
)

// Function MyBackgroundFunction accepts and handles event data
func MyBackgroundFunction(ctx context.Context, e EventDataType) error {
    // Your code here
    // The argument e represents the event data payload

    // Return nil if no error occurred
    return nil
}

En Go, se define una función exportada que gestiona los datos de eventos. Cloud Run Functions pasa los siguientes argumentos a tu función de controlador:

  • ctx: un objeto context.Context que contiene metadatos sobre el evento. Puede obtener los metadatos mediante el paquete cloud.google.com/go/functions/metadata.
  • e: objeto que representa la carga útil de datos del evento. Su tipo, que en el ejemplo anterior es EventDataType, debe ser una estructura correspondiente al tipo de evento que gestiona la función. La carga útil de los datos del evento se deserializa en la estructura mediante json.Unmarshal().

El punto de entrada de la función es el nombre del controlador de eventos exportado. En este ejemplo, el punto de entrada es MyBackgroundFunction.

Java 

package mybackgroundfunction;

import com.google.cloud.functions.BackgroundFunction;
import com.google.cloud.functions.Context;

// Define a class that implements the BackgroundFunction<T> interface
public class MyBackgroundFunction implements BackgroundFunction<EventDataType> {
  // Implement the accept() method to handle events
  @Override
  public void accept(EventDataType eventData, Context context) {
    // Your code here
    // The eventData argument represents the event data payload
  }
}

En Java, se usa la API Java de Functions Framework para implementar una clase de controlador de eventos con la interfaz BackgroundFunction<T>. El método accept() acepta como argumentos la carga útil de datos del evento y un objeto Context que contiene metadatos sobre el evento.

El tipo del argumento de carga útil de datos de evento, que en el ejemplo anterior se muestra como EventDataType, debe corresponder al tipo de evento que gestiona la función. La carga útil de datos de evento se deserializa en una instancia de esta clase mediante Gson.fromJson().

El punto de entrada de la función es el nombre completo de la clase del controlador de eventos, incluido el nombre del paquete. En este ejemplo, el punto de entrada es mybackgroundfunction.MyBackgroundFunction.

En el caso de las funciones en segundo plano, la carga útil de datos de eventos se transfiere directamente a la función en un formato que corresponde al tipo de evento que la activa. Consulta Activadores admitidos en Cloud Functions (1.ª gen.) para obtener información sobre los activadores, los tipos de eventos y los formatos de datos de eventos asociados.

Finalización de la función

Cloud Run Functions considera que la ejecución de una función basada en eventos se ha completado cuando la función devuelve un valor. Si la función crea tareas en segundo plano (como con hilos, futuros, objetos JavaScript Promise, retrollamadas o procesos del sistema), debes finalizar o resolver estas tareas antes de volver de tu función. Es posible que las tareas que no se hayan finalizado antes de que la función devuelva un valor no se completen y provoquen un comportamiento indefinido.

Reintentos automáticos

Las funciones basadas en eventos se pueden configurar para que vuelvan a intentar automáticamente las invocaciones fallidas. Para obtener más información, consulta Reintentar funciones basadas en eventos.

Pasos siguientes