Hintergrundfunktionen

Sie verwenden Hintergrundfunktionen, wenn Ihre Cloud Functions-Funktion indirekt als Reaktion auf ein Ereignis, z. B. eine Nachricht auf ein Pub/Sub-Thema, eine Änderung in einem Cloud Storage-Bucket oder ein Firebase-Ereignis, aufgerufen werden soll.

Informationen zum Wiederholen von Hintergrundfunktionen finden Sie unter Hintergrundfunktionen wiederholen.

Verwendungsbeispiel

Die folgenden Beispiele zeigen, wie Ereignisse aus Pub/Sub und Cloud Storage verarbeitet werden. Weitere Informationen zur Verarbeitung von Ereignissen aus verschiedenen Quellen finden Sie unter Cloud Functions aufrufen.

Pub/Sub-Beispiel

Dieses Beispiel zeigt eine Cloud Functions-Funktion, die durch Pub/Sub-Ereignisse ausgelöst wird. Jedes Mal, wenn eine Nachricht in einem Pub/Sub-Thema veröffentlicht wird, wird die Funktion aufgerufen, und eine Begrüßung mit Daten aus der Nachricht wird in das Log geschrieben.

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

Weitere Informationen zur Bereitstellung von Cloud Functions-Funktionen, die von Pub/Sub-Ereignissen ausgelöst werden, finden Sie unter Cloud Pub/Sub-Trigger und Anleitung zu Pub/Sub.

Beispiel für Cloud Storage

Dieses Beispiel zeigt eine Cloud Functions-Funktion, die von Cloud Storage-Ereignissen ausgelöst wird. Die Funktion wird jedes Mal aufgerufen, wenn in einem Cloud Storage-Bucket ein Objekt erstellt wird. Die Änderung wird mit einer Nachricht im Log protokolliert.

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());
  }
}

Weitere Informationen zum Bereitstellen von Cloud Functions-Funktionen, die von Cloud Storage-Ereignissen ausgelöst werden, finden Sie unter Cloud Storage-Trigger und in der Cloud Storage-Anleitung.

Funktionsparameter

Hintergrundfunktionen sind übergebene Argumente, die Daten zu dem Ereignis enthalten, das die Ausführung der Funktion ausgelöst hat. Die Parameter der Hintergrundfunktionen sind nachfolgend beschrieben:

Node.js

In den Node.js-Laufzeiten werden der Funktion die Argumente (data, context, callback) übergeben:

Attribut Beschreibung Typ
data Das Datenobjekt für das Ereignis. Der Typ hängt vom Ereignis ab. Objekt
context Das Kontextobjekt für das Ereignis. Objekt
context.eventId Eine eindeutige ID für das Ereignis. Beispiel: "70172329041928" String
context.timestamp Datum/Uhrzeit, zu der das Ereignis erstellt wurde. Beispiel: "2018-04-09T07:56:12.975Z". String (ISO 8601)
context.eventType Der Typ des Ereignisses. Beispiel: "google.pubsub.topic.publish". String
context.resource Die Ressource, von der das Ereignis stammt. Objekt
callback

Ein Callback, um das Ende der Funktionsausführung zu signalisieren. Folgt der "errback"-Konvention, die das erste Argument als Fehler interpretiert:


callback();                    // Success
callback(null, 'Success!');    // Success
callback(1);                   // Error
callback(new Error('Failed')); // Error
Funktion

Python

In der Python-Laufzeit werden der Funktion die Argumente (data, context) übergeben:

Attribut Beschreibung Typ
data Ein Wörterbuch mit den Daten für das Ereignis. Das Format hängt vom Ereignis ab. Cloud Storage-Objekt oder PubsubMessage
context Das Kontextobjekt für das Ereignis. Kontext
context.event_id Eine eindeutige ID für das Ereignis. Beispiel: "70172329041928" String
context.timestamp Datum/Uhrzeit, zu der das Ereignis erstellt wurde. Beispiel: "2018-04-09T07:56:12.975Z". String (ISO 8601)
context.event_type Der Typ des Ereignisses. Beispiel: "google.pubsub.topic.publish". String
context.resource Die Ressource, von der das Ereignis stammt. String

Go

In der Go-Laufzeit werden der Funktion die Argumente (ctx, Event) übergeben:

Attribut Beschreibung Typ
ctx Ein Wert context.Context, der Metadaten zum Ereignis enthält. Sie können die Metadaten mit dem Paket cloud.google.com/go/functions/metadata abrufen. context.Context
Event

Ein struct, dessen Typ Sie definieren. Für die Ereignisnutzlast wird damit über json.Unmarshal() ein Unmarshalling ausgeführt. Die Ereignisnutzlast hängt vom Trigger ab, für den die Funktion registriert wurde.

Die struct-Definition, die Sie in Ihrem Code angeben, muss der Struktur des Ereignistyps entsprechen. Die Struktur für jedes Ereignis wird auf der Übersichtsseite der Trigger für das entsprechende Ereignis dokumentiert.

Beachten Sie, dass Sie mit Ihrem struct nicht jedes in der Nutzlast enthaltene Feld definieren müssen. Wenn Sie in der Funktion nur bestimmte Felder verwenden möchten, müssen Sie im struct auch nur diese Felder definieren. Sie können ein Feld auch mithilfe von JSON-Tags umbenennen, z. B. wenn der Name des JSON-Felds einen Unterstrich enthält.

Benutzerdefinierter struct

Java

In der Java-Laufzeit werden der Funktion die Parameter (event, context) übergeben. Es gibt zwei Arten von Hintergrundfunktionen: BackgroundFunction<T> und RawBackgroundFunction.

Attribut Beschreibung Typ
event Die Nutzlast des Ereignisses. Der Inhalt der Nutzlast hängt vom Trigger ab, für den die Funktion registriert wurde.

Für BackgroundFunction<T> lautet der Typ dieses Parameters T, was eine benutzerdefinierte Klasse ist. Die JSON-Nutzlast des Ereignisses wird mithilfe von Gson.fromJson in eine Instanz dieser Klasse deserialisiert.

Für RawBackgroundFunction lautet der Typ dieses Parameters String und ist die JSON-Nutzlast des Ereignisses.
Benutzerdefiniert oder String
context Ein schreibgeschütztes Context-Objekt, das Metadaten zum Ereignis enthält. Context

Die Ereignisdaten hängen vom Trigger ab, für den die Funktion registriert wurde, z. B. Pub/Sub oder Cloud Storage. Bei direkt ausgelösten Funktionen, die mit dem Befehl gcloud functions call ausgelöst wurden, enthalten die Ereignisdaten die Nachricht, die Sie direkt gesendet haben.

Hintergrundfunktionen beenden

Wenn eine Funktion Hintergrundaufgaben erstellt (z. B. Threads, Futures, Promises, Callbacks oder Systemprozesse), müssen Sie diese Aufgaben vor dem Zurückkehren von der Funktion beenden oder anderweitig auflösen. Aufgaben, die vor dem Zurückkehren von einer bestimmten Ausführung nicht beendet wurden, werden möglicherweise nicht abgeschlossen und können außerdem ein nicht definiertes Verhalten verursachen.

Mit Node.js-Laufzeiten können Ihre Funktionen Verweise auf laufende Aufgaben bereitstellen und Cloud Functions auffordern, auf diese zu warten. Dies kann auf eine der folgenden Arten geschehen:

  • Zurückgeben eines Promise, das aufgelöst wird, sobald die Funktion abgeschlossen ist
  • Nach dem Abschluss: Aufrufen des Arguments callback in einer Callback-Funktion

Weitere Informationen