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} message The Pub/Sub message.
 * @param {object} context The event metadata.
 */
exports.helloPubSub = (message, context) => {
  const name = message.data
    ? Buffer.from(message.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) // Automatically decoded from base64.
	if name == "" {
		name = "World"
	}
	log.Printf("Hello, %s!", name)
	return nil
}

Java


import com.google.cloud.functions.BackgroundFunction;
import com.google.cloud.functions.Context;
import functions.eventpojos.PubSubMessage;
import java.nio.charset.StandardCharsets;
import java.util.Base64;
import java.util.logging.Level;
import java.util.logging.Logger;

public class HelloPubSub implements BackgroundFunction<PubSubMessage> {
  private static final Logger logger = Logger.getLogger(HelloPubSub.class.getName());

  @Override
  public void accept(PubSubMessage message, Context context) {
    String name = "world";
    if (message != null && message.getData() != null) {
      name = new String(
          Base64.getDecoder().decode(message.getData().getBytes(StandardCharsets.UTF_8)),
          StandardCharsets.UTF_8);
    }
    logger.info(String.format("Hello %s!", name));
    return;
  }
}

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

/**
 * Generic background Cloud Function to be triggered by Cloud Storage.
 *
 * @param {object} file The Cloud Storage file metadata.
 * @param {object} context The event metadata.
 */
exports.helloGCS = (file, context) => {
  console.log(`  Event: ${context.eventId}`);
  console.log(`  Event Type: ${context.eventType}`);
  console.log(`  Bucket: ${file.bucket}`);
  console.log(`  File: ${file.name}`);
  console.log(`  Metageneration: ${file.metageneration}`);
  console.log(`  Created: ${file.timeCreated}`);
  console.log(`  Updated: ${file.updated}`);
};

Python

def hello_gcs(event, context):
    """Background Cloud Function to be triggered by Cloud Storage.
       This generic function logs relevant data when a file is changed.

    Args:
        event (dict):  The dictionary with data specific to this type of event.
                       The `data` field contains a description of the event in
                       the Cloud Storage `object` format described here:
                       https://cloud.google.com/storage/docs/json_api/v1/objects#resource
        context (google.cloud.functions.Context): Metadata of triggering event.
    Returns:
        None; the output is written to Stackdriver Logging
    """

    print('Event ID: {}'.format(context.event_id))
    print('Event type: {}'.format(context.event_type))
    print('Bucket: {}'.format(event['bucket']))
    print('File: {}'.format(event['name']))
    print('Metageneration: {}'.format(event['metageneration']))
    print('Created: {}'.format(event['timeCreated']))
    print('Updated: {}'.format(event['updated']))

Go


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

import (
	"context"
	"fmt"
	"log"
	"time"

	"cloud.google.com/go/functions/metadata"
)

// 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 {
	meta, err := metadata.FromContext(ctx)
	if err != nil {
		return fmt.Errorf("metadata.FromContext: %v", err)
	}
	log.Printf("Event ID: %v\n", meta.EventID)
	log.Printf("Event type: %v\n", meta.EventType)
	log.Printf("Bucket: %v\n", e.Bucket)
	log.Printf("File: %v\n", e.Name)
	log.Printf("Metageneration: %v\n", e.Metageneration)
	log.Printf("Created: %v\n", e.TimeCreated)
	log.Printf("Updated: %v\n", e.Updated)
	return nil
}

Java

import com.google.cloud.functions.BackgroundFunction;
import com.google.cloud.functions.Context;
import functions.eventpojos.GcsEvent;
import java.util.logging.Logger;

public class HelloGcs implements BackgroundFunction<GcsEvent> {
  private static final Logger logger = Logger.getLogger(HelloGcs.class.getName());

  @Override
  public void accept(GcsEvent event, Context context) {
    logger.info("Event: " + context.eventId());
    logger.info("Event Type: " + context.eventType());
    logger.info("Bucket: " + event.getBucket());
    logger.info("File: " + event.getName());
    logger.info("Metageneration: " + event.getMetageneration());
    logger.info("Created: " + event.getTimeCreated());
    logger.info("Updated: " + event.getUpdated());
  }
}

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

Nos ambientes de execução em Node.js, sua função recebe 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

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

Java

No tempo de execução em Java, sua função recebe os parâmetros (event, context). Há duas variedades de funções em segundo plano, BackgroundFunction<T> e RawBackgroundFunction:

Propriedade Descrição Tipo
event O payload do evento. O conteúdo do payload depende do acionador para que a função foi registrada.

Para BackgroundFunction<T>, o tipo desse parâmetro é T, uma classe definida pelo usuário. O payload JSON do evento é cancelado em uma instância dessa classe usando Gson.fromJson.

Para RawBackgroundFunction, o tipo desse parâmetro é String, além disso ele é o payload JSON do evento.
Definido pelo usuário ou String
context Um objeto Context somente leitura que carrega metadados sobre o evento. Context

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

Se uma função criar tarefas em segundo plano (como linhas de execução, futuros, promessas, callbacks ou processos do sistema), será necessário encerrar ou resolver essas tarefas antes de retornar da função. As tarefas não encerradas antes de retornar de uma determinada execução podem não ser concluídas. Além disso, elas também podem causar um comportamento⁠não definido.

Com os ambientes de execução do Node.js suas funções podem fornecer referências a tarefas em andamento e solicitar que o Cloud Functions aguarde por elas. Há duas formas de fazer isso:

  • Retornar um Promise que é resolvido quando a função é concluída.
  • Invocar o argumento callback em uma função callback depois da conclusão.

A seguir