Funktionen aus Cloud Storage mit Eventarc auslösen

In dieser Anleitung erfahren Sie, wie Sie mit der Google Cloud CLI eine ereignisgesteuerte Funktion in Cloud Run bereitstellen und Eventarc verwenden, um die Funktion als Reaktion auf Cloud Storage-Ereignisse auszulösen.

Durch Angabe von Filtern für einen Eventarc-Trigger können Sie das Routing von Ereignissen konfigurieren, einschließlich der Ereignisquelle und des Ereignisziels. Im Beispiel in dieser Anleitung wird die Aktualisierung eines Cloud Storage-Bucket das Ereignis auslösen und eine Anfrage in Form einer HTTP-Anfrage an Ihre Funktion gesendet.

Erforderliche Rollen festlegen

Sie oder Ihr Administrator müssen dem Bereitstellerkonto, der Triggeridentität und optional dem Pub/Sub-Dienst-Agent und dem Cloud Storage-Dienst-Agent die folgenden IAM-Rollen zuweisen.

Erforderliche Rollen für das Bereitstellerkonto

  1. Wenn Sie der Projektersteller sind, wird Ihnen die einfache Owner-Rolle (roles/owner) zugewiesen. Standardmäßig enthält diese IAM-Rolle (Identity and Access Management) die Berechtigungen, die für den vollständigen Zugriff auf die meisten Google Cloud-Ressourcen erforderlich sind. Sie können diesen Schritt überspringen.

    Wenn Sie nicht der Project Creator sind, müssen dem entsprechenden Hauptkonto die erforderlichen Berechtigungen für das Projekt erteilt werden. Ein Hauptkonto kann beispielsweise ein Google-Konto (für Endnutzer) oder ein Dienstkonto (für Anwendungen und Computing-Arbeitslasten) sein. Weitere Informationen finden Sie auf der Seite Rollen und Berechtigungen für Ihr Ereignisziel.

    Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Ausführen dieser Anleitung benötigen:

    Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

    Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

    Beachten Sie, dass Cloud Build-Berechtigungen standardmäßig Berechtigungen zum Hochladen und Herunterladen von Artifact Registry-Artefakten enthalten.

Erforderliche Rollen für die Triggeridentität

  1. Notieren Sie sich das Compute Engine Standarddienstkonto, das Sie an einen Eventarc-Trigger anhängen, um die Identität des Triggers zu Testzwecken darzustellen. Dieses Dienstkonto wird automatisch nach der Aktivierung oder Verwendung eines Google Cloud -Dienstes, der Compute Engine verwendet, mit dem folgenden E-Mail-Format erstellt:

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Ersetzen Sie PROJECT_NUMBER durch die Google CloudProjektnummer. Sie finden Ihre Projektnummer auf der Willkommensseite der Google Cloud -Konsole oder durch Ausführen des folgenden Befehls:

    gcloud projects describe PROJECT_ID --format='value(projectNumber)'

    Für Produktionsumgebungen empfehlen wir dringend, ein neues Dienstkonto zu erstellen und ihm eine oder mehrere IAM-Rollen zuzuweisen, die die erforderlichen Mindestberechtigungen enthalten und dem Grundsatz der geringsten Berechtigung folgen.

  2. Standardmäßig können Cloud Run-Dienste nur von Nutzern mit der Rolle „Project Owner“, „Project Editor“, „Cloud Run Admin“ oder „Cloud Run Invoker“ aufgerufen werden. Sie können den Zugriff für einzelne Dienste steuern. Weisen Sie jedoch zu Testzwecken dem Compute Engine-Dienstkonto die Rolle „Cloud Run-Aufrufer” (run.invoker) für das Projekt Google Cloud zu. Dadurch wird die Rolle für alle Cloud Run-Dienste und -Jobs in einem Projekt zugewiesen. 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/run.invoker

    Wenn Sie einen Trigger für einen authentifizierten Cloud Run-Dienst erstellen, ohne die Rolle "Cloud Run Invoker" zuzuweisen, wird der Trigger erfolgreich erstellt und ist aktiv. Der Trigger funktioniert jedoch nicht wie erwartet und in den Logs wird eine Meldung wie die folgende angezeigt:

    The request was not authenticated. Either allow unauthenticated invocations or set the proper Authorization header.
  3. Weisen Sie dem Compute Engine-Standarddienstkonto die Rolle „Eventarc-Ereignisempfänger“ (roles/eventarc.eventReceiver) für das Projekt zu, damit der Eventarc-Trigger Ereignisse vom Ereignisanbieter empfangen kann. 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/eventarc.eventReceiver

Optionale Rolle für den Cloud Storage-Dienst-Agent

  • Bevor Sie einen Trigger für direkte Ereignisse aus Cloud Storage erstellen, weisen Sie dem Cloud Storage-Dienst-Agent die Pub/Sub-Publisher-Rolle (roles/pubsub.publisher) zu:

    SERVICE_ACCOUNT="$(gcloud storage service-agent --project=PROJECT_ID)"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:${SERVICE_ACCOUNT}" \
    --role='roles/pubsub.publisher'

Optionale Rolle für den Pub/Sub-Dienst-Agent

  • Wenn Sie den Cloud Pub/Sub-Dienst-Agent am oder vor dem 8. April 2021 aktiviert haben, um authentifizierte Pub/Sub-Push-Anfragen zu unterstützen, weisen Sie dem von Google verwalteten Dienstkonto die Rolle „Ersteller von Dienstkonto-Tokens“ (roles/iam.serviceAccountTokenCreator) zu. Andernfalls wird diese Rolle standardmäßig zugewiesen: 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountTokenCreator

Cloud Storage-Bucket erstellen

Erstellen Sie einen Cloud Storage-Bucket, der als Ereignisquelle verwendet werden soll:

gcloud storage buckets create -l us-central1 gs://PROJECT_ID-bucket/

Ereignisgesteuerte Funktion schreiben

So schreiben Sie eine ereignisgesteuerte Funktion:

Node.js

  1. Erstellen Sie ein neues Verzeichnis mit dem Namen helloGCS und ersetzen Sie das aktuelle Verzeichnis durch dieses Verzeichnis:

       mkdir helloGCS
   cd helloGCS

  2. Erstellen Sie im Verzeichnis helloGCS eine package.json-Datei, um Node.js-Abhängigkeiten anzugeben:

    {
  "name": "nodejs-docs-samples-functions-v2-storage",
  "version": "0.0.1",
  "private": true,
  "license": "Apache-2.0",
  "author": "Google LLC",
  "repository": {
    "type": "git",
    "url": "https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git"
  },
  "engines": {
    "node": ">=16.0.0"
  },
  "scripts": {
    "test": "c8 mocha -p -j 2 test/*.test.js --timeout=60000"
  },
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0"
  },
  "devDependencies": {
    "c8": "^10.0.0",
    "mocha": "^10.0.0",
    "sinon": "^18.0.0",
    "supertest": "^7.0.0"
  }
}

  3. Erstellen Sie im Verzeichnis helloGCS eine index.js-Datei mit dem folgenden Node.js-Beispiel:

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

// Register a CloudEvent callback with the Functions Framework that will
// be triggered by Cloud Storage.
functions.cloudEvent('helloGCS', cloudEvent => {
  console.log(`Event ID: ${cloudEvent.id}`);
  console.log(`Event Type: ${cloudEvent.type}`);

  const file = cloudEvent.data;
  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

  1. Erstellen Sie ein neues Verzeichnis mit dem Namen helloGCS und ersetzen Sie das aktuelle Verzeichnis durch dieses Verzeichnis:

       mkdir helloGCS
   cd helloGCS

  2. Erstellen Sie im Verzeichnis helloGCS eine requirements.txt-Datei, um Python-Abhängigkeiten anzugeben:

    functions-framework==3.9.2
cloudevents==1.11.0

    Dadurch werden für das Beispiel erforderliche Pakete hinzugefügt.

  3. Erstellen Sie im Verzeichnis helloGCS eine main.py-Datei mit dem folgenden Python-Beispiel:

    from cloudevents.http import CloudEvent

import functions_framework


# Triggered by a change in a storage bucket
@functions_framework.cloud_event
def hello_gcs(cloud_event: CloudEvent) -> tuple:
    """This function is triggered by a change in a storage bucket.

    Args:
        cloud_event: The CloudEvent that triggered this function.
    Returns:
        The event ID, event type, bucket, name, metageneration, and timeCreated.
    """
    data = cloud_event.data

    event_id = cloud_event["id"]
    event_type = cloud_event["type"]

    bucket = data["bucket"]
    name = data["name"]
    metageneration = data["metageneration"]
    timeCreated = data["timeCreated"]
    updated = data["updated"]

    print(f"Event ID: {event_id}")
    print(f"Event type: {event_type}")
    print(f"Bucket: {bucket}")
    print(f"File: {name}")
    print(f"Metageneration: {metageneration}")
    print(f"Created: {timeCreated}")
    print(f"Updated: {updated}")

    return event_id, event_type, bucket, name, metageneration, timeCreated, updated

Ereignisgesteuerte Funktion bereitstellen

Stellen Sie die Funktion mit dem Namen helloworld-events bereit, indem Sie den folgenden Befehl in dem Verzeichnis ausführen, das den Beispielcode enthält:

Node.js 

gcloud run deploy helloworld-events \
      --source . \
      --function helloGCS \
      --base-image BASE_IMAGE \
      --region us-central1

Ersetzen Sie BASE_IMAGE durch die Basis-Image-Umgebung für Ihre Funktion, z. B. nodejs22. Weitere Informationen zu Basis-Images und den in den einzelnen Images enthaltenen Paketen finden Sie unter Unterstützte Sprach-Runtimes und Basis-Images.

Python 

gcloud run deploy helloworld-events \
      --source . \
      --function hello_gcs \
      --base-image BASE_IMAGE \
      --region us-central1

Ersetzen Sie BASE_IMAGE durch die Basis-Image-Umgebung für Ihre Funktion, z. B. python313. Weitere Informationen zu Basis-Images und den in den einzelnen Images enthaltenen Paketen finden Sie unter Unterstützte Sprach-Runtimes und Basis-Images.

Wenn die Bereitstellung abgeschlossen ist, wird in der Google Cloud CLI eine URL angezeigt, unter der Ihr Dienst ausgeführt wird.

Eventarc-Trigger erstellen

Der Eventarc-Trigger sendet Ereignisse aus dem Cloud Storage-Bucket an den Cloud Run-Dienst helloworld-events.

  1. Erstellen Sie einen Trigger, der Cloud Storage-Ereignisse filtert:

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=${REGION} \
    --destination-run-service=helloworld-events  \
    --destination-run-region=${REGION} \
    --event-filters="type=google.cloud.storage.object.v1.finalized" \
    --event-filters="bucket=PROJECT_ID-bucket" \
    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Ersetzen Sie:

    • Ersetzen Sie TRIGGER_NAME durch den Namen des Triggers.
    • PROJECT_ID durch Ihre Google Cloud Projekt-ID.
    • PROJECT_NUMBER durch Ihre Google Cloud Projektnummer.

    Beachten Sie, dass das Erstellen eines Eventarc-Triggers in einem Google Cloud -Projekt möglicherweise zu einer Verzögerung bei der Bereitstellung des Eventarc-Dienst-Agents kommt. Dieses Problem lässt sich normalerweise durch erneutes Erstellen des Triggers beheben. Weitere Informationen finden Sie unter Fehler „Berechtigung verweigert“.

  2. Prüfen Sie, ob der Trigger korrekt erstellt wurde. Der Trigger wird zwar sofort erstellt, es kann jedoch bis zu zwei Minuten dauern, bis ein Trigger vollständig funktioniert.

    gcloud eventarc triggers list --location=${REGION}

    Die Ausgabe sollte in etwa so aussehen:

    NAME: helloworld-events
TYPE: google.cloud.storage.object.v1.finalized
DESTINATION: Cloud Run service: helloworld-events
ACTIVE: Yes
LOCATION: us-central1

Ereignis erstellen und abrufen

Laden Sie eine Textdatei in den Cloud Storage-Bucket hoch, um ein Ereignis zu generieren, das an die Funktion weitergeleitet wird. Die Cloud Run-Funktion protokolliert das Ereignis in den Dienstlogs.

  1. Laden Sie eine Textdatei in Cloud Storage hoch, um ein Ereignis zu generieren:

     echo "Hello World" > random.txt
 gcloud storage cp random.txt gs://PROJECT_ID-bucket/random.txt

    Beim Upload wird ein Ereignis erstellt und die Cloud Run-Funktion loggt die Nachricht des Ereignisses.

  2. So rufen Sie den Logeintrag auf:

    1. Filtern Sie die Logeinträge und geben Sie die Ausgabe im JSON-Format zurück:

      gcloud logging read "resource.labels.service_name=helloworld-events AND textPayload:random.txt" --format=json

    2. Suchen Sie nach einem Logeintrag wie dem folgenden:

      [
  {
   ....
    "resource": {
      "labels": {
        ....
        "location": "us-central1",
        .....
        "service_name": "helloworld-events"
      },
    },
    "textPayload": "File: random.txt",
     .....
  }
]

      Es kann einige Momente dauern, bis Logs angezeigt werden. Wenn Sie sie nicht sofort sehen, versuchen Sie es nach einer Minute noch einmal.

Wenn Sie den Logeintrag sehen, haben Sie erfolgreich eine ereignisgesteuerte Funktion bereitgestellt, die ausgelöst wurde, als eine Textdatei in Cloud Storage hochgeladen wurde.