Escribe funciones controladas por eventos

En Cloud Run Functions, usas funciones controladas por eventos cuando deseas que se invoque una función automáticamente en respuesta a un evento que ocurre en tu entorno de nube.

Funciones de CloudEvent

Usas funciones de CloudEvent para invocar tu función.

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

En el siguiente ejemplo, se muestra el archivo de origen de una función básica de CloudEvent para cada entorno de ejecución. Consulta la Estructura del directorio del código fuente para obtener información sobre dónde ubicar el código fuente.

Node.js 

const functions = require('@google-cloud/functions-framework');

// Register a CloudEvent function with the Functions Framework
functions.cloudEvent('myCloudEventFunction', cloudEvent => {
  // Your code here
  // Access the CloudEvent data payload via cloudEvent.data
});

En Node.js, registras una función del controlador de CloudEvent con Functions Framework para Node.js. Tu función de controlador debe aceptar un objeto CloudEvent como argumento.

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

Python 

import functions_framework

# Register a CloudEvent function with the Functions Framework
@functions_framework.cloud_event
def my_cloudevent_function(cloud_event):
  # Your code here
  # Access the CloudEvent data payload via cloud_event.data

En Python, registras una función del controlador de CloudEvent con Functions Framework para Python. Tu función de controlador debe aceptar un objeto CloudEvent como argumento.

El punto de entrada de la función es el nombre de la función del controlador registrada en Functions Framework. En este ejemplo, el punto de entrada es my_cloudevent_function.

Go

package mycloudeventfunction

import (
    "context"

    "github.com/GoogleCloudPlatform/functions-framework-go/functions"
    "github.com/cloudevents/sdk-go/v2/event"
)

func init() {
    // Register a CloudEvent function with the Functions Framework
    functions.CloudEvent("MyCloudEventFunction", myCloudEventFunction)
}

// Function myCloudEventFunction accepts and handles a CloudEvent object
func myCloudEventFunction(ctx context.Context, e event.Event) error {
    // Your code here
    // Access the CloudEvent data payload via e.Data() or e.DataAs(...)

    // Returning an error causes its message to be logged.
    // Example:
    err := myInternalFunction() // may return an error
    if err != nil {
        // Append error message to log
        return err
    }

    // Return nil if no error occurred
    return nil
}

En Go, registras una función del controlador de CloudEvent con Functions Framework para Go. Tu función de controlador debe aceptar un objeto event.Event de CloudEvents como argumento.

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

Java 

package mycloudeventfunction;

import com.google.cloud.functions.CloudEventsFunction;
import io.cloudevents.CloudEvent;

// Define a class that implements the CloudEventsFunction interface
public class MyCloudEventFunction implements CloudEventsFunction {
  // Implement the accept() method to handle CloudEvents
  @Override
  public void accept(CloudEvent event) {
    // Your code here
    // Access the CloudEvent data payload via event.getData()
    // To get the data payload as a JSON string, use:
    // new String(event.getData().toBytes())
  }
}

En Java, usas la API de Functions Framework para Java a fin de implementar una clase de controlador de CloudEvent con la interfaz CloudEventsFunction. El método accept() debe aceptar un objeto CloudEvent como argumento y realizar cualquier procesamiento en el evento.

El punto de entrada de la función es el nombre completamente calificado de la clase de controlador de CloudEvent, incluido el nombre del paquete. En este ejemplo, el punto de entrada es mycloudeventfunction.MyCloudEventFunction.

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 entornos de ejecución de .NET, usas Functions Framework para .NET a fin de implementar una clase de controlador de CloudEvent con la interfaz de ICloudEventFunction<T>. El método HandleAsync() acepta un objeto CloudEvent y la carga útil de datos de CloudEvent asociada como argumentos.

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

El punto de entrada de la función es el nombre completamente calificado 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, registra una función del controlador de CloudEvent con Functions Framework para Ruby. Tu función de controlador debe aceptar un objeto Event de CloudEvents como argumento.

El punto de entrada de la función es el nombre con el que se registra el controlador 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, registra una función de controlador de CloudEvent con Functions Framework para PHP. La función del controlador debe aceptar un argumento que se ajuste a la interfaz CloudEventInterface.

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

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

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

Finalización de la función

Cloud Run Functions considera que la ejecución de la función controlada por eventos se completa cuando la función muestra un resultado. Si la función crea tareas en segundo plano (como subprocesos, futuros, objetos Promise de JavaScript, devoluciones de llamada o procesos del sistema), debes finalizar o resolver estas tareas antes de mostrar un resultado desde tu función. Es posible que no se completen las tareas que no se finalicen antes de que se muestre la función, lo que puede causar un comportamiento indefinido.

Reintentos automáticos

Las funciones controladas por eventos se pueden configurar para reintentar de forma automática las invocaciones con errores. Consulta Reintenta las funciones controladas por eventos para obtener más información.

Próximos pasos