CloudEvent-Funktionen

Eine Hintergrundfunktion ist ein Typ einer ereignisgesteuerten Funktion. CloudEvent-Funktionen werden indirekt als Antwort auf Ereignisse aufgerufen, z. B. eine Nachricht zu einem Pub/Sub-Thema, eine Änderung in einem Cloud Storage-Bucket oder ein Firebase-Ereignis.

CloudEvent-Funktionen sind konzeptionell ähnlich wie Hintergrundfunktionen. Die zwei Funktionen unterscheiden sich hauptsächlich darin, dass CloudEvent-Funktionen ein Ereignisformat nach Branchenstandard verwenden, das als CloudEvents bezeichnet wird. Ein weiterer Unterschied besteht darin, dass Cloud Functions selbst CloudEvent-Funktionen über HTTP-Anfragen aufruft, die an anderer Stelle reproduziert werden können. Insgesamt bewirken diese Unterschiede, dass CloudEvent-Funktionen nahtlos zwischen Computing-Plattformen verschoben werden können.

Unterstützende Laufzeiten

Die folgenden Laufzeiten unterstützen CloudEvent-Funktionen:

Sprache Version(en)
PHP Beta Alle
C# Beta Alle
Ruby Beta Alle

Funktionsparameter

An CloudEvent-Funktionen wird ein einzelnes cloudEvent-Argument übergeben, das Attribute und Metadaten zu dem Ereignis enthält, das die Ausführung der Funktion ausgelöst hat. Eingehende CloudEvents werden dann mithilfe der Functions Framework-Bibliotheken in die unten gezeigten sprachspezifischen Darstellungen umgewandelt.

C#

Der Parameter cloudEvent wird als CloudEvent-Objekt an die Funktion übergeben. Dieses Objekt enthält die folgenden Attribute:

Attribut Typ Beschreibung
Id String Die eindeutige ID des Ereignisses.
Source Uri Die Google Cloud-Entität, die vom Ereignis betroffen ist, im Format /[SERVICE_DOMAIN_NAME]/[RESOURCE]/.
Type String Der CloudEvent-Typ des empfangenen Ereignisses.
Time Nullwerte zulässig für DateTimeOffset Ein Zeitstempel, der angibt, wann das Ereignis aufgetreten ist.
SpecVersion CloudEventsSpecVersion Die CloudEvents-Spezifikationsversion, die zum Erstellen des Ereignisses verwendet wurde.
Data Object Ein object mit spezifischen Daten gemäß Ereignistyp.
Subject Nullable String (Nullwerte zulässig) Der Wert des Betreffs hängt von der Art des ausgelösten Ereignisses ab. Wenn das zugrunde liegende Ereignis auf ein Cloud Storage-Objekt verweist, wird dieses Attribut auf den Speicherort des Objekts im Format objects/path/to/object festgelegt. Einige Ereignisse legen kein Betreff fest. In diesem Fall ist dieses Attribut null.

Ruby

Der Parameter cloudEvent wird als CloudEvents::Event::V1-Objekt an die Funktion übergeben. Dieses Objekt enthält die folgenden Attribute:

Attribut Typ Beschreibung
cloudEvent.id String Die eindeutige ID des Ereignisses.
cloudEvent.source URI Die Google Cloud-Entität, die vom Ereignis betroffen ist, im Format /[SERVICE_DOMAIN_NAME]/[RESOURCE]/.
cloudEvent.type String Der CloudEvent-Typ des empfangenen Ereignisses.
cloudEvent.time DateTime Ein Zeitstempel, der angibt, wann das Ereignis aufgetreten ist.
cloudEvent.specversion String Die CloudEvents-Spezifikationsversion, die zum Erstellen des Ereignisses verwendet wurde.
cloudEvent.data Hash Ein Hash mit spezifischen Daten gemäß Ereignistyp.
cloudEvent.subject String oder Nil Der Wert des Betreffs hängt von der Art des ausgelösten Ereignisses ab. Wenn das zugrunde liegende Ereignis auf ein Cloud Storage-Objekt verweist, wird dieses Attribut auf den Speicherort des Objekts im Format objects/path/to/object festgelegt. Einige Ereignisse legen kein Betreff fest. In diesem Fall ist dieses Attribut Nil.

PHP

Der Parameter cloudEvent wird als CloudEvent-Objekt an die Funktion übergeben. Dieses Objekt enthält Folgendes:

Funktion Typ Beschreibung
cloudEvent->getId() string Die eindeutige ID des Ereignisses.
cloudEvent->getSource() string Die Google Cloud-Entität, die vom Ereignis betroffen ist, im Format /[SERVICE_DOMAIN_NAME]/[RESOURCE]/.
cloudEvent->getType() string Der CloudEvent-Typ des empfangenen Ereignisses.
cloudEvent->getTime() ?string Ein Zeitstempel, der angibt, wann das Ereignis aufgetreten ist.
cloudEvent->getSpecVersion() string Die CloudEvents-Spezifikationsversion, die zum Erstellen des Ereignisses verwendet wurde.
cloudEvent->getSubject() ?string Der Wert des Betreffs hängt von der Art des ausgelösten Ereignisses ab. Wenn das zugrunde liegende Ereignis auf ein Cloud Storage-Objekt verweist, wird dieses Attribut auf den Speicherort des Objekts im Format objects/path/to/object festgelegt. Einige Ereignisse legen kein Betreff fest. In diesem Fall ist dieses Attribut null.
cloudEvent->getData() Object Ein object mit spezifischen Daten gemäß Ereignistyp.

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 CloudEvent-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.

C#

functions/helloworld/HelloPubSub/Function.cs 
using CloudNative.CloudEvents;
using Google.Cloud.Functions.Framework;
using Google.Events.Protobuf.Cloud.PubSub.V1;
using Microsoft.Extensions.Logging;
using System.Threading;
using System.Threading.Tasks;

namespace HelloPubSub
{
    public class Function : ICloudEventFunction<MessagePublishedData>
    {
        private readonly ILogger _logger;

        public Function(ILogger<Function> logger) =>
            _logger = logger;

        public Task HandleAsync(CloudEvent cloudEvent, MessagePublishedData data, CancellationToken cancellationToken)
        {
            string nameFromMessage = data.Message?.TextData;
            string name = string.IsNullOrEmpty(nameFromMessage) ? "world" : nameFromMessage;
            _logger.LogInformation("Hello {name}", name);
            return Task.CompletedTask;
        }
    }
}

Ruby

functions/helloworld/pubsub/app.rb 
require "functions_framework"
require "base64"

FunctionsFramework.cloud_event "hello_pubsub" do |event|
  # The event parameter is a CloudEvents::Event::V1 object.
  # See https://cloudevents.github.io/sdk-ruby/latest/CloudEvents/Event/V1.html
  name = Base64.decode64 event.data["message"]["data"] rescue "World"

  # A cloud_event function does not return a response, but you can log messages
  # or cause side effects such as sending additional events.
  logger.info "Hello, #{name}!"
end

PHP

functions/helloworld_pubsub/index.php 

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

// Register the function with Functions Framework.
// This enables omitting the `FUNCTIONS_SIGNATURE_TYPE=cloudevent` environment
// variable when deploying. The `FUNCTION_TARGET` environment variable should
// match the first parameter.
FunctionsFramework::cloudEvent('helloworldPubsub', 'helloworldPubsub');

function helloworldPubsub(CloudEventInterface $event): void
{
    $log = fopen(getenv('LOGGER_OUTPUT') ?: 'php://stderr', 'wb');

    $cloudEventData = $event->getData();
    $pubSubData = base64_decode($cloudEventData['message']['data']);

    $name = $pubSubData ? htmlspecialchars($pubSubData) : 'World';
    fwrite($log, "Hello, $name!" . PHP_EOL);
}

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 CloudEvent-Funktion, die durch Cloud Storage-Ereignisse 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.

C#

functions/helloworld/HelloGcs/Function.cs 
using CloudNative.CloudEvents;
using Google.Cloud.Functions.Framework;
using Google.Events.Protobuf.Cloud.Storage.V1;
using Microsoft.Extensions.Logging;
using System.Threading;
using System.Threading.Tasks;

namespace HelloGcs
{
     /// <summary>
     /// Example Cloud Storage-triggered function.
     /// This function can process any event from Cloud Storage.
     /// </summary>
    public class Function : ICloudEventFunction<StorageObjectData>
    {
        private readonly ILogger _logger;

        public Function(ILogger<Function> logger) =>
            _logger = logger;

        public Task HandleAsync(CloudEvent cloudEvent, StorageObjectData data, CancellationToken cancellationToken)
        {
            _logger.LogInformation("Event: {event}", cloudEvent.Id);
            _logger.LogInformation("Event Type: {type}", cloudEvent.Type);
            _logger.LogInformation("Bucket: {bucket}", data.Bucket);
            _logger.LogInformation("File: {file}", data.Name);
            _logger.LogInformation("Metageneration: {metageneration}", data.Metageneration);
            _logger.LogInformation("Created: {created:s}", data.TimeCreated?.ToDateTimeOffset());
            _logger.LogInformation("Updated: {updated:s}", data.Updated?.ToDateTimeOffset());
            return Task.CompletedTask;
        }
    }
}

Ruby

functions/helloworld/storage/app.rb 
require "functions_framework"

FunctionsFramework.cloud_event "hello_gcs" do |event|
  # This function supports all Cloud Storage events.
  # The `event` parameter is a CloudEvents::Event::V1 object.
  # See https://cloudevents.github.io/sdk-ruby/latest/CloudEvents/Event/V1.html
  payload = event.data

  logger.info "Event: #{event.id}"
  logger.info "Event Type: #{event.type}"
  logger.info "Bucket: #{payload['bucket']}"
  logger.info "File: #{payload['name']}"
  logger.info "Metageneration: #{payload['metageneration']}"
  logger.info "Created: #{payload['timeCreated']}"
  logger.info "Updated: #{payload['updated']}"
end

PHP

functions/helloworld_storage/index.php 

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

// Register the function with Functions Framework.
// This enables omitting the `FUNCTIONS_SIGNATURE_TYPE=cloudevent` environment
// variable when deploying. The `FUNCTION_TARGET` environment variable should
// match the first parameter.
FunctionsFramework::cloudEvent('helloGCS', 'helloGCS');

function helloGCS(CloudEventInterface $cloudevent)
{
    // This function supports all Cloud Storage event types.
    $log = fopen(getenv('LOGGER_OUTPUT') ?: 'php://stderr', 'wb');
    $data = $cloudevent->getData();
    fwrite($log, 'Event: ' . $cloudevent->getId() . PHP_EOL);
    fwrite($log, 'Event Type: ' . $cloudevent->getType() . PHP_EOL);
    fwrite($log, 'Bucket: ' . $data['bucket'] . PHP_EOL);
    fwrite($log, 'File: ' . $data['name'] . PHP_EOL);
    fwrite($log, 'Metageneration: ' . $data['metageneration'] . PHP_EOL);
    fwrite($log, 'Created: ' . $data['timeCreated'] . PHP_EOL);
    fwrite($log, 'Updated: ' . $data['updated'] . PHP_EOL);
}

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

Informationen zum Bereitstellen von Ereignissen (auch im CloudEvents-Format) für einen Cloud Run-Zieldienst mit Eventarc finden Sie unter Trigger für Cloud Run erstellen.

Tipps und Tricks

Ereignis-Logging

Ereignisinhalte werden nicht automatisch protokolliert, da sie vertrauliche Informationen enthalten können. Wenn Sie Ereignisinhalte protokollieren möchten, müssen Sie dies explizit wie in Logs schreiben, aufrufen und darauf reagieren beschrieben veranlassen.

CloudEvent-Funktionen beenden

Wenn eine CloudEvent-Funktion Hintergrundaufgaben erstellt, müssen diese Aufgaben ausführt werden, bevor Sie aus der Funktion zurückkehren. So können Sie Fehler und/oder nicht definiertes Verhalten vermeiden.

Automatische Wiederholungsversuche

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

Weitere Informationen