Funciones en segundo plano

Utilizas funciones en segundo plano cuando quieres invocar tu función de Cloud Functions indirectamente en respuesta a un evento, como un mensaje en un tema de Pub/Sub, un cambio en un depósito de Cloud Storage o un evento de Firebase.

Para obtener información sobre cómo reintentar funciones en segundo plano, consulta la documentación sobre cómo reintentar las funciones en segundo plano.

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 la documentación sobre cómo llamar a Cloud Functions.

Ejemplo de Pub/Sub

En este ejemplo, se muestra una función de Cloud Functions 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.

Node.js

functions/helloworld/index.js

Ver en GitHub Comentarios

/**
     * Background Cloud Function to be triggered by Pub/Sub.
     * This function is exported by index.js, and executed when
     * the trigger topic receives a message.
     *
     * @param {object} data The event payload.
     * @param {object} context The event metadata.
     */
    exports.helloPubSub = (data, context) => {
      const pubSubMessage = data;
      const name = pubSubMessage.data
        ? Buffer.from(pubSubMessage.data, 'base64').toString()
        : 'World';

      console.log(`Hello, ${name}!`);
    };

Nota: Esta función de muestra usa la firma de funciones en segundo plano de Node.js 8 y superior y no es compatible con el entorno de ejecución de Node.js 6.

Python

functions/helloworld/main.py

Ver en GitHub Comentarios

def hello_pubsub(event, context):
        """Background Cloud Function to be triggered by Pub/Sub.
        Args:
             event (dict):  The dictionary with data specific to this type of
             event. The `data` field contains the PubsubMessage message. The
             `attributes` field will contain custom attributes if there are any.
             context (google.cloud.functions.Context): The Cloud Functions event
             metadata. The `event_id` field contains the Pub/Sub message ID. The
             `timestamp` field contains the publish time.
        """
        import base64

        print("""This Function was triggered by messageId {} published at {}
        """.format(context.event_id, context.timestamp))

        if 'data' in event:
            name = base64.b64decode(event['data']).decode('utf-8')
        else:
            name = 'World'
        print('Hello {}!'.format(name))

Go

functions/helloworld/hello_pubsub.go

Ver en GitHub Comentarios

    // Package helloworld provides a set of Cloud Functions samples.
    package helloworld

    import (
    	"context"
    	"log"
    )

    // PubSubMessage is the payload of a Pub/Sub event.
    type PubSubMessage struct {
    	Data []byte `json:"data"`
    }

    // HelloPubSub consumes a Pub/Sub message.
    func HelloPubSub(ctx context.Context, m PubSubMessage) error {
    	name := string(m.Data)
    	if name == "" {
    		name = "World"
    	}
    	log.Printf("Hello, %s!", name)
    	return nil
    }
    

Para obtener más información sobre la implementación de Cloud Functions activada por eventos de Pub/Sub, consulta los artículos Instructivo de Pub/Sub y Activadores de Pub/Sub.

Ejemplo de Cloud Storage

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

Node.js

functions/helloworld/index.js

Ver en GitHub Comentarios

/**
     * Background Cloud Function to be triggered by Cloud Storage.
     *
     * @param {object} data The event payload.
     * @param {object} context The event metadata.
     */
    exports.helloGCS = (data, context) => {
      const file = data;
      if (file.resourceState === 'not_exists') {
        console.log(`File ${file.name} deleted.`);
      } else if (file.metageneration === '1') {
        // metageneration attribute is updated on metadata changes.
        // on create value is 1
        console.log(`File ${file.name} uploaded.`);
      } else {
        console.log(`File ${file.name} metadata updated.`);
      }
    };

Nota: Esta función de muestra usa la firma de funciones en segundo plano de Node.js 8 y superior y no es compatible con el entorno de ejecución de Node.js 6.

Python

functions/helloworld/main.py

Ver en GitHub Comentarios

def hello_gcs(event, context):
        """Background Cloud Function to be triggered by Cloud Storage.
        Args:
             event (dict): The dictionary with data specific to this type of event.
             context (google.cloud.functions.Context): The Cloud Functions
             event metadata.
        """
        print("File: {}.".format(event['objectId']))

Go

functions/helloworld/hello_cloud_storage.go

Ver en GitHub Comentarios

    // Package helloworld provides a set of Cloud Functions samples.
    package helloworld

    import (
    	"context"
    	"log"
    	"time"
    )

    // GCSEvent is the payload of a GCS event.
    type GCSEvent struct {
    	Kind                    string                 `json:"kind"`
    	ID                      string                 `json:"id"`
    	SelfLink                string                 `json:"selfLink"`
    	Name                    string                 `json:"name"`
    	Bucket                  string                 `json:"bucket"`
    	Generation              string                 `json:"generation"`
    	Metageneration          string                 `json:"metageneration"`
    	ContentType             string                 `json:"contentType"`
    	TimeCreated             time.Time              `json:"timeCreated"`
    	Updated                 time.Time              `json:"updated"`
    	TemporaryHold           bool                   `json:"temporaryHold"`
    	EventBasedHold          bool                   `json:"eventBasedHold"`
    	RetentionExpirationTime time.Time              `json:"retentionExpirationTime"`
    	StorageClass            string                 `json:"storageClass"`
    	TimeStorageClassUpdated time.Time              `json:"timeStorageClassUpdated"`
    	Size                    string                 `json:"size"`
    	MD5Hash                 string                 `json:"md5Hash"`
    	MediaLink               string                 `json:"mediaLink"`
    	ContentEncoding         string                 `json:"contentEncoding"`
    	ContentDisposition      string                 `json:"contentDisposition"`
    	CacheControl            string                 `json:"cacheControl"`
    	Metadata                map[string]interface{} `json:"metadata"`
    	CRC32C                  string                 `json:"crc32c"`
    	ComponentCount          int                    `json:"componentCount"`
    	Etag                    string                 `json:"etag"`
    	CustomerEncryption      struct {
    		EncryptionAlgorithm string `json:"encryptionAlgorithm"`
    		KeySha256           string `json:"keySha256"`
    	}
    	KMSKeyName    string `json:"kmsKeyName"`
    	ResourceState string `json:"resourceState"`
    }

    // HelloGCS consumes a GCS event.
    func HelloGCS(ctx context.Context, e GCSEvent) error {
    	if e.ResourceState == "not_exists" {
    		log.Printf("File %v deleted.", e.Name)
    		return nil
    	}
    	if e.Metageneration == "1" {
    		// The metageneration attribute is updated on metadata changes.
    		// The on create value is 1.
    		log.Printf("File %v created.", e.Name)
    		return nil
    	}
    	log.Printf("File %v metadata updated.", e.Name)
    	return nil
    }
    

Para obtener más información sobre cómo implementar funciones de Cloud Functions activadas por eventos de Cloud Storage, consulta Activadores de Cloud Storage y el Instructivo de Cloud Storage.

Parámetros de las funciones

Las funciones en segundo plano reciben argumentos que poseen datos asociados con el evento que activó la ejecución de la función. Los parámetros de estas funciones en segundo plano se describen a continuación:

Node.js 8 o superior

En la versión 8 del entorno de ejecución de Node.js y superiores, tu función recibe los argumentos (data, context, callback):

Propiedad	Descripción	Tipo
data	El objeto de datos para el evento. Su tipo depende del evento.	Objeto
context	El objeto de contexto del evento.	Objeto
context.eventId	Un ID único para el evento. Por ejemplo: "70172329041928".	String
context.timestamp	La fecha/hora en la que se creó este evento. Por ejemplo: "2018-04-09T07:56:12.975Z".	String (ISO 8601)
context.eventType	El tipo de evento. Por ejemplo: "google.pubsub.topic.publish".	String
context.resource	El recurso que emitió el evento.	Objeto
callback	Una devolución de llamada para indicar que la ejecución de la función se completó. Sigue la convención de "errback" que interpreta el primer argumento como un error. callback(); // Success callback(null, 'Success!'); // Success callback(1); // Error callback(new Error('Failed')); // Error	Función

Node.js 6 (obsoleta)

En el entorno de ejecución de Node.js 6, tu función recibe los argumentos (event, callback):

Propiedad	Descripción	Tipo
event	Un objeto que representa el evento que activó la función.	Objeto
event.data	El objeto de datos para el evento. Su tipo depende del evento.	Objeto
event.context	El objeto de contexto del evento.	Objeto
event.context.eventId	Un ID único para el evento. Por ejemplo: "70172329041928".	String
event.context.timestamp	La fecha/hora en la que se creó este evento. Por ejemplo: "2018-04-09T07:56:12.975Z".	String (ISO 8601)
event.context.eventType	El tipo de evento. Por ejemplo: "google.pubsub.topic.publish".	String
event.context.resource	El recurso que emitió el evento.	String
callback	Una devolución de llamada para indicar que la ejecución de la función se completó. Sigue la convención de "errback" que interpreta el primer argumento como un error. callback(); // Success callback(null, 'Success!'); // Success callback(1); // Error callback(new Error('Failed')); // Error	Función

Python

En el entorno de ejecución de Python, tu función recibe los argumentos (data, context):

Propiedad	Descripción	Tipo
data	Un diccionario que contiene los datos de un evento. Su formato depende del evento.	Objeto de Cloud Storage o PubsubMessage
context	El objeto de contexto del evento.	Contexto
context.event_id	Un ID único para el evento. Por ejemplo: "70172329041928".	String
context.timestamp	La fecha/hora en la que se creó este evento. Por ejemplo: "2018-04-09T07:56:12.975Z".	String (ISO 8601)
context.event_type	El tipo de evento. Por ejemplo: "google.pubsub.topic.publish".	String
context.resource	El recurso que emitió el evento.	String

Go

En el entorno de ejecución de Go, tu función recibe los argumentos (ctx, Event):

Propiedad	Descripción	Tipo
ctx	Un valor context.Context que transporta metadatos sobre el evento. Puedes recuperar los metadatos mediante el paquete cloud.google.com/go/functions/metadata.	context.Context
Event	Un struct que tú defines y en el que se deserializará la carga útil del evento en json.Unmarshal(). La carga útil del evento depende del activador para el cual se registró la función. La definición de struct que proporciones en tu código debe corresponder a la estructura del tipo de evento. La estructura para cada evento se documenta en la página del activador del evento correspondiente. Ten en cuenta que tu struct no es necesario para definir todos los campos contenidos en la carga útil. Quizás solo debes usar ciertos campos en tu función, si ese es el caso, solo necesitas definir esos campos en tu struct. También puedes cambiar el nombre del campo (por ejemplo, cuando el nombre del campo JSON contiene un guion bajo) con etiquetas JSON en ese campo.	struct definido por el usuario

Los datos del evento dependen del activador para el que se registró la función, por ejemplo, Pub/Sub o Cloud Storage. En el caso de funciones que se activaron de forma directa a través del comando gcloud functions call, los datos del evento contienen el mensaje que enviaste directamente.

Nota: Los datos del evento no se registran automáticamente, ya que pueden contener información confidencial que los usuarios no quieren que se escriba en Stackdriver Logging. Si quieres registrar los datos del evento, debes hacerlo de manera explícita, como se describe en la documentación sobre cómo escribir, visualizar y responder a los registros.

Finaliza funciones en segundo plano

Debes indicar cuándo se han completado las funciones en segundo plano. De lo contrario, tu función puede seguir ejecutándose y el sistema podría forzar su finalización. Puedes indicar la finalización de la función en cada entorno de ejecución como se describe a continuación:

Node.js 8 o superior

En la versión 8 y posteriores de los entornos de ejecución de Node.js, indica la finalización de la función mediante:

• Invoca el argumento callback.
• Muestra una promesa.
• Une tu función a través de la palabra clave async (lo que hace que tu función muestre implícitamente una promesa).
• Muestra un valor.

Si invocas el argumento callback o si muestras un valor de forma sincrónica, asegúrate de que todos los procesos asíncronos se hayan completado primero. Si muestras una promesa, Cloud Functions se asegura de que esta se establezca antes de finalizar.

La siguiente función de ejemplo muestra una promesa:

functions/node8/index.js

Ver en GitHub Comentarios

const fetch = require('node-fetch');

    /**
     * Background Cloud Function that returns a Promise. Note that we don't pass
     * a "callback" argument to the function.
     *
     * @param {object} data The Cloud Functions event data.
     * @returns {Promise}
     */
    exports.helloPromise = data => {
      return fetch(data.endpoint);
    };

Node.js 6 (obsoleta)

En el entorno de ejecución de Node.js 6, indica la finalización de la función de alguna de las siguientes formas:

• Invoca el argumento callback.
• Muestra una promesa.
• Muestra un valor.

Si invocas el argumento callback o si muestras un valor de forma sincrónica, asegúrate de que todos los procesos asíncronos se hayan completado primero. Si muestras una promesa, Cloud Functions se asegura de que esta se establezca antes de finalizar.

La siguiente función de ejemplo muestra una promesa:

functions/background/index.js

Ver en GitHub Comentarios

const requestPromiseNative = require('request-promise-native');

    /**
     * Background Cloud Function that returns a Promise. Note that we don't pass
     * a "callback" argument to the function.
     *
     * @param {object} event The Cloud Functions event.
     * @param {object} event.data The event data.
     * @returns {Promise}
     */
    exports.helloPromise = event => {
      return requestPromiseNative({
        uri: event.data.endpoint,
      });
    };

Python

En el entorno de ejecución de Python, indica la finalización de la función con solo mostrar un valor:

functions/helloworld/main.py

Ver en GitHub Comentarios

def hello_background(event, context):
        """Background Cloud Function.
        Args:
             event (dict): The dictionary with data specific to the given event.
             context (google.cloud.functions.Context): The Cloud Functions event
             metadata.
        """
        if event and 'name' in event:
            name = event['name']
        else:
            name = 'World'
        return 'Hello {}!'.format(name)

Go

En el entorno de ejecución de Go, indica la finalización de la función con solo mostrar un valor:

functions/helloworld/hello_pubsub.go

Ver en GitHub Comentarios

    // Package helloworld provides a set of Cloud Functions samples.
    package helloworld

    import (
    	"context"
    	"log"
    )

    // PubSubMessage is the payload of a Pub/Sub event.
    type PubSubMessage struct {
    	Data []byte `json:"data"`
    }

    // HelloPubSub consumes a Pub/Sub message.
    func HelloPubSub(ctx context.Context, m PubSubMessage) error {
    	name := string(m.Data)
    	if name == "" {
    		name = "World"
    	}
    	log.Printf("Hello, %s!", name)
    	return nil
    }
    

Próximos pasos

• Implementa Cloud Functions.
• Llama a funciones del activador de Pub/Sub.
• Llama a funciones del activador de Cloud Storage.
• Instructivo de Cloud Functions con Pub/Sub.
• Instructivo de Cloud Functions con Cloud Storage.