Hintergrundfunktionen

Eine Hintergrundfunktion ist ein Typ einerereignisgesteuerter Funktion. Sie wird für Node.js, Go, Python und Java unterstützt.

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 wiederholten Anwenden von Hintergrundfunktionen finden Sie unter Ereignisgesteuerte Funktionen wiederholen.

Unterstützende Laufzeiten

Die folgenden Laufzeiten unterstützen Hintergrundfunktionen:

Sprache	Versionen
Node.js	Alle
Python	Alle
Go	Alle
Java	Alle

Hinweis: Wenn Sie eine ereignisgesteuerte Funktion für eine Laufzeit schreiben, die oben nicht aufgeführt ist, finden Sie weitere Informationen unterCloudEvent-Funktionen.

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

functions/helloworld/index.js

Auf GitHub ansehen 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

Auf GitHub ansehen 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

Auf GitHub ansehen 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

Auf GitHub ansehen 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;
  }
}

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

functions/helloworld/index.js

Auf GitHub ansehen Feedback

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

functions/helloworld/main.py

Auf GitHub ansehen 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.

    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

functions/helloworld/hello_cloud_storage.go

Auf GitHub ansehen 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 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

Auf GitHub ansehen Feedback

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.

Hinweis: Die Ereignisdaten werden nicht automatisch protokolliert, da sie möglicherweise vertrauliche Informationen enthalten, die Nutzer nicht in Cloud Logging schreiben möchten. Wenn Sie die Ereignisdaten im Log erfassen möchten, müssen Sie dies explizit tun, wie in Logs schreiben, aufrufen und darauf reagieren beschrieben wird.

Hintergrundfunktionen beenden

Wenn eine Funktion Hintergrundaufgaben erstellt, z. B. Threads, Futures, Promise-Objekte von Node.js, Callbacks oder Systemprozessee, müssen Sie diese Aufgaben beenden oder anderweitig auflösen, bevor Sie von der Funktion zurückkehren. 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.

Hinweis: Weitere Informationen zum Umgang mit Promise-Objekten der Node.js-Laufzeit finden Sie auf der Seite Node.js-Laufzeiten..

Tipp

• Cloud Functions bereitstellen
• Pub/Sub-Triggerfunktionen aufrufen
• Cloud Storage-Triggerfunktionen aufrufen
• Anleitung zu Cloud Functions mit Pub/Sub
• Anleitung zu Cloud Functions mit Cloud Storage