Funções em segundo plano

Você usa funções em segundo plano para que o Cloud Function seja invocado indiretamente em resposta a um evento, como uma mensagem em um tópico do Pub/Sub, uma alteração em um bucket do Cloud Storage ou um evento do Firebase.

Para ver informações sobre como repetir as funções de segundo plano, consulte Como repetir funções em segundo plano.

Exemplo de uso

Os exemplos abaixo mostram como processar eventos do Pub/Sub e do Cloud Storage. Para ver mais informações sobre como processar eventos de diferentes origens, consulte Como chamar Cloud Functions.

Exemplo do Pub/Sub

Este exemplo mostra um Cloud Function acionado por eventos do Pub/Sub. Toda vez que uma mensagem é publicada em um tópico do Pub/Sub, a função é invocada e uma saudação usando dados derivados da mensagem é gravada no registro.

Node.js

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

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


// 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 ver mais informações sobre como implantar o Cloud Functions acionado por eventos do Pub/Sub, consulte Acionadores do Pub/Sub e Tutorial do Pub/Sub.

Exemplo do Cloud Storage

Neste exemplo, você verá uma função do Cloud acionada por eventos do Cloud Storage. Toda vez que um objeto é criado em um bucket do Cloud Storage, a função é invocada e uma mensagem sobre a alteração é gravada no registro.

Node.js

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

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


// 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 ver mais informações sobre como implantar o Cloud Functions acionado por eventos do Cloud Storage, consulte Acionadores do Cloud Storage e Tutorial do Cloud Storage.

Parâmetros de função

As funções de segundo plano são argumentos transmitidos que contêm dados associados ao evento que acionou a execução da função. Os parâmetros das funções de fundo são descritos abaixo:

Node.js 8+

Nas versões do ambiente de execução do Node.js 8 e posteriores, sua função recebe os argumentos (data, context, callback):

Propriedade Descrição Tipo
data O objeto de dados do evento. O tipo depende do evento. Objeto
context O objeto de contexto do evento. Objeto
context.eventId Um ID exclusivo do evento. Por exemplo, "70172329041928". String
context.timestamp A data/hora em que esse evento foi criado. Por exemplo, "2018-04-09T07:56:12.975Z". String (ISO 8601)
context.eventType O tipo do evento. Por exemplo, "google.pubsub.topic.publish". String
context.resource O recurso que emitiu o evento. Objeto
callback

Um callback para sinalizar a conclusão da execução da função. Segue a convenção "errback", que interpreta o primeiro argumento como um erro:


callback();                    // Success
callback(null, 'Success!');    // Success
callback(1);                   // Error
callback(new Error('Failed')); // Error
Função

Node.js 6 (obsoleto)

No ambiente de execução do Node.js 6, sua função recebe os argumentos (event, callback):

Propriedade Descrição Tipo
event Um objeto que representa o evento que acionou a função. Objeto
event.data O objeto de dados do evento. O tipo depende do evento. Objeto
event.context O objeto de contexto do evento. Objeto
event.context.eventId Um ID exclusivo do evento. Por exemplo, "70172329041928". String
event.context.timestamp A data/hora em que esse evento foi criado. Por exemplo, "2018-04-09T07:56:12.975Z". String (ISO 8601)
event.context.eventType O tipo do evento. Por exemplo, "google.pubsub.topic.publish". String
event.context.resource O recurso que emitiu o evento. String
callback

Um callback para sinalizar a conclusão da execução da função. Segue a convenção "errback", que interpreta o primeiro argumento como um erro:


callback();                    // Success
callback(null, 'Success!');    // Success
callback(1);                   // Error
callback(new Error('Failed')); // Error
Função

Python

No ambiente de execução do Python, sua função recebe os argumentos (data, context):

Propriedade Descrição Tipo
data Um dicionário contendo os dados do evento. O formato depende do evento. Cloud Storage Object ou PubsubMessage
context O objeto de contexto do evento. Contexto
context.event_id Um ID exclusivo do evento. Por exemplo, "70172329041928". String
context.timestamp A data/hora em que esse evento foi criado. Por exemplo, "2018-04-09T07:56:12.975Z". String (ISO 8601)
context.event_type O tipo do evento. Por exemplo, "google.pubsub.topic.publish". String
context.resource O recurso que emitiu o evento. String

Go

No ambiente de execução do Go, sua função recebe os argumentos (ctx, Event):

Propriedade Descrição Tipo
ctx Um valor context.Context que carrega metadados sobre o evento. É possível recuperar os metadados usando o pacote cloud.google.com/go/functions/metadata. context.Context
Event

Um struct, com tipo definido por você, em que o payload do evento terá o marshal cancelado usando json.Unmarshal(). O payload do evento depende do acionador para o qual a função foi registrada.

A definição de struct que você fornece em seu código precisa corresponder à estrutura do tipo de evento. A estrutura de cada evento é documentada na página de acionadores (em inglês) do evento correspondente.

Observe que seu struct não é necessário para definir todos os campos contidos no payload. Caso use apenas determinados campos em sua função, só precisará definir esses campos em seu struct. Também é possível renomear um campo (por exemplo, quando o nome do campo JSON contiver um sublinhado) usando tags JSON nesse campo.

struct definido pelo usuário

Os dados do evento dependem do acionador para o qual a função foi registrada, por exemplo, Pub/Sub ou Cloud Storage. No caso de funções acionadas diretamente, acionadas usando o comando gcloud functions call, os dados do evento contêm a mensagem enviada diretamente.

Como encerrar funções em segundo plano

Você precisa sinalizar a conclusão de funções em segundo plano. Caso contrário, a função pode continuar a ser executada e interrompida automaticamente pelo sistema. É possível sinalizar a conclusão em cada ambiente de execução como descrito abaixo:

Node.js 8+

Nas versões do ambiente de execução do Node.js 8 e posteriores, sinalize a conclusão da função de uma destas maneiras:

  • Invocando o argumento callback.
  • Retornando uma promessa.
  • Encapsulando sua função usando a palavra-chave async (que faz com que a função retorne implicitamente uma promessa).
  • Retornando um valor.

Ao invocar o argumento callback ou retornar um valor de forma síncrona, certifique-se de que todos os processos assíncronos tenham sido concluídos primeiro. Se uma promessa for retornada, o Cloud Functions garantirá que ela seja resolvida antes do encerramento.

O exemplo de função a seguir retorna uma promessa:

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

No ambiente de execução do Node.js 6, sinalize a conclusão da função de uma destas maneiras:

  • Invocando o argumento callback.
  • Retornando uma promessa.
  • Retornando um valor.

Ao invocar o argumento callback ou retornar um valor de forma síncrona, certifique-se de que todos os processos assíncronos tenham sido concluídos primeiro. Se uma promessa for retornada, o Cloud Functions garantirá que ela seja resolvida antes do encerramento.

O exemplo de função a seguir retorna uma promessa:

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

No ambiente de execução do Python, sinalize a conclusão da função de uma destas maneiras:

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

No ambiente de execução do Go, sinalize a conclusão da função retornando um valor:


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

A seguir