Trigger aus Cloud Storage-Ereignissen erstellen

In Cloud Run können Sie Dienste aus Cloud Storage mit Eventarc als Reaktion auf Änderungen in Cloud Storage auslösen.

Wählen Sie einen Ereignistyp aus und geben einen Cloud Storage-Bucket an, wenn Sie einen Cloud Storage-Trigger für Ihren Dienst angeben. Aufgrund dieses Triggers wird Ihr Dienst immer dann aufgerufen, wenn eine Änderung an einem Objekt (Datei) im angegebenen Bucket erfolgt.

Damit Ihr Dienst durch ein Ereignis in einem Cloud Storage-Bucket ausgelöst wird, müssen sich der Dienst und der Bucket im selben Google Cloud -Projekt befinden.

Eine detaillierte Anleitung und Codebeispiele zum Erstellen von Triggern aus Cloud Storage-Ereignissen finden Sie in den folgenden Anleitungen:

Unterstützte Cloud Storage-Ereignistypen

Cloud Run unterstützt die folgenden Cloud Storage-Ereignistypen:

Ereignis Ereignistyp Beschreibung
Objekt abgeschlossen
  • google.cloud.storage.object.v1.finalized (über Eventarc)
 Tritt auf, wenn Sie ein neues Objekt erstellen oder ein vorhandenes Objekt überschreiben und Cloud Storage eine neue Generation dieses Objekts erstellt.
Objekt gelöscht
  • google.cloud.storage.object.v1.deleted (über Eventarc)
 Tritt auf, wenn ein Objekt vorläufig gelöscht wird. Weitere Informationen finden Sie unter Vorläufiges Löschen.
Objekt archiviert
  • google.cloud.storage.object.v1.archived (über Eventarc)
 Tritt auf, wenn eine Liveversion eines Objekts zu einer nicht aktuellen Version wird. Weitere Informationen finden Sie unter Objektversionsverwaltung.
Objektmetadaten aktualisiert
  • google.cloud.storage.object.v1.metadataUpdated (über Eventarc)
 Tritt auf, wenn Sie die Metadaten eines vorhandenen Objekts ändern.

Das Repository Google Events enthält zusätzliche Ressourcen für die Arbeit mit Ereignisdaten.

Hinweis

  1. Prüfen Sie, ob Sie ein neues Projekt für Cloud Run eingerichtet haben, wie auf der Seite Einrichtung beschrieben.

  2. Aktivieren Sie die APIs für Artifact Registry, Cloud Build, Cloud Run Admin API, Eventarc, Cloud Logging, Pub/Sub und Cloud Storage:

    APIs aktivieren

  3. Erforderliche IAM-Rollen und ‑Berechtigungen zuweisen

Erforderliche Rollen für das Bereitstellerkonto

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Projekt zuzuweisen, damit Sie die nötigen Berechtigungen für das Auslösen von Cloud Storage-Ereignissen haben:

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.

Trigger für Dienste erstellen

Nachdem Sie einen Dienst bereitgestellt haben, können Sie einen Trigger über die Google Cloud Console, die Google Cloud CLI oder Terraform konfigurieren.

Console

  1. Stellen Sie Ihren Cloud Run-Dienst mit Containern oder aus Quellcode bereit.

  2. Rufen Sie in der Google Cloud Console Cloud Run auf:

    Zu Cloud Run

  3. Klicken Sie in der Liste der Dienste auf einen vorhandenen Dienst.

  4. Rufen Sie auf der Seite „Dienstdetails“ den Tab Trigger auf.

  5. Klicken Sie auf  Trigger hinzufügen und wählen Sie Cloud Storage-Trigger aus.

  6. Ändern Sie im Bereich Eventarc-Trigger die Triggerdetails so:

    1. Geben Sie im Feld Triggername einen Namen für den Trigger ein oder verwenden Sie den Standardnamen.

    2. Wählen Sie einen Triggertyp aus der Liste aus, um einen der folgenden Triggertypen festzulegen:

      • Google-Quellen, um Trigger für Pub/Sub, Cloud Storage, Firestore und andere Google-Ereignisanbieter anzugeben.

      • Drittanbieter, um eine Integration mit Nicht-Google-Anbietern zu ermöglichen, die eine Eventarc-Quelle anbieten. Weitere Informationen finden Sie unter Drittanbieterereignisse in Eventarc.

    3. Wählen Sie in der Liste Ereignisanbieter die Option Cloud Storage aus, um ein Produkt auszuwählen, das den Ereignistyp für das Auslösen Ihres Dienstes bereitstellt. Eine Liste der Ereignisanbieter finden Sie unter Ereignisanbieter und -ziele.

    4. Wählen Sie in der Liste Ereignistyp die Option google.cloud.storage.object.v1.finalized aus. Die Triggerkonfiguration variiert je nach unterstütztem Ereignistyp. Weitere Informationen finden Sie unter Ereignistypen.

    5. Klicken Sie im Feld Bucket auf Durchsuchen, um einen Cloud Storage-Bucket auszuwählen, den der Trigger überwachen soll. Änderungen an Objekten in diesem Bucket lösen Aufrufe Ihrer Funktion aus.

    6. Wenn das Feld Region aktiviert ist, wählen Sie einen Standort für den Eventarc-Trigger aus. Im Allgemeinen sollte der Standort eines Eventarc-Triggers mit dem Standort der Google Cloud Ressource übereinstimmen, die Sie auf Ereignisse überwachen möchten. In den meisten Szenarien sollten Sie Ihren Dienst auch in derselben Region bereitstellen. Weitere Informationen zu Eventarc-Triggerstandorten finden Sie unter Informationen zu Eventarc-Standorten.

    7. Wählen Sie im Feld Dienstkonto ein Dienstkonto aus. Eventarc-Trigger sind mit Dienstkonten verknüpft, um sie beim Aufrufen Ihres Dienstes als Identität zu verwenden. Das Dienstkonto Ihres Eventarc-Triggers muss die Berechtigung zum Aufrufen Ihres Dienstes haben. Standardmäßig verwendet Cloud Run das Compute Engine-Standarddienstkonto.

    8. Geben Sie optional den Dienst-URL-Pfad an, an den die eingehende Anfrage gesendet werden soll. Dies ist der relative Pfad im Zieldienst, an den die Ereignisse für den Trigger gesendet werden sollen. Beispiel: /, /route, route und route/subroute.

    9. Optional: Wenn Sie Wiederholungsversuche aktivieren möchten, falls der Zustellungsversuch fehlschlägt, klicken Sie das Kästchen Bei Fehler noch einmal versuchen an. Andernfalls wird standardmäßig nur ein Zustellungsversuch ohne Wiederholungsversuche durchgeführt. Weitere Informationen finden Sie unter Ereignisse wiederholen.

    10. Wenn Sie die erforderlichen Felder ausgefüllt haben, klicken Sie auf Trigger speichern.

  7. Nachdem Sie den Trigger erstellt haben, können Sie seinen Status prüfen. Dazu muss im Tab Trigger ein Häkchen angezeigt werden.

gcloud

  1. Stellen Sie Ihren Cloud Run-Dienst mit Containern oder aus Quellcode bereit.

  2. Führen Sie den folgenden Befehl aus, um einen Trigger zu erstellen, der Ereignisse filtert und weiterleitet:

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=LOCATION \
    --destination-run-service=DESTINATION_RUN_SERVICE  \
    --destination-run-region=DESTINATION_RUN_REGION \
    --event-filters="type=EVENT_FILTER_TYPE" \
    --event-filters="bucket=BUCKET" \
    --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

    Ersetzen Sie Folgendes:

    • TRIGGER_NAME: die ID des Triggers oder eine voll qualifizierte Kennzeichnung.
    • LOCATION: der Standort des Eventarc-Triggers. Alternativ können Sie das Attribut eventarc/location festlegen. Beispiel: gcloud config set eventarc/location us-central1.

      Zur Vermeidung von Leistungs- und Datenstandortproblemen muss der Standort mit dem Standort des Google Cloud -Dienstes übereinstimmen, der die Ereignisse generiert. Weitere Informationen finden Sie unter Eventarc-Standorte.

    • DESTINATION_RUN_SERVICE: der Name des Cloud Run-Dienstes, der die Ereignisse für den Trigger empfängt. Der Dienst kann sich an einem der von Cloud Run unterstützten Standorte befinden und muss sich nicht am selben Standort wie der Trigger befinden. Er muss sich aber im selben Projekt wie der Trigger befinden. Der Dienst empfängt Ereignisse als HTTP-POST-Anfragen, die an seinen Root-URL-Pfad (/) gesendet werden, wenn das Ereignis erzeugt wird.
    • DESTINATION_RUN_REGION: (optional) der Cloud Run-Standort, an dem sich der Cloud Run-Zieldienst befindet. Wenn keine Angabe erfolgt, wird davon ausgegangen, dass sich der Dienst in derselben Region wie der Trigger befindet.
    • EVENT_FILTER_TYPE: die Kennzeichnung des Ereignisses. Ein Ereignis wird generiert, wenn ein API-Aufruf für die Methode erfolgreich ist. Bei lang andauernden Vorgängen wird das Ereignis nur am Ende des Vorgangs generiert und nur dann, wenn die Aktion erfolgreich ausgeführt wird. Eine Liste der unterstützten Ereignistypen finden Sie unter Von Eventarc unterstützte Google-Ereignistypen.
    • BUCKET: die global eindeutige ID des Cloud Storage-Bucket.
    • SERVICE_ACCOUNT_NAME: der Name Ihres nutzerverwalteten Dienstkontos.
    • PROJECT_ID: Projekt-ID in Google Cloud .

    Hinweise:

    • Das Flag --event-filters="type=EVENT_FILTER_TYPE" ist erforderlich. Wenn kein anderer Ereignisfilter festgelegt ist, werden Ereignisse für alle Ressourcen abgeglichen.
    • EVENT_FILTER_TYPE kann nach dem Erstellen nicht mehr geändert werden. Wenn Sie EVENT_FILTER_TYPE ändern möchten, erstellen Sie einen neuen Trigger und löschen Sie den alten.
    • Jeder Trigger kann mehrere Ereignisfilter haben, die durch Komms in einem --event-filters=[ATTRIBUTE=VALUE,...]-Flag getrennt sind. Sie können das Flag aber auch wiederholen, um weitere Filter hinzuzufügen. Nur Ereignisse, die mit allen Filtern übereinstimmen, werden an das Ziel gesendet. Platzhalter und reguläre Ausdrücke werden nicht unterstützt. Mit dem Flag --event-filters-path-pattern können Sie jedoch ein Pfadmuster für Ressourcen definieren.
    • Optional können Sie mit dem Flag --max-retry-attempts einen einzelnen Zustellversuch ohne Wiederholungen angeben. Der einzige gültige Wert ist 1. Wenn Sie das Flag weglassen, gilt das Standardverhalten für Wiederholungsversuche. Weitere Informationen finden Sie unter Ereignisse wiederholen.
    • Es sind weitere Flags verfügbar. Weitere Informationen finden Sie unter gcloud eventarc triggers create.

Terraform

Informationen zum Erstellen eines Eventarc-Triggers für einen Cloud Run-Dienst finden Sie unter Trigger mit Terraform erstellen.

Trigger für Funktionen erstellen

Nachdem Sie eine Funktion bereitgestellt haben, können Sie einen Trigger über die Google Cloud Console, die Google Cloud CLI oder Terraform konfigurieren.

Console

Wenn Sie die Google Cloud Console zum Erstellen einer Funktion verwenden, können Sie auch einen Trigger für die Funktion hinzufügen. So erstellen Sie einen Trigger für Ihre Funktion:

  1. Rufen Sie in der Google Cloud Console Cloud Run auf:

    Zu Cloud Run

  2. Klicken Sie auf Funktion schreiben und geben Sie die Funktionsdetails ein. Weitere Informationen zum Konfigurieren von Funktionen während der Bereitstellung finden Sie unter Funktionen bereitstellen.

  3. Klicken Sie im Bereich Trigger auf Trigger hinzufügen.

  4. Wählen Sie Cloud Storage-Trigger aus.

  5. Ändern Sie im Bereich Eventarc-Trigger die Triggerdetails so:

    1. Geben Sie im Feld Triggername einen Namen für den Trigger ein oder verwenden Sie den Standardnamen.

    2. Wählen Sie einen Triggertyp aus der Liste aus:

      • Google-Quellen, um Trigger für Pub/Sub, Cloud Storage, Firestore und andere Google-Ereignisanbieter anzugeben.

      • Drittanbieter, um eine Integration mit Nicht-Google-Anbietern zu ermöglichen, die eine Eventarc-Quelle anbieten. Weitere Informationen finden Sie unter Drittanbieterereignisse in Eventarc.

    3. Wählen Sie in der Liste Ereignisanbieter die Option Cloud Storage aus, um ein Produkt auszuwählen, das den Ereignistyp für das Auslösen Ihrer Funktion bereitstellt. Eine Liste der Ereignisanbieter finden Sie unter Ereignisanbieter und -ziele.

    4. Wählen Sie in der Liste Ereignistyp die Option google.cloud.storage.object.v1.finalized aus. Die Triggerkonfiguration variiert je nach unterstütztem Ereignistyp. Weitere Informationen finden Sie unter Ereignistypen.

    5. Lassen Sie das Feld Inhaltstyp der Ereignisdaten unverändert.

    6. Klicken Sie im Feld Bucket auf Durchsuchen, um einen Cloud Storage-Bucket auszuwählen, den der Trigger überwachen soll. Änderungen an Objekten in diesem Bucket lösen Aufrufe Ihrer Funktion aus.

    7. Wenn das Feld Region aktiviert ist, wählen Sie einen Speicherort für den Eventarc-Trigger aus. Im Allgemeinen sollte der Standort eines Eventarc-Triggers mit dem Standort derGoogle Cloud -Ressource übereinstimmen, die Sie auf Ereignisse überwachen möchten. In den meisten Szenarien sollten Sie Ihre Funktion auch in derselben Region bereitstellen. Weitere Informationen zu Eventarc-Triggerstandorten finden Sie unter Informationen zu Eventarc-Standorten.

    8. Wählen Sie im Feld Dienstkonto ein Dienstkonto aus. Eventarc-Trigger sind mit Dienstkonten verknüpft, um sie beim Aufrufen Ihrer Funktion als Identität zu verwenden. Das Dienstkonto Ihres Eventarc-Triggers muss die Berechtigung zum Aufrufen Ihrer Funktion haben. Standardmäßig verwendet Cloud Run das Compute Engine-Standarddienstkonto.

    9. Geben Sie optional den Dienst-URL-Pfad an, an den die eingehende Anfrage gesendet werden soll. Dies ist der relative Pfad im Zieldienst, an den die Ereignisse für den Trigger gesendet werden sollen. Beispiel: /, /route, route und route/subroute.

    10. Optional: Wenn Sie Wiederholungsversuche aktivieren möchten, falls der Zustellungsversuch fehlschlägt, klicken Sie das Kästchen Bei Fehler noch einmal versuchen an. Andernfalls wird standardmäßig nur ein Zustellungsversuch ohne Wiederholungsversuche durchgeführt. Weitere Informationen finden Sie unter Ereignisse wiederholen.

  6. Wenn Sie die erforderlichen Felder ausgefüllt haben, klicken Sie auf Trigger speichern.

  7. Klicken Sie auf Erstellen.

  8. Bearbeiten Sie auf dem Tab Quelle den Quellcode nach Bedarf und wählen Sie dann Speichern und neu bereitstellen aus.

gcloud

Wenn Sie eine Funktion mit der gcloud CLI erstellen, müssen Sie sie zuerst bereitstellen und dann einen Trigger erstellen. So erstellen Sie einen Trigger für Ihre Funktion:

  1. Führen Sie den folgenden Befehl in dem Verzeichnis aus, das den Beispielcode enthält, um die Funktion bereitzustellen:

    gcloud run deploy FUNCTION \
    --source . \
    --function FUNCTION_ENTRYPOINT \
    --base-image BASE_IMAGE_ID \
    --region REGION

    Ersetzen Sie Folgendes:

    • FUNCTION: Der Name der Funktion, die Sie bereitstellen. Sie können diesen Parameter auch weglassen, werden dann jedoch nach dem Namen gefragt.

    • FUNCTION_ENTRYPOINT: Der Einstiegspunkt zur Funktion in Ihrem Quellcode. Dies ist der Code, der von Cloud Run ausgeführt wird, wenn Ihre Funktion ausgeführt wird. Der Wert dieses Flags muss ein Funktionsname oder ein voll qualifizierter Klassenname sein, der in Ihrem Quellcode vorhanden ist.

    • BASE_IMAGE_ID: Die Basisbildumgebung für Ihre Funktion. Weitere Informationen zu Basis-Images und den in den einzelnen Images enthaltenen Paketen finden Sie unter Laufzeit-Basis-Images.

    • REGION: die Google Cloud Region, in der Sie Ihre Funktion bereitstellen möchten. Beispiel: europe-west1

  2. Führen Sie den folgenden Befehl aus, um einen Trigger zu erstellen, der Ereignisse filtert und weiterleitet:

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=LOCATION \
    --destination-run-service=FUNCTION  \
    --destination-run-region=DESTINATION_RUN_REGION \
    --event-filters="type=EVENT_FILTER_TYPE" \
    --event-filters="bucket=BUCKET" \
    --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

    Ersetzen Sie Folgendes:

    • TRIGGER_NAME: die ID des Triggers oder eine voll qualifizierte Kennzeichnung.
    • LOCATION: der Standort des Eventarc-Triggers. Alternativ können Sie das Attribut eventarc/location festlegen. Beispiel: gcloud config set eventarc/location us-central1.

      Zur Vermeidung von Leistungs- und Datenstandortproblemen muss der Standort mit dem Standort des Google Cloud -Dienstes übereinstimmen, der die Ereignisse generiert. Weitere Informationen finden Sie unter Eventarc-Standorte.

    • FUNCTION: der Name der bereitgestellten Cloud Run-Funktion, die die Ereignisse für den Trigger empfängt.
    • DESTINATION_RUN_REGION: (optional) der Cloud Run-Standort, an dem sich die Cloud Run-Zielfunktion befindet. Wenn keine Angabe erfolgt, wird davon ausgegangen, dass sich die Funktion in derselben Region wie der Trigger befindet.
    • EVENT_FILTER_TYPE: die Kennzeichnung des Ereignisses. Ein Ereignis wird generiert, wenn ein API-Aufruf für die Methode erfolgreich ist. Bei lang andauernden Vorgängen wird das Ereignis nur am Ende des Vorgangs generiert und nur dann, wenn die Aktion erfolgreich ausgeführt wird. Eine Liste der unterstützten Ereignistypen finden Sie unter Von Eventarc unterstützte Google-Ereignistypen.
    • BUCKET: die global eindeutige ID des Cloud Storage-Bucket.
    • SERVICE_ACCOUNT_NAME: der Name Ihres nutzerverwalteten Dienstkontos.
    • PROJECT_ID: Projekt-ID in Google Cloud .

    Hinweise:

    • Das Flag --event-filters="type=EVENT_FILTER_TYPE" ist erforderlich. Wenn kein anderer Ereignisfilter festgelegt ist, werden Ereignisse für alle Ressourcen abgeglichen.
    • EVENT_FILTER_TYPE kann nach dem Erstellen nicht mehr geändert werden. Wenn Sie EVENT_FILTER_TYPE ändern möchten, erstellen Sie einen neuen Trigger und löschen Sie den alten.
    • Jeder Trigger kann mehrere Ereignisfilter haben, die durch Komms in einem --event-filters=[ATTRIBUTE=VALUE,...]-Flag getrennt sind. Sie können das Flag aber auch wiederholen, um weitere Filter hinzuzufügen. Nur Ereignisse, die mit allen Filtern übereinstimmen, werden an das Ziel gesendet. Platzhalter und reguläre Ausdrücke werden nicht unterstützt. Mit dem Flag --event-filters-path-pattern können Sie jedoch ein Pfadmuster für Ressourcen definieren.
    • Optional können Sie mit dem Flag --max-retry-attempts einen einzelnen Zustellversuch ohne Wiederholungen angeben. Der einzige gültige Wert ist 1. Wenn Sie das Flag weglassen, gilt das Standardverhalten für Wiederholungsversuche. Weitere Informationen finden Sie unter Ereignisse wiederholen.
    • Es sind weitere Flags verfügbar. Weitere Informationen finden Sie unter gcloud eventarc triggers create.

Terraform

Informationen zum Erstellen eines Eventarc-Triggers für eine Cloud Run-Funktion finden Sie unter Trigger mit Terraform erstellen.

Ereignisübermittlung

Cloud Storage-Trigger werden mit Pub/Sub-Benachrichtigungen für Cloud Storage implementiert. Ereignisse unterliegen den Garantien für die Pub/Sub-Benachrichtigungsübermittlung.

Ein Cloud Storage-Bucket kann bis zu 10 Benachrichtigungskonfigurationen haben, die zum Auslösen von Benachrichtigungen für ein bestimmtes Ereignis festgelegt sind. Wenn Sie die Benachrichtigungslimits des Buckets überschreiten, schlagen weitere Funktionsbereitstellungen mit einem Fehler wie dem folgenden fehl:

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

Sie können diese Einschränkung umgehen, indem Sie Ihr eigenes Pub/Sub-Thema verwalten und es für Cloud Storage-Benachrichtigungen des Typs registrieren, auf den Ihre Funktion reagieren soll. Sie können beispielsweise eine einzelne Benachrichtigung für das ausgewählte Ereignis (z. B. Objekterstellung) für ein Pub/Sub-Thema konfigurieren. Anschließend können Sie beliebig viele Funktionsabonnenten für das Thema haben, die das Ereignis verarbeiten und an mehrere Ziele weiterleiten. Beispiel:

  1. Eigenes Pub/Sub-Thema erstellen
  2. Erstellen Sie in Ihrem Cloud Storage-Bucket eine einzelne Benachrichtigungskonfiguration, die bei einem bestimmten Ereignis (z. B. OBJECT_FINALIZE für die Objekterstellung) ausgelöst wird und das Ereignis an Ihr einzelnes Pub/Sub-Thema sendet.
  3. Erstellen Sie eine oder mehrere Funktionen, die durch Ihr Pub/Sub-Thema ausgelöst werden.

Das Ergebnis ist eine Cloud Storage-Benachrichtigungskonfiguration, ein Pub/Sub-Thema und so viele Funktionen, wie Sie benötigen (innerhalb der sehr hohen Zustellungslimits, die von Pub/Sub zulässig sind).

Weitere Informationen zu Cloud Storage-Limits finden Sie unter Kontingente und Limits für Cloud Storage.

Nächste Schritte