Google Cloud Storage-Trigger

Cloud Functions verwendet ereignisgesteuerte Funktionen, um Ereignisse aus Ihrer Cloud-Infrastruktur zu verarbeiten. Beispielsweise kann Cloud Functions auf Änderungsbenachrichtigungen aus Google Cloud Storage reagieren. Die Benachrichtigungen können so konfiguriert werden, dass sie als Reaktion auf verschiedene Ereignisse innerhalb eines Buckets eine Antwort auslösen, zum Beispiel das Erstellen, Löschen und Archivieren von Objekten oder die Aktualisierung von Metadaten.

Ereignistypen

Von Cloud Functions-Funktionen verwendete Cloud Storage-Ereignisse basieren auf Cloud Pub/Sub-Benachrichtigungen für Google Cloud Storage und sind im Cloud Storage JSON API-Format verfügbar.

Durch Cloud Storage ausgelöste Funktionen unterstützen vier Triggertypen. Diese Triggertypwerte werden nach der Funktionsbereitstellung verwendet, um festzulegen, welche Cloud Storage-Ereignisse Ihre Funktionen auslösen:

Beispiel für Funktionscode

Die folgende Beispielfunktion protokolliert relevante Daten, wenn ein Ereignis eintritt.

Sie geben den Triggertyp an, wenn Sie die Funktion bereitstellen. Im Bereitstellungsbeispiel unten wird mithilfe der Funktion jedes Mal ein Log erstellt, wenn ein Objekt erstellt wird. Dazu wird der Triggertyp google.storage.object.finalize angegeben.

Eine vollständige Anleitung zum Ausführen dieses Codes finden Sie in der Cloud Storage-Anleitung:

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

C#

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
{
    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

require "functions_framework"

FunctionsFramework.cloud_event "hello_gcs" do |event|
  # 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


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)
{
    $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);
}

Triggertyp bei der Bereitstellung angeben

Mit dem folgenden gcloud-Befehl wird die Funktion mit einem object.finalize-Trigger bereitgestellt.

Node.js

gcloud functions deploy helloGCS \
--runtime nodejs16 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
Mit den folgenden Werten für das Flag --runtime können Sie Ihre bevorzugte Version von Node.js festlegen:
  • nodejs16(empfohlen).
  • nodejs14
  • nodejs12
  • nodejs10

Python

gcloud functions deploy hello_gcs \
--runtime python39 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
Mit den folgenden Werten für das Flag --runtime können Sie Ihre bevorzugte Version von Python festlegen:
  • python39(empfohlen).
  • python38
  • python37

Go

gcloud functions deploy HelloGCS \
--runtime go116 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
Mit diesen Werten für das Flag --runtime können Sie Ihre bevorzugte Version von Go festlegen:
  • go116(empfohlen).
  • go113
  • go111

Java

gcloud functions deploy java-gcs-function \
--entry-point functions.HelloGcs \
--runtime java11 \
--memory 512MB \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize

C#

gcloud functions deploy csharp-gcs-function \
--entry-point HelloGcs.Function \
--runtime dotnet3 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize

Ruby

gcloud functions deploy hello_gcs --runtime ruby27 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
Mit den folgenden Werten für das Flag --runtime können Sie Ihre bevorzugte Version von Ruby festlegen:
  • ruby27(empfohlen).
  • ruby26

PHP

gcloud functions deploy helloGCS --runtime php74 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize

Dabei ist YOUR_TRIGGER_BUCKET_NAME der Name des Cloud Storage-Buckets, den die Funktion beobachten soll.

Objekt finalisieren

Wert des Triggertyps: google.storage.object.finalize

Dieses Ereignis wird gesendet, wenn ein neues Objekt im Bucket erstellt wird (oder ein vorhandenes Objekt überschrieben und eine neue Objektgeneration erstellt wird).

Objekt löschen

Wert des Triggertyps: google.storage.object.delete

Dieses Ereignis wird gesendet, wenn ein Objekt dauerhaft gelöscht wird. Abhängig von der für den Bucket ausgewählten Objektversionierung bedeutet dies:

  • Bei Buckets mit Versionsverwaltung wird das Ereignis nur gesendet, wenn eine Version dauerhaft gelöscht wird (aber nicht, wenn ein Objekt archiviert wird).

  • Bei Buckets ohne Versionsverwaltung wird das Ereignis gesendet, wenn ein Objekt gelöscht oder überschrieben wird.

Objekt archivieren

Wert des Triggertyps: google.storage.object.archive

Dieses Ereignis wird gesendet, wenn eine Live-Version eines Objekts archiviert oder gelöscht wird.

Dieses Ereignis wird nur für Buckets mit Versionsverwaltung gesendet.

Objektmetadaten aktualisieren

Wert des Triggertyps: google.storage.object.metadataUpdate

Dieses Ereignis wird gesendet, wenn die Metadaten eines vorhandenen Objekts geändert werden.

Ereignisstruktur

Daten zu Speicherereignissen werden im object-Format von Cloud Storage gesendet.

Zustellmechanismus für Ereignisse

Ereignisse werden mit Pub/Sub-Benachrichtigungen aus Cloud Storage zugestellt. Ereignisse unterliegen den Zustellungsgarantien von Pub/Sub.

Benachrichtigungslimit

Ein Bucket kann bis zu 10 Benachrichtigungskonfigurationen haben, die zum Auslösen von Benachrichtigungen für ein bestimmtes Ereignis festgelegt sind. Das Einrichten von zu vielen Benachrichtigungen für denselben Bucket kann das Benachrichtigungslimit für den Bucket überschreiten und das Erstellen der Funktion unmöglich machen. Dies wird durch den folgenden Fehler angezeigt:

Cloud Storage bucket ...: Pub/Sub notification limit reached

Wenn Sie das Limit erreicht haben, können Sie eine Funktion erst erstellen, wenn Sie entsprechende Maßnahmen ergriffen haben, z. B. Benachrichtigungen entfernen.

Weitere Informationen zu Kontingenten und Anfragelimits für Cloud Storage

Berechtigungen

Sie benötigen ausreichende Berechtigungen für das Projekt, das die Benachrichtigungen erhalten wird. Achten Sie dabei auf Folgendes:

  1. Rufen Sie die E-Mail-Adresse des Dienst-Agents ab, der mit dem Projekt verknüpft ist, in dem sich Ihr Cloud Storage-Bucket befindet.

  2. Verwenden Sie die E-Mail-Adresse, die Sie im vorherigen Schritt erhalten haben, um dem Dienstkonto die IAM-Rolle pubsub.publisher für das gewünschte Pub/Sub-Thema zuzuweisen.

Pub/Sub-Benachrichtigungen für Cloud Storage konfigurieren

Legacy-Trigger von Cloud Storage

Mit dem unten gezeigten gcloud-Befehl wird eine Funktion bereitgestellt, die von Legacy-Benachrichtigungen über Objektänderungen für einen bestimmten Bucket ausgelöst wird. Im Allgemeinen sind Cloud Pub/Sub-Benachrichtigungen einfacher zu verwenden, flexibler und leistungsfähiger als Änderungsbenachrichtigungen für Objekte. Diese Legacy-Benachrichtigungen werden noch für Legacy-Funktionen unterstützt, die diese Ereignisse verwenden.

gcloud functions deploy YOUR_FUNCTION_NAME \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event providers/cloud.storage/eventTypes/object.change \
FLAGS...
Argument Beschreibung
--trigger-resource NAME Der Name des Cloud Storage-Buckets, den die Funktion auf Änderungen überwacht.
--trigger-event NAME Der Name des Ereignistyps, den die Funktion erhalten möchte. In diesem Fall handelt es sich um das Legacy-Ereignis object.change.
FLAGS... Zusätzliche Flags, die Sie während der Bereitstellung angeben müssen, z. B. --runtime. Eine vollständige Referenz finden Sie in der Dokumentation zu gcloud functions deploy.

Tipp

In der Cloud Storage-Anleitung finden Sie ein Beispiel für die Implementierung einer ereignisgesteuerten Funktion, die von Cloud Storage ausgelöst wird.