Funciones en segundo plano

Usas funciones en segundo plano cuando quieres que tus funciones de Cloud Functions se invoquen indirectamente en respuesta a un evento, como un mensaje en un tema de Google Cloud Pub/Sub, un cambio en un depósito de Google Cloud Storage o un evento de Firebase.

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

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 se describen a continuación:

Node.js 6

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 de Cloud Storage o PubsubMessage
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 del 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

Node.js 8 (Beta)

En el entorno de ejecución de Node.js 8, 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 de Cloud Storage o PubsubMessage
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 del evento. Por ejemplo: "google.pubsub.topic.publish".	String
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 (Beta)

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 del evento. Por ejemplo: "google.pubsub.topic.publish".	String
context.resource	El recurso que emitió el evento.	String

Go (Beta)

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 contiene metadatos sobre el evento. Puedes recuperar los metadatos con el paquete cloud.google.com/go/functions/metadata.	context.Context
Event	Un valor definido por el usuario en el que JSON deserializará la carga útil del evento. La carga útil del evento depende del activador para el cual se registró la función.	Definido por el usuario.

Los contenidos del objeto data del evento dependen del activador para el cual se registró la función, por ejemplo, Cloud Pub/Sub o Cloud Storage. En el caso de las funciones que se activan directamente, esos activadores que usan el 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 Escribe, visualiza y responde 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 6

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 muestras un valor de manera síncrona, 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,
  });
};

La siguiente función de ejemplo no usa llamadas asíncronas, de manera que puede mostrar un valor de manera síncrona:

functions/background/index.js

Ver en GitHub Comentarios

/**
 * Background Cloud Function that returns synchronously. 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.
 */
exports.helloSynchronous = event => {
  // This function returns synchronously
  if (event.data.something === true) {
    return 'Something is true!';
  } else {
    throw new Error('Something was not true!');
  }
};

Node.js 8 (Beta)

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

• Invoca el argumento callback.
• Muestra una promesa.
• Une tu función con la palabra clave async (que hace que tu función muestre una función de manera implícita).
• Muestra un valor.

Si invocas el argumento callback o muestras un valor de manera síncrona, 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);
};

La siguiente función de ejemplo no usa llamadas asíncronas, de manera que puede mostrar un valor de manera síncrona:

functions/node8/index.js

Ver en GitHub Comentarios

/**
 * Background Cloud Function that returns synchronously. Note that we don't pass
 * a "callback" argument to the function.
 *
 * @param {object} data The Cloud Functions event data.
 */
exports.helloSynchronous = data => {
  // This function returns synchronously
  if (data.something === true) {
    return 'Something is true!';
  } else {
    throw new Error('Something was not true!');
  }
};

Python (Beta)

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

Go (Beta)

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 Function samples.
package helloworld

import (
	"context"
	"log"
)

// PubSubMessage is the payload of a Pub/Sub event. Please refer to the docs for
// additional information regarding Pub/Sub events.
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
}

Ejemplo de Cloud Pub/Sub

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

Node.js 6

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} event The Cloud Functions event.
 * @param {function} callback The callback function.
 */
exports.helloPubSub = (event, callback) => {
  const pubsubMessage = event.data;
  const name = pubsubMessage.data
    ? Buffer.from(pubsubMessage.data, 'base64').toString()
    : 'World';

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

  callback();
};

Node.js 8 (Beta)

functions/node8/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}!`);
};

Python (Beta)

functions/helloworld/main.py

Ver en GitHub Comentarios

def hello_pubsub(data, context):
    """Background Cloud Function to be triggered by Pub/Sub.
    Args:
         data (dict): The dictionary with data specific to this type of event.
         context (google.cloud.functions.Context): The Cloud Functions event
         metadata.
    """
    import base64

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

Go (Beta)

functions/helloworld/hello_pubsub.go

Ver en GitHub Comentarios

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

import (
	"context"
	"log"
)

// PubSubMessage is the payload of a Pub/Sub event. Please refer to the docs for
// additional information regarding Pub/Sub events.
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 cómo implementar funciones de Cloud Functions activadas por eventos de Cloud Pub/Sub, consulta Activadores de Google Cloud Pub/Sub, así como el Instructivo de Cloud 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 se escribe en el registro un mensaje sobre el cambio.

Node.js 6

functions/helloworld/index.js

Ver en GitHub Comentarios

/**
 * Background Cloud Function to be triggered by Cloud Storage.
 *
 * @param {object} event The Cloud Functions event.
 * @param {function} callback The callback function.
 */
exports.helloGCS = (event, callback) => {
  const file = event.data;

  if (file.resourceState === 'not_exists') {
    console.log(`File ${file.name} deleted.`);
  } else if (file.metageneration === '1') {
    // metageneration attribute is updated on metadata changes.
    // value is 1 if file was newly created or overwritten
    console.log(`File ${file.name} uploaded.`);
  } else {
    console.log(`File ${file.name} metadata updated.`);
  }

  callback();
};

Node.js 8 (Beta)

functions/node8/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.`);
  }
};

Python (Beta)

functions/helloworld/main.py

Ver en GitHub Comentarios

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

Go (Beta)

functions/helloworld/hello_cloud_storage.go

Ver en GitHub Comentarios

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

import (
	"context"
	"log"
)

// GCSEvent is the payload of a GCS event. Please refer to the docs for
// additional information regarding GCS events.
type GCSEvent struct {
	Bucket         string `json:"bucket"`
	Name           string `json:"name"`
	Metageneration string `json:"metageneration"`
	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, así como el Instructivo de Cloud Storage.

Migra funciones en segundo plano desde Node.js 6 hasta Node.js 8

La firma para las funciones en segundo plano cambió entre los entornos de ejecución de Node.js 6 y Node.js 8. En esta sección, se explica el cambio y se proporciona una guía para migrar funciones en segundo plano existentes que usan el entorno de ejecución Node.js 6.

Una función en segundo plano de ejemplo de Node.js 6 puede tener un aspecto similar al siguiente:

exports.nodeJS6BackgroundFunction = (event, callback) => {
  let data = event.data;
  let context = event.context;
  // ... the rest of your function
};

Ten en cuenta que el argumento event contiene las propiedades data y context. En el entorno de ejecución de Node.js 8, las propiedades data y context se extrajeron del objeto event y ahora se incluyen como parte de la firma de la función:

exports.nodeJS8BackgroundFunction = (data, context, callback) => {
  // ... the rest of your function is unchanged
};

Este cambio simplifica las referencias a los objetos data y context que antes contenía el argumento event. Para obtener más información, consulta Parámetros de funciones en segundo plano.

Próximos pasos

• Implementa Cloud Functions.
• Llama a funciones de activación de Cloud Pub/Sub.
• Llama a funciones de activación de Cloud Storage.
• Instructivo de Cloud Functions con Cloud Pub/Sub.
• Instructivo de Cloud Functions con Cloud Storage.