Funktionen aus Cloud Storage mit Eventarc auslösen

---

Vorschau — Cloud Run functions

Diese Funktion unterliegt den „Nutzungsbedingungen für Pre-GA-Angebote“ im Abschnitt „Allgemeine Nutzungsbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA-Funktionen sind „wie besehen“ verfügbar und werden möglicherweise nur eingeschränkt unterstützt. Weitere Informationen finden Sie in den Beschreibungen der Startphase.

In dieser Anleitung erfahren Sie, wie Sie eine ereignisgesteuerte Funktion in Cloud Run bereitstellen und mit Eventarc die Funktion über die Google Cloud CLI als Reaktion auf Cloud Storage-Ereignisse auslö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 das Ereignis durch eine Aktualisierung eines Cloud Storage-Buckets ausgelöst und eine Anfrage in Form einer HTTP-Anfrage an Ihre Funktion gesendet.

Ziele

In dieser Anleitung wird Folgendes beschrieben:

1. Cloud Storage-Bucket als Ereignisquelle erstellen.
2. Ereignisgesteuerte Funktion bereitstellen
3. Eventarc-Trigger erstellen.
4. Die Funktion durch Hochladen einer Datei in Cloud Storage auslösen.

Kosten

In diesem Dokument verwenden Sie die folgenden kostenpflichtigen Komponenten von Google Cloud:

• Artifact Registry
• Cloud Build
• Cloud Run
• Cloud Storage
• Eventarc

Mit dem Preisrechner können Sie eine Kostenschätzung für Ihre voraussichtliche Nutzung vornehmen. Neuen Google Cloud-Nutzern steht möglicherweise eine kostenlose Testversion zur Verfügung.

Vorbereitung

Von Ihrer Organisation definierte Sicherheitsbeschränkungen verhindern möglicherweise, dass die folgenden Schritte ausgeführt werden. Informationen zur Fehlerbehebung finden Sie unter Anwendungen in einer eingeschränkten Google Cloud-Umgebung entwickeln.

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
2. Install the Google Cloud CLI.

3. To initialize the gcloud CLI, run the following command:

   gcloud init

4. Create or select a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   • Create a Google Cloud project:

     gcloud projects create PROJECT_ID

     Replace PROJECT_ID with a name for the Google Cloud project you are creating.

   • Select the Google Cloud project that you created:

     gcloud config set project PROJECT_ID

     Replace PROJECT_ID with your Google Cloud project name.

5. Make sure that billing is enabled for your Google Cloud project.

6. Install the Google Cloud CLI.

7. To initialize the gcloud CLI, run the following command:

   gcloud init

8. Create or select a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   • Create a Google Cloud project:

     gcloud projects create PROJECT_ID

     Replace PROJECT_ID with a name for the Google Cloud project you are creating.

   • Select the Google Cloud project that you created:

     gcloud config set project PROJECT_ID

     Replace PROJECT_ID with your Google Cloud project name.

9. Make sure that billing is enabled for your Google Cloud project.

10. Wenn Sie Cloud Shell nicht verwenden, aktualisieren Sie die Komponenten der Google Cloud-Befehlszeile und melden Sie sich mit Ihrem Konto an:

    gcloud components update
    gcloud auth login

11. APIs aktivieren:

    gcloud services enable artifactregistry.googleapis.com \
        cloudbuild.googleapis.com \
        eventarc.googleapis.com \
        run.googleapis.com \
        storage.googleapis.com

12. Legen Sie die in dieser Anleitung zu verwendenden Konfigurationsvariablen fest:

    export REGION=us-central1
    gcloud config set run/region ${REGION}
    gcloud config set run/platform managed
    gcloud config set eventarc/location ${REGION}

13. Wenn Sie einer Domaineinschränkung zur Organisation nicht eingeschränkter Aufrufe für Ihr Projekt unterliegen, müssen Sie auf Ihren bereitgestellten Dienst zugreifen, wie unter Private Dienste testen beschrieben.

Erforderliche Rollen festlegen

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.

   Erforderliche Berechtigungen

   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:

   • Cloud Build-Bearbeiter (roles/cloudbuild.builds.editor)
   • Cloud Run-Administrator (roles/run.admin)
   • Cloud Run Source Developer (roles/run.sourceDeveloper)
   • Eventarc Admin (roles/eventarc.admin)
   • Zugriffsberechtigter für Logbetrachtung (roles/logging.viewAccessor)
   • Projekt-IAM-Administrator (roles/resourcemanager.projectIamAdmin)
   • Service Account Admin (roles/iam.serviceAccountAdmin)
   • Service Account User (roles/iam.serviceAccountUser)
   • Service Usage Admin (roles/serviceusage.serviceUsageAdmin)
   • Storage-Administrator (roles/storage.admin)

   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.

2. 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:

   [e-mail]

   Ersetzen Sie PROJECT_NUMBER durch Ihre Google Cloud-Projektnummer. Sie finden Ihre Projektnummer auf der Willkommensseite der Google Cloud Console 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.

   Hinweis:

   Die Einschränkung für die Organisationsrichtlinie iam.automaticIamGrantsForDefaultServiceAccounts verhindert, dass die Rolle „Bearbeiter“ automatisch Standarddienstkonten zugewiesen wird. Wenn Sie Ihre Organisation nach dem 3. Mai 2024 erstellt haben, wird diese Einschränkung standardmäßig erzwungen.

   Wir empfehlen dringend, diese Einschränkung zu erzwingen, um die automatische Rollenzuweisung zu deaktivieren. Wenn Sie die automatische Rollenzuweisung deaktivieren, müssen Sie entscheiden, welche Rollen den Standarddienstkonten zugeteilt werden sollen, und diese Rollen dann selbst zuweisen.

   Wenn das Standarddienstkonto bereits die Rolle "Bearbeiter" hat, sollten Sie die Rolle "Bearbeiter" durch weniger strikte Rollen ersetzen. Verwenden Sie zum sicheren Ändern der Rollen des Dienstkontos Policy Simulator, um die Auswirkungen der Änderung zu sehen, und weisen Sie die entsprechenden Rollen zu und widerrufen Sie sie.

3. 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 Google Cloud-Projekt 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:[e-mail] \
       --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.
4. 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:[e-mail] \
       --role=roles/eventarc.eventReceiver

5. 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'

6. 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:[e-mail] \
       --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/

Hinweis: Der Cloud Storage-Bucket muss sich im selben Google Cloud-Projekt und in derselben Region oder Multiregionwie der Eventarc-Trigger befinden.

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

Führen Sie den folgenden Befehl in dem Verzeichnis aus, das den Beispielcode enthält, um die Funktion namens helloworld-events bereitzustellen:

Node.js

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

Python

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

Wenn die Bereitstellung abgeschlossen ist, wird in der Google Cloud CLI eine URL angezeigt, unter der der helloworld-events-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=[e-mail]

   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",
           .....
        }
      ]
      

      Hinweis: Wenn kein Logeintrag angezeigt wird, warten Sie einige Minuten und führen dann den Befehl gcloud logging read noch einmal aus. Nach dem Erstellen des Triggers kann es bis zu zwei Minuten dauern, bis Ereignisse gefiltert werden können.

      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, wurde die ereignisgesteuerte Funktion erfolgreich bereitgestellt und ausgelöst, als eine Textdatei in Cloud Storage hochgeladen wurde.

Bereinigen

Wenn Sie ein neues Projekt für diese Anleitung erstellt haben, löschen Sie das Projekt. Wenn Sie ein vorhandenes Projekt verwendet haben und es beibehalten möchten, ohne die Änderungen in dieser Anleitung hinzuzufügen, löschen Sie die für die Anleitung erstellten Ressourcen.

Projekt löschen

Am einfachsten vermeiden Sie weitere Kosten durch Löschen des für die Anleitung erstellten Projekts.

So löschen Sie das Projekt:

Achtung: Das Löschen von Projekten hat folgende Auswirkungen:

• Alle Inhalte des Projekts werden gelöscht. Wenn Sie für die Aufgaben in diesem Dokument ein bereits bestehendes Projekt verwendet haben und dieses löschen, werden auch alle anderen im Rahmen des Projekts erstellten Daten gelöscht.
• Benutzerdefinierte Projekt-IDs gehen verloren. Beim Erstellen dieses Projekts haben Sie möglicherweise eine benutzerdefinierte Projekt-ID erstellt, die Sie weiterhin verwenden möchten. Damit die URLs, die die Projekt-ID nutzen, z. B. eine appspot.com-URL, erhalten bleiben, sollten Sie ausgewählte Ressourcen innerhalb des Projekts löschen, statt das gesamte Projekt.

Wenn Sie mehrere Architekturen, Anleitungen und Kurzanleitungen durcharbeiten möchten, können Sie die Überschreitung von Projektkontingenten verhindern, indem Sie Projekte wiederverwenden.

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

Anleitungsressourcen löschen

1. Löschen Sie den Cloud Run-Dienst, den Sie in dieser Anleitung bereitgestellt haben:

   gcloud run services delete SERVICE_NAME

   Dabei ist SERVICE_NAME der von Ihnen ausgewählte Dienstname.

   Sie können Cloud Run-Dienste auch über die Google Cloud Console löschen.

2. Entfernen Sie gcloud CLI-Standardkonfigurationen, die Sie während der Einrichtung der Anleitung hinzugefügt haben.

   Beispiel:

   gcloud config unset run/region

   oder

   gcloud config unset project

3. Löschen Sie sonstige Google Cloud-Ressourcen, die in dieser Anleitung erstellt wurden:

   • Löschen Sie den Eventarc-Trigger:

     gcloud eventarc triggers delete TRIGGER_NAME
     

     Ersetzen Sie TRIGGER_NAME durch den Namen des Triggers.

Nächste Schritte

• Eventarc-Trigger für andere Ereignistypen erstellen
• Funktionen verwalten