Funciones de CloudEvent

Una función CloudEvent es un tipo de función basada en eventos. Las funciones de CloudEvent son funciones que se invocan de forma indirecta en respuesta a eventos, como un mensaje en un tema de Pub/Sub, un cambio en un bucket de Cloud Storage o un evento de Firebase.

Las funciones de CloudEvent son similares desde una perspectiva conceptual a las funciones en segundo plano. La diferencia principal entre ambos es que las funciones de CloudEvent usan un formato de evento estándar de la industria, conocido como CloudEvents. Otra diferencia es que Cloud Functions invoca las funciones de CloudEvent mediante solicitudes HTTP, que se pueden reproducir en otro lugar. En conjunto, estas diferencias permiten que las funciones de CloudEvent se muevan sin problemas entre las plataformas de procesamiento.

Compatibilidad con los entornos de ejecución

Los siguientes entornos de ejecución son compatibles con las funciones de CloudEvent:

Lenguaje Versiones:
C# Beta Todos
Ruby Beta Todos

Parámetros de las funciones

A las funciones de CloudEvent se les pasa un argumento cloudEvent único que contiene propiedades y metadatos asociados con el evento que activó la ejecución de la función. Luego, los CloudEvents entrantes se convierten en las representaciones específicas del lenguaje que se muestran a continuación mediante las bibliotecas de Functions Framework.

C#

El parámetro cloudEvent se pasa a la función como un objeto CloudEvent que contiene las siguientes propiedades:

Propiedad Tipo Descripción
cloudEvent.Id String El ID único del evento
cloudEvent.Source uri La entidad de Google Cloud afectada por el evento, en el formato /[SERVICE_DOMAIN_NAME]/[RESOURCE]/
cloudEvent.Type String El tipo de CloudEvent del evento recibido
cloudEvent.Time DateTime Una marca de tiempo que indica cuándo ocurrió el evento
cloudEvent.SpecVersion CloudEventsSpecVersion La versión de la especificación de CloudEvents que se usa para crear el evento
cloudEvent.data Object Un object que contiene los datos específicos según el tipo de evento
cloudEvent.subject String que acepta valor NULL Si el evento subyacente hace referencia a un objeto de Cloud Storage, este se configurará en la ubicación del objeto, en el formato objects/path/to/object. Si el evento subyacente no hace referencia a este objeto, esta propiedad será null

Ruby

El parámetro cloudEvent se pasa a la función como un objeto CloudEvents::Event::V1 que contiene las siguientes propiedades:

Propiedad Tipo Descripción
cloudEvent.id String El ID único del evento
cloudEvent.source URI La entidad de Google Cloud afectada por el evento, en el formato /[SERVICE_DOMAIN_NAME]/[RESOURCE]/
cloudEvent.type String El tipo de CloudEvent del evento recibido
cloudEvent.time DateTime Una marca de tiempo que indica cuándo ocurrió el evento
cloudEvent.specversion String La versión de la especificación de CloudEvents que se usa para crear el evento
cloudEvent.data Hash Un Hash que contiene los datos específicos según el tipo de evento
cloudEvent.subject String o Nil Si el evento subyacente hace referencia a un objeto de Cloud Storage, este se configurará en la ubicación del objeto, en el formato objects/path/to/object. Si el evento subyacente no hace referencia a este objeto, esta propiedad será Nil Eventos de Cloud Storage

Ejemplo de uso

En los siguientes ejemplos, se muestra cómo procesar eventos desde Pub/Sub y Cloud Storage. Para obtener más información sobre el control de eventos de diferentes fuentes, consulta Llama a Cloud Functions.

Ejemplo de Pub/Sub

En este ejemplo, se muestra una función de CloudEvent activada por eventos de Pub/Sub. Cada vez que se publica un mensaje en un tema de Pub/Sub, se invoca la función y se escribe en el registro un saludo con datos derivados del mensaje.

C#

functions/helloworld/HelloPubSub/Function.cs 
using CloudNative.CloudEvents;
using Google.Cloud.Functions.Framework;
using Google.Events.Protobuf.Cloud.PubSub.V1;
using Microsoft.Extensions.Logging;
using System.Threading;
using System.Threading.Tasks;

namespace HelloPubSub
{
    public class Function : ICloudEventFunction<MessagePublishedData>
    {
        private readonly ILogger _logger;

        public Function(ILogger<Function> logger) =>
            _logger = logger;

        public Task HandleAsync(CloudEvent cloudEvent, MessagePublishedData data, CancellationToken cancellationToken)
        {
            string nameFromMessage = data.Message?.TextData;
            string name = string.IsNullOrEmpty(nameFromMessage) ? "world" : nameFromMessage;
            _logger.LogInformation("Hello {name}", name);
            return Task.CompletedTask;
        }
    }
}

Ruby

functions/helloworld/pubsub/app.rb 
require "functions_framework"
require "base64"

FunctionsFramework.cloud_event "hello_pubsub" do |event|
  # The event parameter is a CloudEvents::Event::V1 object.
  # See https://cloudevents.github.io/sdk-ruby/latest/CloudEvents/Event/V1.html
  name = Base64.decode64 event.data["message"]["data"] rescue "World"

  # A cloud_event function does not return a response, but you can log messages
  # or cause side effects such as sending additional events.
  logger.info "Hello, #{name}!"
end

Para obtener más información sobre la implementación de funciones de Cloud Functions activadas por eventos de Pub/Sub, consulta Instructivo de Pub/Sub y Activadores de Pub/Sub.

Ejemplo de Cloud Storage

En este ejemplo, se muestra una función de CloudEvent activada por eventos de Cloud Storage. Cada vez que se crea un objeto en un bucket de Cloud Storage, se invoca la función y se escribe en el registro un mensaje sobre el cambio.

C#

functions/helloworld/HelloGcs/Function.cs 
using CloudNative.CloudEvents;
using Google.Cloud.Functions.Framework;
using Google.Events.Protobuf.Cloud.Storage.V1;
using Microsoft.Extensions.Logging;
using System.Threading;
using System.Threading.Tasks;

namespace HelloGcs
{
    public class Function : ICloudEventFunction<StorageObjectData>
    {
        private readonly ILogger _logger;

        public Function(ILogger<Function> logger) =>
            _logger = logger;

        public Task HandleAsync(CloudEvent cloudEvent, StorageObjectData data, CancellationToken cancellationToken)
        {
            _logger.LogInformation("Event: {event}", cloudEvent.Id);
            _logger.LogInformation("Event Type: {type}", cloudEvent.Type);
            _logger.LogInformation("Bucket: {bucket}", data.Bucket);
            _logger.LogInformation("File: {file}", data.Name);
            _logger.LogInformation("Metageneration: {metageneration}", data.Metageneration);
            _logger.LogInformation("Created: {created:s}", data.TimeCreated?.ToDateTimeOffset());
            _logger.LogInformation("Updated: {updated:s}", data.Updated?.ToDateTimeOffset());
            return Task.CompletedTask;
        }
    }
}

Ruby

functions/helloworld/storage/app.rb 
require "functions_framework"

FunctionsFramework.cloud_event "hello_gcs" do |event|
  # The event parameter is a CloudEvents::Event::V1 object.
  # See https://cloudevents.github.io/sdk-ruby/latest/CloudEvents/Event/V1.html
  payload = event.data

  logger.info "Event: #{event.id}"
  logger.info "Event Type: #{event.type}"
  logger.info "Bucket: #{payload['bucket']}"
  logger.info "File: #{payload['name']}"
  logger.info "Metageneration: #{payload['metageneration']}"
  logger.info "Created: #{payload['timeCreated']}"
  logger.info "Updated: #{payload['updated']}"
end

Si deseas obtener más información para implementar funciones de CloudEvent activadas por eventos de Cloud Storage, consulta Activadores de Cloud Storage y el Instructivo de Cloud Storage.

Sugerencias y trucos

Registro de eventos

El contenido de los eventos no se registra de forma automática, ya que puede contener información confidencial. Si deseas registrar el contenido de los eventos, debes hacerlo de forma explícita como se describe en Escribe, visualiza y responde registros.

Finaliza las funciones de CloudEvent

Si una función de CloudEvent crea tareas en segundo plano, debes resolver estas tareas antes de regresar de tu función para evitar errores o comportamientos no definidos.

Reintentos automáticos

Las funciones de CloudEvent 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