Trigger aus Firestore-Ereignissen erstellen

Dieser Leitfaden enthält eine Anleitung zum Erstellen von Triggern für Cloud Run-Dienste und -Funktionen aus Firestore-Ereignissen.

Sie können Ihre Cloud Run-Dienste so konfigurieren, dass sie durch Ereignisse in einer Firestore-Datenbank ausgelöst werden. Nach der Auslösung kann Ihr Dienst als Reaktion auf diese Ereignisse eine Firestore-Datenbank lesen und aktualisieren und zwar durch die Firestore APIs und Clientbibliotheken.

In einem typischen Lebenszyklus passiert Folgendes, wenn ein Cloud Run-Dienst durch Firestore-Ereignisse ausgelöst wird:

  1. Der Dienst wartet auf Änderungen an einem bestimmten Dokument.

  2. Wenn eine Änderung eintritt, wird der Dienst ausgelöst und führt seine Aufgaben aus.

  3. Der Dienst empfängt ein Datenobjekt mit einem Snapshot des betreffenden Dokuments. Für write- oder update-Ereignisse enthält das Datenobjekt Snapshots, die den Dokumentstatus vor und nach dem auslösenden Ereignis darstellen.

Ereignistypen

Firestore unterstützt Ereignisse vom Typ create, update, delete und write. Das write-Ereignis umfasst alle Änderungen eines Dokuments.

Ereignistyp Trigger
google.cloud.firestore.document.v1.created (Standard) Wird ausgelöst, wenn ein Dokument zum ersten Mal beschrieben wird.
google.cloud.firestore.document.v1.updated Wird ausgelöst, wenn ein Dokument bereits existiert und sich ein Wert geändert hat.
google.cloud.firestore.document.v1.deleted Wird ausgelöst, wenn ein Dokument mit Daten gelöscht wird.
google.cloud.firestore.document.v1.written Wird ausgelöst, wenn ein Dokument erstellt, aktualisiert oder gelöscht wird.

Platzhalter werden in Triggern in geschweiften Klammern dargestellt, z. B.: projects/YOUR_PROJECT_ID/databases/(default)/documents/collection/{document_wildcard}

Dokumentpfad angeben

Wenn Sie einen Dienst auslösen möchten, müssen Sie den Dokumentpfad angeben, der überwacht werden soll. Der Dokumentpfad muss sich im selben Google Cloud Projekt wie der Dienst befinden.

Hier sehen Sie ein paar Beispiele gültiger Dokumentpfade:

  • users/marie: Gültiger Trigger. Überwacht ein einzelnes Dokument, /users/marie.

  • users/{username}: Gültiger Trigger. Überwacht alle Nutzerdokumente. Bei Angabe von Platzhaltern werden alle Dokumente in der Sammlung überwacht.

  • users/{username}/addresses: Ungültiger Trigger. Bezieht sich auf die untergeordnete Sammlung addresses und nicht auf ein Dokument.

  • users/{username}/addresses/home: Gültiger Trigger. Überwacht das Privatadressdokument für alle Nutzer.

  • users/{username}/addresses/{addressId}: Gültiger Trigger. Überwacht alle Adressdokumente.

  • users/{user=**}: Gültiger Trigger. Überwacht alle Nutzerdokumente und alle Dokumente in Untersammlungen unter jedem Nutzerdokument, z. B. /users/userID/address/home oder /users/userID/phone/work.

Platzhalter und Parameter

Wenn Sie das Dokument, das überwacht werden soll, nicht kennen, verwenden Sie {wildcard} anstelle der Dokument-ID:

  • users/{username} wartet auf Änderungen für alle Nutzerdokumente.

Wenn in diesem Beispiel ein Feld in einem Dokument im Verzeichnis users geändert wird, entspricht es einem Platzhalter namens {username}.

Wenn ein Dokument in users untergeordnete Sammlungen enthält und ein Feld in einem Dokument dieser Sammlungen geändert wird, wird der Platzhalter {username} nicht ausgelöst. Wenn Sie auf Ereignisse in Untersammlungen reagieren möchten, verwenden Sie den Multi-Segment-Platzhalter {username=**}.

Platzhalterübereinstimmungen werden aus Dokumentpfaden extrahiert. Sie können beliebig viele Platzhalter für explizite Sammlungs- oder Dokument-IDs festlegen. Sie können bis zu einen Platzhalter mit mehreren Segmenten wie {username=**} verwenden.

Ereignisstrukturen

Dieser Trigger ruft Ihren Dienst mit einem Ereignis wie dem folgenden auf: 

{
    "oldValue": { // Update and Delete operations only
        A Document object containing a pre-operation document snapshot
    },
    "updateMask": { // Update operations only
        A DocumentMask object that lists changed fields.
    },
    "value": {
        // A Document object containing a post-operation document snapshot
    }
}

Jedes Document-Objekt enthält ein oder mehrere Value-Objekte. Informationen zu Typreferenzen finden Sie in der Dokumentation zu Value.

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 Artifact Registry API, die Cloud Build API, die Cloud Run Admin API, die Eventarc API, die Firestore Cloud Logging API und die Pub/Sub API:

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

Firestore-Datenbank einrichten

Bevor Sie Ihren Dienst bereitstellen, müssen Sie eine Firestore-Datenbank erstellen:

  1. Zur Firestore-Seite "Daten"

  2. Wählen Sie Datenbank erstellen aus.

  3. Klicken Sie auf Nativer Modus und dann auf Weiter.

  4. Geben Sie im Feld Datenbank benennen eine Datenbank-ID ein, z. B. firestore-db.

  5. Wählen Sie unter Standorttyp die Option Region und dann die Region aus, in der sich Ihre Datenbank befinden soll. Diese Entscheidung ist endgültig.

  6. Lassen Sie den Abschnitt Sichere Regeln unverändert.

  7. Klicken Sie auf Datenbank erstellen.

Das Firestore-Datenmodell besteht aus Sammlungen, die Dokumente enthalten. Jedes Dokument enthält eine Reihe von Schlüssel/Wert-Paaren.

Trigger erstellen

Je nach Art des Dienstes, den Sie bereitstellen, haben Sie folgende Möglichkeiten:

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 Firestore-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 Firestore 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 type=google.cloud.firestore.document.v1.created aus. Die Triggerkonfiguration variiert je nach unterstütztem Ereignistyp. Weitere Informationen finden Sie unter Ereignistypen.

    5. Wählen Sie im Bereich „Filter“ eine Datenbank, einen Vorgang und Attributwerte aus oder verwenden Sie die Standardauswahl.

    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" \
    --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.
    • SERVICE_ACCOUNT_NAME: der Name Ihres nutzerverwalteten Dienstkontos.
    • PROJECT_ID: Projekt-ID in Google Cloud .

    Hinweise:

    • Nachdem ein Trigger erstellt wurde, kann der Ereignisfiltertyp nicht mehr geändert werden. Für einen anderen Ereignistyp müssen Sie einen neuen Trigger erstellen.
    • --event-filters=type=google.cloud.firestore.document.v1.written gibt an, dass die Funktion ausgelöst wird, wenn ein Dokument gemäß dem Ereignistyp erstellt, aktualisiert oder gelöscht wird.
    • --event-filters=database='(default)' gibt die Firebase-Datenbank an. Verwenden Sie (default) für den Standarddatenbanknamen.
    • --event-filters-path-pattern=document='users/{username}' enthält das Pfadmuster der Dokumente, die auf relevante Änderungen überwacht werden sollen. Dieses Pfadmuster gibt an, dass alle Dokumente in der Sammlung users überwacht werden sollen. Weitere Informationen finden Sie unter Informationen zu Pfadmustern.
    • 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 Firestore-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 Firestore aus, um ein Produkt auszuwählen, das den Ereignistyp zum 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 type=google.cloud.firestore.document.v1.created aus. Die Triggerkonfiguration variiert je nach unterstütztem Ereignistyp. Weitere Informationen finden Sie unter Ereignistypen.

    5. Wählen Sie im Bereich „Filter“ eine Datenbank, einen Vorgang und Attributwerte aus oder verwenden Sie die Standardauswahl.

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

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

    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.

  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" \
    --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.
    • SERVICE_ACCOUNT_NAME: der Name Ihres nutzerverwalteten Dienstkontos.
    • PROJECT_ID: Projekt-ID in Google Cloud .

    Hinweise:

    • Nachdem ein Trigger erstellt wurde, kann der Ereignisfiltertyp nicht mehr geändert werden. Für einen anderen Ereignistyp müssen Sie einen neuen Trigger erstellen.
    • --event-filters=type=google.cloud.firestore.document.v1.written gibt an, dass die Funktion ausgelöst wird, wenn ein Dokument gemäß dem Ereignistyp erstellt, aktualisiert oder gelöscht wird.
    • --event-filters=database='(default)' gibt die Firebase-Datenbank an. Verwenden Sie (default) für den Standarddatenbanknamen.
    • --event-filters-path-pattern=document='users/{username}' enthält das Pfadmuster der Dokumente, die auf relevante Änderungen überwacht werden sollen. Dieses Pfadmuster gibt an, dass alle Dokumente in der Sammlung users überwacht werden sollen. Weitere Informationen finden Sie unter Informationen zu Pfadmustern.
    • 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.

Weitere Informationen finden Sie unter Firestore mit Ereignistriggern mithilfe von Cloud Run Functions erweitern.

Nächste Schritte

  • Beispiele für Funktionen, die ausgelöst werden, wenn Sie Änderungen an einem Dokument innerhalb einer angegebenen Sammlung vornehmen.