Ereignisgesteuerte Funktionen schreiben

In Cloud Functions verwenden Sie ereignisgesteuerte Funktionen, wenn eine Funktion automatisch als Reaktion auf ein Ereignis, das in Ihrer Cloudumgebung passiert, aufgerufen werden soll.

Es gibt zwei Möglichkeiten, ereignisgesteuerte Funktionen zu implementieren. Welchen Weg Sie wählen, hängt von der ausgewählten Sprachlaufzeit ab und davon, ob Sie Cloud Functions (1. Generation) oder Cloud Functions (2. Generation) verwenden:

CloudEvent-Funktionen

CloudEvent-Funktionen basieren auf CloudEvents, einer Branchenstandard-Spezifikation zum Beschreiben von Ereignisdaten auf gemeinsame Weise. Weitere Informationen zur CloudEvents-Spezifikation finden Sie im GitHub-Repository für CloudEvents. Das CloudEvents-Projekt bietet auch eine Reihe von CloudEvents-SDKs, die Ihnen bei der Arbeit mit CloudEvents-Objekten in Ihrem Code helfen.

Das folgende Beispiel zeigt eine einfache Quelldatei der CloudEvent-Funktion für jede Laufzeit. Informationen zur Position Ihres Quellcodes finden Sie unter Quellverzeichnisstruktur.

Node.js 

const functions = require('@google-cloud/functions-framework');

// Register a CloudEvent function with the Functions Framework
functions.cloudEvent('myCloudEventFunction', cloudEvent => {
  // Your code here
  // Access the CloudEvent data payload via cloudEvent.data
});

In Node.js registrieren Sie eine CloudEvent-Handler-Funktion mit dem Functions Framework für Node.js. Die Handler-Funktion muss ein CloudEvent-Objekt als Argument akzeptieren.

Der Funktionseinstiegspunkt ist der Name, mit dem der Handler beim Functions Framework registriert ist. In diesem Beispiel ist der Einstiegspunkt myCloudEventFunction.

Python 

import functions_framework

# Register a CloudEvent function with the Functions Framework
@functions_framework.cloud_event
def my_cloudevent_function(cloud_event):
  # Your code here
  # Access the CloudEvent data payload via cloud_event.data

In Python registrieren Sie eine CloudEvent-Handler-Funktion mit dem Functions Framework für Python. Die Handler-Funktion muss ein CloudEvent-Objekt als Argument akzeptieren.

Der Funktionseinstiegspunkt ist der Name der Handler-Funktion, die bei Functions Framework registriert ist. In diesem Beispiel ist der Einstiegspunkt my_cloudevent_function.

Einfach loslegen (Go) 

package mycloudeventfunction

import (
    "context"

    "github.com/GoogleCloudPlatform/functions-framework-go/functions"
    "github.com/cloudevents/sdk-go/v2/event"
)

func init() {
    // Register a CloudEvent function with the Functions Framework
    functions.CloudEvent("MyCloudEventFunction", myCloudEventFunction)
}

// Function myCloudEventFunction accepts and handles a CloudEvent object
func myCloudEventFunction(ctx context.Context, e event.Event) error {
    // Your code here
    // Access the CloudEvent data payload via e.Data() or e.DataAs(...)

    // Return nil if no error occurred
    return nil
}

In Go registrieren Sie eine CloudEvent-Handler-Funktion mit dem Functions Framework für Go. Ihre Handler-Funktion muss eine CloudEvents event.Event Objekt akzeptieren als Argument.

Der Funktionseinstiegspunkt ist der Name, mit dem der Handler beim Functions Framework registriert ist. In diesem Beispiel ist der Einstiegspunkt MyCloudEventFunction.

Java 

package mycloudeventfunction;

import com.google.cloud.functions.CloudEventsFunction;
import io.cloudevents.CloudEvent;

// Define a class that implements the CloudEventsFunction interface
public class MyCloudEventFunction implements CloudEventsFunction {
  // Implement the accept() method to handle CloudEvents
  @Override
  public void accept(CloudEvent event) {
    // Your code here
    // Access the CloudEvent data payload via event.getData()
    // To get the data payload as a JSON string, use:
    // new String(event.getData().toBytes())
  }
}

In Java verwenden Sie die Functions Framework Java API, um eine CloudEvent-Handler-Klasse mit der Schnittstelle CloudEventsFunction zu implementieren. Die Methode accept() muss ein CloudEvent-Objekt als Argument akzeptieren und jede Verarbeitung für das Ereignis ausführen.

Der Funktionseinstiegspunkt ist der voll qualifizierte Name der CloudEvent-Handler-Klasse, einschließlich des Paketnamens. In diesem Beispiel ist der Einstiegspunkt mycloudeventfunction.MyCloudEventFunction.

C# 

using CloudNative.CloudEvents;
using Google.Cloud.Functions.Framework;
using System.Threading;
using System.Threading.Tasks;

namespace MyProject
{
    // Define a class that implements the ICloudEventFunction<T> interface
    public class MyCloudEventFunction : ICloudEventFunction<CloudEventDataType>
    {
        // Implement the HandleAsync() method to handle CloudEvents
        public Task HandleAsync(CloudEvent cloudEvent, CloudEventDataType data, CancellationToken cancellationToken)
        {
            // Your code here
            // The data argument represents the CloudEvent data payload

            // Signal function completion
            return Task.CompletedTask;
        }
    }
}

In .NET-Laufzeiten verwenden Sie das Functions Framework für .NET, um eine CloudEvent-Handler-Klasse mit der Benutzeroberfläche ICloudEventFunction<T>. Die Methode HandleAsync() akzeptiert ein CloudEvent-Objekt und die zugehörige CloudEvent-Datennutzlast als Argumente.

Der Typ des CloudEvent-Datennutzlastarguments, der im obigen Beispiel als CloudEventDataType gezeigt wird, muss dem Typ des Ereignisses entsprechen, das von der Funktion verarbeitet wird. Die Google CloudEvents .NET-Bibliothek bietet Datentypen für die verschiedenen von Google unterstützten Ereignisse.

Der Funktionseinstiegspunkt ist der vollständig qualifizierte Name der CloudEvent-Handler-Klasse, einschließlich des Namespace. In diesem Beispiel ist der Einstiegspunkt MyProject.MyCloudEventFunction.

Ruby 

require "functions_framework"

# Register a CloudEvent function with the Functions Framework
FunctionsFramework.cloud_event "my_cloudevent_function" do |cloud_event|
  # Your code here
  # Access the CloudEvent data payload via cloud_event.data
end

In Ruby Sie registrieren eine CloudEvent-Handler-Funktion mit dem Functions Framework für Ruby. Die Handler-Funktion muss ein CloudEvents-Objekt Event als Argument akzeptieren.

Der Funktionseinstiegspunkt ist der Name, mit dem der Handler beim Functions Framework registriert ist. In diesem Beispiel ist der Einstiegspunkt my_cloudevent_function.

PHP 

<?php

use CloudEvents\V1\CloudEventInterface;
use Google\CloudFunctions\FunctionsFramework;

// Register a CloudEvent function with the Functions Framework
FunctionsFramework::cloudEvent('myCloudEventFunction', 'myCloudEventHandler');

// Define your CloudEvent handler
function myCloudEventHandler(CloudEventInterface $event): void
{
    // Your code here
    // Access the CloudEvent data payload via $event->getData()
}

In PHP registrieren Sie eine CloudEvent-Handler-Funktion mit dem Functions Framework für PHP. Die Handler-Funktion muss ein Argument akzeptieren, das der Schnittstelle CloudEventInterface entspricht.

Der Funktionseinstiegspunkt ist der Name, mit dem der Handler beim Functions Framework registriert ist. In diesem Beispiel ist der Einstiegspunkt myCloudEventFunction.

Bei CloudEvent-Funktionen werden Ereignisdaten im CloudEvents-Format an Ihre Funktion übergeben, wobei eine CloudEvent-Datennutzlast dem Ereignistyp entspricht, der die Funktion auslöst. Informationen zu unterstützten Triggern, Ereignistypen und zugehörigen Ereignisdatenformaten finden Sie unter Cloud Functions-Trigger.

Das Repository Google Events enthält Ressourcen für die Arbeit mit CloudEvents, die herausgegeben von Google.

Hintergrundfunktionen

Ereignisgesteuerte Funktionen in den Cloud Functions- (1. Generation) Node.js-, Python-, Go- und Java-Laufzeiten erwarten unterschiedliche Argumente von CloudEvent-Funktionen. Diese ältere Art ereignisgesteuerter Funktionen wird als Hintergrundfunktion bezeichnet.

Das folgende Beispiel zeigt eine einfache Quelldatei der Hintergrund-Funktion für jede Laufzeit. Informationen zur Position Ihres Quellcodes finden Sie unter Quellverzeichnisstruktur.

Node.js 

// Define and export an event handler
exports.myBackgroundFunction = (eventData, context, callback) => {
  // Your code here
  // The eventData argument represents the event data payload

  // Optionally signal function completion:
  callback();
};

In Node.js definieren und exportieren Sie eine Funktion, die Ereignisdaten verarbeitet. Cloud Functions übergibt die Handler-Funktion an die folgenden Argumente:

  • eventData: Ein Objekt, das die Ereignisdaten-Nutzlast darstellt. Das Format hängt vom Ereignistyp ab.
  • context: Ein Objekt mit Metadaten zum Ereignis.
  • callback: Eine optionale Funktion, die Sie aufrufen können, um den Abschluss zu signalisieren. Das erste Argument dieses Callbacks wird als Signalisierung eines Fehlers interpretiert. Übergeben Sie keine Argumente oder ein erstes null-Argument, um den Erfolg zu signalisieren.

Der Funktionseinstiegspunkt ist der Name des exportierten Ereignis-Handlers. In diesem Beispiel ist der Einstiegspunkt myBackgroundFunction.

Python 

# Define an event handler
def my_background_function(event_data, context):
  # Your code here
  # The event_data argument represents the event data payload

In Python definieren Sie eine Funktion, die Ereignisdaten verarbeitet. Cloud Functions übergibt die Handler-Funktion an die folgenden Argumente:

  • event_data: Ein Wörterbuch, das die Ereignisdaten-Nutzlast darstellt. Das Format hängt vom Ereignistyp ab.
  • context: Ein Objekt mit Metadaten zum Ereignis.

Der Funktionseinstiegspunkt ist der Name der Handler-Funktion. In diesem Beispiel ist der Einstiegspunkt my_background_function.

Einfach loslegen (Go) 

package mybackgroundfunction

import (
    "context"
)

// Function MyBackgroundFunction accepts and handles event data
func MyBackgroundFunction(ctx context.Context, e EventDataType) error {
    // Your code here
    // The argument e represents the event data payload

    // Return nil if no error occurred
    return nil
}

In Go definieren Sie eine exportierte Funktion, die Ereignisdaten verarbeitet. Cloud Functions übergibt die Handler-Funktion an die folgenden Argumente:

  • ctx: Ein context.Context-Objekt, das Metadaten zum Ereignis enthält. Sie können die Metadaten mit dem Paket cloud.google.com/go/functions/metadata abrufen.
  • e: Ein Objekt, das die Ereignisdaten-Nutzlast darstellt. Dessen Typ, im obigen Beispiel gezeigt als EventDataType, muss eine Struktur sein, die dem Ereignistyp entspricht, den die Funktion verarbeitet. Für die Ereignisdatennutzlast wird mit json.Unmarshal() ein Unmarshalling in die Struktur ausgeführt.

Der Funktionseinstiegspunkt ist der Name des exportierten Ereignis-Handlers. In diesem Beispiel ist der Einstiegspunkt MyBackgroundFunction.

Java 

package mybackgroundfunction;

import com.google.cloud.functions.BackgroundFunction;
import com.google.cloud.functions.Context;

// Define a class that implements the BackgroundFunction<T> interface
public class MyBackgroundFunction implements BackgroundFunction<EventDataType> {
  // Implement the accept() method to handle events
  @Override
  public void accept(EventDataType eventData, Context context) {
    // Your code here
    // The eventData argument represents the event data payload
  }
}

In Java verwenden Sie die Functions Framework Java API, um eine Event-Handler-Klasse mit der Schnittstelle BackgroundFunction<T> zu implementieren. Die Methode accept() akzeptiert als Argumente die Nutzlast der Ereignisdaten und ein Context-Objekt mit Metadaten zum Ereignis.

Der Typ des Ereignis-Datennutzlastarguments, der im obigen Beispiel als EventDataType gezeigt wird, muss dem Typ des Ereignisses entsprechen, das von der Funktion verarbeitet wird. Die Ereignisdaten-Nutzlast wird mit Gson.fromJson() in eine Instanz dieser Klasse deserialisiert.

Der Funktionseinstiegspunkt ist der voll qualifizierte Name der Ereignis-Handler-Klasse, einschließlich des Paketnamens. In diesem Beispiel ist der Einstiegspunkt mybackgroundfunction.MyBackgroundFunction.

Bei Hintergrundfunktionen wird die Nutzlast der Ereignisdaten direkt in einem Format an Ihre Funktion übergeben, das dem Ereignistyp entspricht, der die Funktion auslöst. Weitere Informationen zu unterstützten Triggern, Ereignistypen und zugehörigen Ereignisdatenformaten finden Sie unter In Cloud Functions unterstützte Trigger (1. Generation).

Beendigung der Funktion

Cloud Functions betrachtet die ereignisgesteuerte Funktionsausführung als abgeschlossen, wenn die Funktion zurückgibt. Wenn die Funktion Hintergrundaufgaben erstellt (z. B. mit Threads, Futures, JavaScript-Promise-Objekten, -Callbacks oder Systemprozessen), müssen Sie diese Aufgaben beenden oder anderweitig auflösen bevor Sie von Ihrer Funktion zurückgeben. Alle Aufgaben, die vor dem Zurückgeben durch die Funktion nicht beendet wurden, sind möglicherweise nicht abgeschlossen und können ein nicht definiertes Verhalten verursachen.

Automatische Wiederholungsversuche

Ereignisgesteuerte Funktionen können so konfiguriert werden, dass fehlgeschlagene Aufrufe automatisch wiederholt werden. Weitere Informationen finden Sie unter Ereignisgesteuerte Funktionen wiederholen.

Weitere Informationen