Funzioni in background

Una funzione in background è un tipo di funzione basata su eventi. È supportata per Node.js, Go, Python e Java.

Utilizza le funzioni in background quando vuoi che la Funzione Cloud venga richiamata indirettamente in risposta a un evento, ad esempio un messaggio su un argomento Pub/Sub, una modifica in un bucket Cloud Storage o un evento Firebase.

Per informazioni su come ritentare le funzioni in background, consulta Riprovare le funzioni basate su eventi.

Supporto dei runtime

I seguenti runtime supportano le funzioni in background:

Lingua	Versioni
Node.js	Tutti
Python	Tutti
Go	Tutti
Java	Tutti

Nota: se stai scrivendo una funzione basata su eventi per un runtime non elencato sopra, consulta la pagina Funzioni CloudEvent.

Esempi di utilizzo

Gli esempi riportati di seguito mostrano come elaborare gli eventi da Pub/Sub e Cloud Storage. Per ulteriori informazioni sulla gestione degli eventi da sorgenti diverse, consulta Chiamata di Cloud Functions.

Esempio di Pub/Sub

Questo esempio mostra una funzione Cloud Functions attivata da eventi Pub/Sub. Ogni volta che un messaggio viene pubblicato in un argomento Pub/Sub, la funzione viene richiamata e un saluto utilizzando i dati derivati dal messaggio viene scritto nel log.

Node.js

Functions/helloworld/index.js

Visualizza su GitHub Feedback

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

Functions/helloworld/main.py

Visualizza su GitHub Feedback

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 `@type` field maps to
                         `type.googleapis.com/google.pubsub.v1.PubsubMessage`.
                        The `data` field maps to the PubsubMessage data
                        in a base64-encoded string. The `attributes` field maps
                        to the PubsubMessage attributes if any is present.
         context (google.cloud.functions.Context): Metadata of triggering event
                        including `event_id` which maps to the PubsubMessage
                        messageId, `timestamp` which maps to the PubsubMessage
                        publishTime, `event_type` which maps to
                        `google.pubsub.topic.publish`, and `resource` which is
                        a dictionary that describes the service API endpoint
                        pubsub.googleapis.com, the triggering topic's name, and
                        the triggering event type
                        `type.googleapis.com/google.pubsub.v1.PubsubMessage`.
    Returns:
        None. The output is written to Cloud Logging.
    """
    import base64

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

    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

Visualizza su GitHub Feedback

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

import (
	"context"
	"log"
)

// PubSubMessage is the payload of a Pub/Sub event.
// See the documentation for more details:
// https://cloud.google.com/pubsub/docs/reference/rest/v1/PubsubMessage
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

Functions/helloworld/hello-pubsub/src/main/java/functions/HelloPubSub.java

Visualizza su GitHub Feedback

import com.google.cloud.functions.BackgroundFunction;
import com.google.cloud.functions.Context;
import com.google.events.cloud.pubsub.v1.Message;
import java.nio.charset.StandardCharsets;
import java.util.Base64;
import java.util.logging.Level;
import java.util.logging.Logger;

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

  @Override
  public void accept(Message 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;
  }
}

Per ulteriori informazioni sul deployment di Cloud Functions attivati da eventi Pub/Sub, consulta gli argomenti Trigger Pub/Sub e Tutorial su Pub/Sub.

Esempio di Cloud Storage

Questo esempio mostra una funzione Cloud Functions attivata da eventi Cloud Storage. Ogni volta che viene creato un oggetto in un bucket Cloud Storage, la funzione viene richiamata e un messaggio sulla modifica viene scritto nel log.

Node.js

Functions/helloworld/index.js

Visualizza su GitHub Feedback

/**
 * Generic background Cloud Function to be triggered by Cloud Storage.
 * This sample works for all Cloud Storage CRUD operations.
 *
 * @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

Functions/helloworld/main.py

Visualizza su GitHub Feedback

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,
       and works for all Cloud Storage CRUD operations.
    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 Cloud 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

Functions/helloworld/hello_cloud_storage.go

Visualizza su GitHub Feedback

// 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(ny) 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

Functions/helloworld/hello-gcs/src/main/java/functions/HelloGcs.java

Visualizza su GitHub Feedback

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

/**
 * Example Cloud Storage-triggered function.
 * This function can process any event from Cloud Storage.
 */
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());
  }
}

Per ulteriori informazioni sul deployment di Cloud Functions attivati dagli eventi di Cloud Storage, consulta i trigger di Cloud Storage e il tutorial su Cloud Storage.

Parametri funzione

Le funzioni in background sono argomenti passati contenenti dati associati all'evento che ha attivato l'esecuzione della funzione. I parametri delle funzioni in background sono descritti di seguito:

Node.js

Nei runtime Node.js, la funzione trasmette gli argomenti (data, context, [callback]):

Proprietà	Descrizione	Tipo
data	L'oggetto dati per l'evento. Il tipo dipende dall'evento.	Oggetto
context	L'oggetto di contesto per l'evento.	Oggetto
context.eventId	Un ID univoco per l'evento. Ad esempio: "70172329041928".	Stringa
context.timestamp	La data e l'ora in cui è stato creato l'evento. Ad esempio: "2018-04-09T07:56:12.975Z".	Stringa (ISO 8601)
context.eventType	Il tipo di evento. Ad esempio: "google.pubsub.topic.publish".	Stringa
context.resource	La risorsa che ha emesso l'evento.	Oggetto
callback	Un callback facoltativo per segnalare il completamento della funzione ritardata. Segue la convenzione "errback" che interpreta il primo argomento come un errore: callback(); // Success callback(null, 'Success!'); // Success callback(1); // Error callback(new Error('Failed')); // Error	Funzione

Python

Nel runtime Python, la funzione trasmette gli argomenti (data, context):

Proprietà	Descrizione	Tipo
data	Un dizionario contenente i dati dell'evento. Il formato dipende dall'evento.	Oggetto Cloud Storage o PubSubMessage
context	L'oggetto di contesto per l'evento.	Context
context.event_id	Un ID univoco per l'evento. Ad esempio: "70172329041928".	Stringa
context.timestamp	La data e l'ora in cui è stato creato l'evento. Ad esempio: "2018-04-09T07:56:12.975Z".	Stringa (ISO 8601)
context.event_type	Il tipo di evento. Ad esempio: "google.pubsub.topic.publish".	Stringa
context.resource	La risorsa che ha emesso l'evento.	Stringa

Go

Nel runtime Go, la funzione trasmette gli argomenti (ctx, Event):

Proprietà	Descrizione	Tipo
ctx	Un valore context.Context che trasporta metadati sull'evento. Puoi recuperare i metadati utilizzando il pacchetto cloud.google.com/go/functions/metadata .	context.Context
Event	Un struct, di cui definisci il tipo di payload dell'evento, per cui verrà ripristinato l'utilizzo json.Unmarshal() . Il payload dell'evento dipende dal trigger per cui è stata registrata la funzione. La definizione di struct che fornisci nel codice deve corrispondere alla struttura del tipo di evento. La struttura di ogni evento è documentata nella pagina dell'attivatore dell'evento corrispondente. Tieni presente che struct non è necessario per definire ogni campo contenuto nel payload. Ti consigliamo di utilizzare solo determinati campi nella funzione, nel qual caso devi definire solo questi campi in struct. Puoi anche rinominare un campo (ad esempio, quando il nome del campo JSON contiene un trattino basso) utilizzando i tag JSON al suo interno.	Definita dall'utente: struct

Java

Nel runtime di Java, la tua funzione passa i parametri (event, context). Esistono due diverse funzioni in background, BackgroundFunction<T> e RawBackgroundFunction:

Proprietà	Descrizione	Tipo
event	Il payload dell'evento. I contenuti del payload dipendono dall'attivatore per cui è stata registrata la funzione. Per BackgroundFunction<T>, il tipo di questo parametro è T, che è una classe definita dall'utente. Il payload JSON dell'evento viene deserializzato in un'istanza di questa classe utilizzando Gson.fromJson. Per RawBackgroundFunction, il tipo di questo parametro è String e rappresenta il payload JSON dell'evento.	Definita dall'utente o String
context	Un oggetto Context di sola lettura che ospita metadati sull'evento.	Context

I dati dell'evento dipendono dall'attivatore per cui è stata registrata la funzione, ad esempio Pub/Sub o Cloud Storage. Nel caso di funzioni attivate direttamente, attivate tramite il comando gcloud functions call, i dati dell'evento contengono il messaggio che hai inviato direttamente.

Nota: i dati degli eventi non vengono registrati automaticamente, poiché potrebbero contenere informazioni riservate che gli utenti non vogliono scrivere in Cloud Logging. Se vuoi registrare i dati dell'evento, devi farlo in modo esplicito, come descritto in Scrittura, visualizzazione e risposta ai log.

Chiusura delle funzioni in background

Se una funzione crea attività in background (come thread, future, oggetti Node.js Promise, callback o processi di sistema), devi terminare o risolvere in altro modo queste attività prima di tornare dalla funzione. Le attività non terminate prima di tornare da una particolare esecuzione potrebbero non essere completate e potrebbero causare comportamenti non definiti.

Nota: per ulteriori informazioni sulla gestione degli oggetti Promise del runtime Node.js, all'interno delle funzioni di background, consulta la pagina dei runtime Node.js.

Passaggi successivi

• Deployment di Funzioni Cloud.
• Chiamata delle funzioni di trigger Pub/Sub.
• Chiamata delle funzioni di trigger di Cloud Storage.
• Tutorial su Cloud Functions con Pub/Sub.
• Tutorial su Cloud Functions con Cloud Storage.