Escribe funciones controladas por eventos

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

Existen dos maneras de implementar las funciones controladas por eventos. La forma que uses depende del entorno de ejecución del lenguaje elegido y de si usas Cloud Functions (1st gen) o Cloud Functions (2nd gen):

Funciones de CloudEvent

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

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

Funciones en segundo plano

Las funciones controladas por eventos en los entornos de ejecución de Node.js, Python, Go y Java de Cloud Functions (1st gen) esperan diferentes argumentos de las funciones de CloudEvent. Este estilo anterior de la función controlada por eventos se denomina función en segundo plano.

En el siguiente ejemplo, se muestra el archivo de origen de una función básica de en segundo plano 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 

// 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, defines y exportas una función que controla los datos de eventos. Cloud Functions pasa tu función de controlador a los siguientes argumentos:

  • eventData: Un objeto que representa la carga útil de datos de eventos. Su formato depende del tipo de evento.
  • context: Un objeto que contiene metadatos sobre el evento.
  • callback: Es una función opcional que puedes llamar para indicar que se completó la operación. El primer argumento para esta devolución de llamada se interpreta como una señal de un error. No pases argumentos ni un primer argumento null para indicar que se realizó de forma correcta.

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, defines una función que controla los datos de eventos. Cloud Functions pasa tu función de controlador a los siguientes argumentos:

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

El punto de entrada de la función es el nombre de la función del 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 controla los datos de eventos. Cloud Functions pasa tu función de controlador a los siguientes argumentos:

  • ctx: Un objeto context.Context que contiene metadatos sobre el evento. Puedes recuperar los metadatos mediante el paquete cloud.google.com/go/functions/metadata.
  • e: Un objeto que representa la carga útil de datos de eventos. Su tipo, que se muestra en el ejemplo anterior como EventDataType, debe ser un struct correspondiente al tipo de evento que maneja la función. La carga útil de datos de eventos se desmarca en el struct 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, debes usar la API de Functions Framework para Java a fin de implementar una clase de controlador de eventos con la interfaz BackgroundFunction<T>. El método accept() acepta como argumentos la carga útil de datos de eventos y un objeto Context que contiene metadatos sobre el evento.

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

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

Para las funciones en segundo plano, la carga útil de datos de eventos se pasa directamente a tu función en un formato correspondiente al tipo de evento que activa la función. Consulta Activadores admitidos en Cloud Functions (1st gen) para obtener información sobre activadores admitidos, tipos de eventos y formatos de datos de eventos asociados.

Finalización de la función

Cloud 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