Direkte Ereignisse von Cloud Storage erhalten (gcloud-CLI)

Direkte Ereignisse von Cloud Storage erhalten (gcloud-CLI)

In dieser Kurzanleitung erfahren Sie, wie Sie direkte Ereignisse von Cloud Storage (ohne Verwendung von Cloud-Audit-Logs) in einem nicht authentifizierten Cloud Run-Dienst mit Eventarc empfangen. eine

Hinweis: Alle Cloud Run-Dienste werden standardmäßig privat bereitgestellt. Das bedeutet, dass sie ohne Authentifizierungsanmeldedaten in der Anfrage nicht zugänglich sind. Für Projekte mit Organisationsrichtlinien für die domaineingeschränkte Freigabe verwenden Sie stattdessen einen authentifizierten Cloud Run-Zieldienst, anstelle eines Dienstes, der den öffentlichen (unauthentifizierten) Zugriff erlaubt.

Sie können das Auslösen von Benachrichtigungen als Reaktion auf verschiedene Ereignisse innerhalb eines Cloud Storage-Buckets konfigurieren: Objekterstellung, Löschen, Archivieren und Aktualisieren von Metadaten. Weitere Informationen finden Sie unter Trigger zum Weiterleiten von Cloud Storage-Ereignissen an Cloud Run erstellen.

In dieser Kurzanleitung werden folgende Schritte erläutert:

1. Cloud Storage-Bucket als Ereignisquelle erstellen

2. Ereignisempfängerdienst für Cloud Run bereitstellen

3. Eventarc-Trigger erstellen

4. Laden Sie eine Datei in den Cloud Storage-Bucket hoch, um ein Ereignis zu erstellen und es in den Cloud Run-Logs aufzurufen.

Hinweise

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. Aktivieren Sie die Cloud Run, Cloud Storage, Eventarc und Pub/Sub APIs.

    gcloud services enable \
    eventarc.googleapis.com \
    pubsub.googleapis.com \
    run.googleapis.com \
    storage.googleapis.com

11. Aktualisieren Sie die gcloud-Komponenten:

    gcloud components update

12. Melden Sie sich mit Ihrem -Konto an:

    gcloud auth login

13. Legen Sie die in dieser Kurzanleitung verwendeten Konfigurationsvariablen fest:

    gcloud config set run/region us-central1
    gcloud config set run/platform managed
    gcloud config set eventarc/location us-central1

14. 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 Run-Administrator (roles/run.admin)
    • 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.

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

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

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

18. 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 gs://PROJECT_ID-bucket/ --location=us-central1

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

Nachdem die Ereignisquelle erstellt wurde, können Sie den Ereignisempfängerdienst in Cloud Run bereitstellen.

Dienst zum Empfangen von Ereignissen in Cloud Run bereitstellen

Stellen Sie einen Cloud Run-Dienst bereit, der Ereignisse mithilfe des vordefinierten Images us-docker.pkg.dev/cloudrun/container/hello empfängt und protokolliert:

gcloud run deploy helloworld-events \
    --image=us-docker.pkg.dev/cloudrun/container/hello \
    --allow-unauthenticated

Wenn die Bereitstellung erfolgreich war, wird in der Befehlszeile die Dienst-URL angezeigt.

Sie haben den Ereignisempfängerdienst helloworld-events in Cloud Run bereitgestellt. Nun können Sie einen Trigger einrichten.

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 und das Compute Engine-Standarddienstkonto verwendet.

     gcloud eventarc triggers create storage-events-trigger \
         --destination-run-service=helloworld-events \
         --destination-run-region=us-central1 \
         --event-filters="type=google.cloud.storage.object.v1.finalized" \
         --event-filters="bucket=PROJECT_ID-bucket" \
         --service-account=[e-mail]
   

   Dadurch wird ein Trigger mit dem Namen storage-events-trigger erstellt.

   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. Führen Sie diesen Befehl aus, um zu prüfen, ob storage-events-trigger erfolgreich erstellt wurde:

     gcloud eventarc triggers list --location=us-central1
   

   Die entsprechende Ausgabe sieht etwa so aus:

    NAME                    TYPE                                      DESTINATION_RUN_SERVICE  DESTINATION_RUN_PATH  ACTIVE
    storage-events-trigger  google.cloud.storage.object.v1.finalized  helloworld-events                              Yes
   

Hinweis: Der Trigger wird zwar sofort erstellt, es kann jedoch bis zu zwei Minuten dauern, bis Trigger vollständig funktionieren.

Ereignis erstellen und abrufen

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 der Cloud Run-Dienst loggt die Nachricht des Ereignisses.

2. Filtern Sie die Logeinträge und geben Sie die Ausgabe im JSON-Format zurück, um den Logeintrag aufzurufen:

   gcloud logging read 'jsonPayload.message: "Received event of type google.cloud.storage.object.v1.finalized."'
   

3. Suchen Sie nach einem Logeintrag wie dem Folgenden:

   jsonPayload:
     event:
     ...
     eventType: google.cloud.storage.object.v1.finalized
     message: |
       Received event of type google.cloud.storage.object.v1.finalized. Event data: {
         "kind": "storage#object",
         "id": "PROJECT_ID-bucket/random.txt/1713970683868432",
         "selfLink": "https://www.googleapis.com/storage/v1/b/PROJECT_ID-bucket/o/random.txt",
         "name": "random.txt",
         "bucket": "PROJECT_ID-bucket",
         ...
       }
   

   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.

Glückwunsch! Sie haben einen Ereignisempfängerdienst in Cloud Run erfolgreich bereitgestellt, einen Eventarc-Trigger erstellt sowie ein Ereignis aus Cloud Storage generiert und in den Cloud Run-Logs angesehen.

Bereinigen

Nach Abschluss der in diesem Dokument beschriebenen Aufgaben können Sie weitere Kosten vermeiden, indem Sie die erstellten Ressourcen löschen.

Sie können:

1. Löschen Sie den Cloud Storage-Bucket.

2. Löschen Sie den Cloud Run-Dienst.

3. Den Eventarc-Trigger löschen.

Alternativ können Sie Ihr Google Cloud-Projekt löschen, um wiederkehrende Gebühren zu vermeiden. Wenn Sie Ihr Google Cloud-Projekt löschen, wird die Abrechnung für alle in diesem Projekt verwendeten Ressourcen beendet.

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.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

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

Nächste Schritte

• Container für Cloud Run erstellen
• Cloud Run-Job in einem Workflow mit einem Eventarc-Trigger ausführen
• Cloud Run-Dienste entwickeln