Ein Eventarc-Trigger deklariert Ihr Interesse an einem bestimmten Ereignis oder einer Reihe von Ereignissen. Sie können das Ereignisrouting konfigurieren. Legen Sie dazu Filter für den Trigger fest, einschließlich der Ereignisquelle und des Cloud Run-Zieldienstes.
Eventarc liefert Ereignisse über eine HTTP-Anfrage an den Ereignisempfänger im CloudEvents-Format.
Cloud Firestore unterstützt Auth Context als Erweiterungsattribut für das CloudEvents-Format. Wenn Sie einen Trigger erstellen, können Sie dieses Ereignistypattribut anwenden, um Ereignisse mit Authentifizierungsinformationen zu filtern.
In dieser Anleitung erfahren Sie, wie Sie das Ereignisrouting für den Cloud Run-Dienst konfigurieren, der durch ein direktesCloud Firestore -Ereignis ausgelöst wird. Weitere Informationen finden Sie in der Liste der unterstützten direkten Ereignisse.
Erstellung eines Triggers vorbereiten
Bevor Sie einen Trigger erstellen, müssen Sie folgende Voraussetzungen erfüllen:
Console
Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.
Aktivieren Sie die Cloud Logging, Eventarc und Eventarc Publishing APIs.
Aktivieren Sie gegebenenfalls die API, die mit den direkten Ereignissen verbunden ist. Aktivieren Sie beispielsweise für Cloud Firestore -Ereignisse dieCloud Firestore API.
Falls noch nicht geschehen, erstellen Sie ein nutzerverwaltetes Dienstkonto und weisen Sie ihm die erforderlichen Rollen und Berechtigungen zu, damit Eventarc Ereignisse für Ihren Zieldienst verwalten kann.
Wechseln Sie in der Google Cloud Console zur Seite Dienstkonto erstellen.
Wählen Sie Ihr Projekt aus.
Geben Sie im Feld Dienstkontoname einen Namen ein. Die Google Cloud Console füllt das Feld Dienstkonto-ID anhand dieses Namens aus.
Geben Sie im Feld Dienstkontobeschreibung eine Beschreibung ein. Beispiel:
Service account for event trigger
Klicken Sie auf Erstellen und fortfahren.
Wählen Sie für einen entsprechenden Zugriff in der Liste Rolle auswählen die erforderlichen IAM-Rollen (Identity and Access Management) aus, die Ihrem Dienstkonto für authentifizierte oder nicht authentifizierte Aufrufe zugewiesen werden sollen. Weitere Informationen finden Sie unter Rollen und Berechtigungen für Cloud Run-Ziele.
Klicken Sie auf
Weitere Rolle hinzufügen, um weitere Rollen hinzuzufügen.Klicken Sie auf Weiter.
Klicken Sie zum Abschließen der Erstellung des Dienstkontos auf Fertig.
gcloud
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
Aktivieren Sie die Cloud Logging, Eventarc und Eventarc Publishing APIs.
gcloud services enable logging.googleapis.com \ eventarc.googleapis.com \ eventarcpublishing.googleapis.com
Aktivieren Sie gegebenenfalls die API, die mit den direkten Ereignissen verbunden ist. Aktivieren Sie beispielsweise für Cloud Firestore -Ereignisse
firestore.googleapis.com
.Falls noch nicht geschehen, erstellen Sie ein nutzerverwaltetes Dienstkonto und weisen Sie ihm die erforderlichen Rollen und Berechtigungen zu, damit Eventarc Ereignisse für Ihren Zieldienst verwalten kann.
Erstellen Sie das Dienstkonto:
gcloud iam service-accounts create SERVICE_ACCOUNT_NAME
Ersetzen Sie
SERVICE_ACCOUNT_NAME
durch den Namen des Dienstkontos. Der Name des Dienstkontos muss zwischen 6 und 30 Zeichen lang sein und darf alphanumerische Zeichen in Kleinschreibung sowie Bindestriche enthalten. Nachdem Sie ein Dienstkonto erstellt haben, können Sie den Namen nicht mehr ändern.Erteilen Sie die erforderlichen IAM-Rollen oder -Berechtigungen (Identity and Access Management) für authentifizierte oder nicht authentifizierte Aufrufe. Weitere Informationen finden Sie unter Rollen und Berechtigungen für Cloud Run-Ziele.
Trigger erstellen
Sie können einen Eventarc-Trigger mit der Google Cloud CLI oder über die Google Cloud Console erstellen.
Console
- Rufen Sie in der Google Cloud Console die Seite mit den Eventarc-Triggern auf.
- Klicken Sie auf Trigger erstellen.
- Geben Sie einen Triggernamen ein.
Dies ist die ID des Triggers. Sie muss mit einem Buchstaben beginnen. Sie kann bis zu 63 Kleinbuchstaben, Ziffern oder Bindestriche enthalten.
- Wählen Sie als Triggertyp die Option Google-Quellen aus.
- Wählen Sie in der Liste Ereignisanbieter die Option Cloud Firestore aus.
Beachten Sie, dass der Name des Ereignisanbieters, der in der zugehörigen Google Cloud-Dokumentation verwendet wird, möglicherweise nicht das Präfix Cloud oder Google Cloud hat. In der Console wird Memorystore for Redis beispielsweise als Google Cloud Memorystore for Redis bezeichnet.
- Wählen Sie in der Liste Ereignistyp aus den Ereignissen Direkt einen Ereignistyp aus.
- Wählen Sie in der Liste Inhaltstyp der Ereignisdaten die Codierung der Ereignisnutzlast aus.
Für direkte Ereignisse von Cloud Firestoremuss dies application/protobuf sein und die Ereignisdaten sind ein Byte-Array. Weitere Informationen zu den protobuf-Nachrichten für Cloud Firestore-Ereignisse finden Sie unter Häufige Ereignisse.
- Wählen Sie in der Liste Region dieselbe Region aus, in der sich der Google Cloud-Dienst befindet, der Ereignisse generiert.
Weitere Informationen finden Sie unter Eventarc-Standorte.
- Klicken Sie, sofern für den Ereignisanbieter zutreffend, auf Filter hinzufügen und geben Sie Folgendes an:
- Wählen Sie im Feld Attribut 1 je nach ausgewähltem direktem Ereignis eine Ressourcen-ID aus, die als Ereignisfilter dienen kann.
- Wählen Sie einen Operator aus:
- Gleich
- Pfadmuster: Gilt für
document
-Ressourcen (nativer Modus) undentity
-Ressourcen (Datastore-Modus). Verwenden Sie Platzhalter, um auf Änderungen zu reagieren, die einem Muster entsprechen. Ein Platzhalter*
entspricht einem einzelnen Segment und ein Platzhalter mit mehreren Segmenten**
entspricht null oder mehr Segmenten im Muster. Beispiel:/users/*
oder/users/{userId}
Entspricht allen Dokumenten in der Sammlung /users
. Stimmt nicht mit Dokumenten in Untersammlungen wie/users/marie/messages/33e2IxYBD9enzS50SJ68
überein/users/**
Führt zu Übereinstimmung mit allen Dokumenten in der Sammlung /users
und Dokumenten in Untersammlungen wie/users/marie/messages/33e2IxYBD9enzS50SJ68
Weitere Informationen finden Sie unter Pfadmuster verstehen.
- Geben Sie im Feld Attributwert 1 je nach ausgewähltem Operator den genauen Wert ein oder wenden Sie ein Pfadmuster an.
- Wenn weitere Attributfilter anwendbar sind, klicken Sie auf Filter hinzufügen und geben Sie die entsprechenden Werte an.
- Wählen Sie das Dienstkonto aus, das Ihren Dienst oder Workflow aufruft.
Alternativ können Sie ein neues Dienstkonto erstellen.
Dies gibt die E-Mail-Adresse des IAM-Dienstkontos (Identity and Access Management) an, die dem Trigger zugeordnet ist und für die Sie zuvor bestimmte Rollen zugewiesen haben, die für Eventarc erforderlich sind.
- Wählen Sie in der Liste Ereignisziel die Option Cloud Run aus.
- Wählen Sie einen Dienst aus.
Dies ist der Name des Dienstes, der die Ereignisse für den Trigger empfängt. Der Dienst muss sich im selben Projekt wie der Trigger befinden und empfängt Ereignisse als HTTP-POST-Anfragen, die an seinen Root-URL-Pfad (
/
) gesendet werden, wenn das Ereignis erzeugt wird. - Optional können Sie den Dienst-URL-Pfad angeben, 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
,route/subroute
. - Klicken Sie auf Erstellen.
Nachdem ein Trigger erstellt wurde, können die Ereignisquellenfilter nicht mehr geändert werden. Erstellen Sie stattdessen einen neuen Trigger und löschen Sie den alten. Weitere Informationen finden Sie unter Trigger verwalten.
gcloud
Wenn Sie einen gcloud eventarc triggers create
-Befehl zusammen mit den erforderlichen und optionalen Flags ausführen, können Sie einen Trigger erstellen.
Die Flags unterscheiden sich je nachdem, ob Sie Firestore im nativen Modus oder im Datastore-Modus ausführen. Weitere Informationen finden Sie unter Zwischen nativem Modus und Datastore-Modus wechseln.
Nativer Modus
gcloud eventarc triggers create TRIGGER \ --location=LOCATION \ --destination-run-service=DESTINATION_RUN_SERVICE \ --destination-run-region=DESTINATION_RUN_REGION \ --event-filters="type=EVENT_FILTER_TYPE" \ --event-filters="database=DATABASE" \ --event-filters="namespace=NAMESPACE" \ --event-filters-path-pattern="document=DOCUMENT" \ --event-data-content-type="EVENT_DATA_CONTENT_TYPE" \ --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com"
Datastore-Modus
gcloud eventarc triggers create TRIGGER \ --location=LOCATION \ --destination-run-service=DESTINATION_RUN_SERVICE \ --destination-run-region=DESTINATION_RUN_REGION \ --event-filters="type=EVENT_FILTER_TYPE" \ --event-filters="database=DATABASE" \ --event-filters="namespace=NAMESPACE" \ --event-filters-path-pattern="entity=ENTITY" \ --event-data-content-type="EVENT_DATA_CONTENT_TYPE" \ --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com"
Ersetzen Sie Folgendes:
TRIGGER
: die ID des Triggers oder eine voll qualifizierte Kennzeichnung.
LOCATION
: der Standort des Eventarc-Triggers. Alternativ können Sie das Attributeventarc/location
festlegen. Beispiel:gcloud config set eventarc/location us-central1
.Cloud Firestore-Trigger für Eventarc sind nur an bestimmten Standorten verfügbar und der Trigger muss sich am selben Standort wie die Cloud Firestore-Datenbank befinden. Weitere Informationen finden Sie unter Eventarc-Standorte und Cloud Firestore-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) die Region, in der 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 Ereignistypen.
Cloud Firestore unterstützt die folgenden Ereignistypen nur im nativen Modus.
google.cloud.firestore.document.v1.created
: Dieses Ereignis wird gesendet, wenn zum ersten Mal in ein Dokument geschrieben wird.google.cloud.firestore.document.v1.created.withAuthContext
: Das Ereignis mit Attributen für Authentifizierungsinformationen wird gesendet, wenn zum ersten Mal in ein Dokument geschrieben wird.google.cloud.firestore.document.v1.updated
: Dieses Ereignis wird gesendet, wenn ein Dokument bereits vorhanden ist und sich ein Wert geändert hat.google.cloud.firestore.document.v1.updated.withAuthContext
: Das Ereignis mit Attributen für Authentifizierungsinformationen wird gesendet, wenn ein Dokument bereits vorhanden ist und sich ein Wert geändert hat.google.cloud.firestore.document.v1.deleted
: Ereignis wird gesendet, wenn ein Dokument gelöscht wird.google.cloud.firestore.document.v1.deleted.withAuthContext
: Das Ereignis mit Attributen für Authentifizierungsinformationen wird gesendet, wenn ein Dokument gelöscht wird.google.cloud.firestore.document.v1.written
: Dieses Ereignis wird gesendet, wenn ein Dokument erstellt, aktualisiert oder gelöscht wird.google.cloud.firestore.document.v1.written.withAuthContext
: Ein Ereignis mit Attributen für Authentifizierungsinformationen wird gesendet, wenn ein Dokument erstellt, aktualisiert oder gelöscht wird.google.cloud.datastore.entity.v1.created
: Dieses Ereignis wird gesendet, wenn zum ersten Mal in eine Entität geschrieben wird.google.cloud.datastore.entity.v1.created.withAuthContext
: Das Ereignis mit Attributen für Authentifizierungsinformationen wird gesendet, wenn in eine Entität zum ersten Mal geschrieben wird.google.cloud.datastore.entity.v1.updated
: Dieses Ereignis wird gesendet, wenn eine Entität bereits vorhanden ist und sich ein Wert geändert hat.google.cloud.datastore.entity.v1.updated.withAuthContext
: Das Ereignis mit Attributen für Authentifizierungsinformationen wird gesendet, wenn eine Entität bereits vorhanden ist und sich ein Wert geändert hat.google.cloud.datastore.entity.v1.deleted
: Dieses Ereignis wird gesendet, wenn eine Entität gelöscht wird.google.cloud.datastore.entity.v1.deleted.withAuthContext
: Ereignis mit Attributen für Authentifizierungsinformationen wird gesendet, wenn eine Entität gelöscht wird.google.cloud.datastore.entity.v1.written
: Dieses Ereignis wird gesendet, wenn eine Entität erstellt, aktualisiert oder gelöscht wird.google.cloud.datastore.entity.v1.written.withAuthContext
: Das Ereignis mit Attributen für Authentifizierungsinformationen wird gesendet, wenn eine Entität erstellt, aktualisiert oder gelöscht wird.
Cloud Firestore unterstützt die folgenden Ereignistypen nur im Datastore-Modus. Datenobjekte in Firestore im Datastore-Modus werden als Entitäten bezeichnet.
DATABASE
: Firestore-Datenbank. Verwenden Sie für den Standarddatenbanknamen(default)
.NAMESPACE
(optional): der Firestore-Datenbank-Namespace. Verwenden Sie für den Standard-Namespace im Datastore-Modus(default)
. Wenn nicht angegeben, wird ein Platzhalterabgleich (*
) mit beliebigen Vorkommen vorgenommen.DOCUMENT
(optional): Gilt für Datenbankinstanzen, die nur im nativen Modus ausgeführt werden. Der Datenbankpfad, von dem Sie Ereignisse erhalten möchten, wenn Daten in diesem Pfad erstellt, aktualisiert oder gelöscht werden. Als Operator kommen die folgenden Zeichen infrage:- Gleich. Beispiel:
--event-filters="document=DOCUMENT"
- Pfadmuster. Beispiel:
--event-filters-path-pattern="document=DOCUMENT"
.Verwenden Sie Platzhalter, um auf Änderungen in Dokumenten zu reagieren, die einem bestimmten Muster entsprechen. Ein Platzhalter
*
entspricht einem einzelnen Segment und ein Multi-Segment-Platzhalter**
entspricht null oder mehr Segmenten im Muster. Beispiel:/users/*
oder/users/{userId}
Entspricht allen Dokumenten in der Sammlung /users
. Stimmt nicht mit Dokumenten in Untersammlungen wie/users/marie/messages/33e2IxYBD9enzS50SJ68
überein/users/**
Führt zu Übereinstimmung mit allen Dokumenten in der Sammlung /users
und Dokumenten in Untersammlungen wie/users/marie/messages/33e2IxYBD9enzS50SJ68
- Gleich. Beispiel:
ENTITY
(optional): Gilt für Datenbankinstanzen, die nur im Datastore-Modus ausgeführt werden. Der Datenbankpfad, von dem Sie Ereignisse erhalten möchten, wenn Daten in diesem Pfad erstellt, aktualisiert oder gelöscht werden. Als Operator kommen die folgenden Zeichen infrage:- Gleich. Beispiel:
--event-filters="document=ENTITY"
- Pfadmuster. Beispiel:
--event-filters-path-pattern="ENTITY=ENTITY"
.Weitere Informationen finden Sie unter Pfadmuster verstehen.
Eventuell müssen Sie Zeichen in Art-IDs und Entitäts-IDs maskieren. Durch das Maskieren eines Zeichens kann der Ereignisfilter die ID korrekt interpretieren. Weitere Informationen finden Sie unter Zeichenmaskierung.
- Gleich. Beispiel:
EVENT_DATA_CONTENT_TYPE
: die Codierung der Ereignisnutzlast. Für direkte Ereignisse aus Firestore muss diesapplication/protobuf
sein. Die Ereignisdaten sind ein Byte-Array. Weitere Informationen zu den protobuf-Nachrichten für Cloud Firestore-Ereignisse finden Sie unter Häufige Ereignisse.SERVICE_ACCOUNT_NAME
: der Name Ihres nutzerverwalteten Dienstkontos.PROJECT_ID
ist Ihre Google Cloud-Projekt-ID.
Hinweise:
- Bei direkten Ereignissen aus Cloud Firestorelautet die Codierung der Ereignisnutzlast
application/protobuf
. - 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 SieEVENT_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. - Mit dem Flag
--service-account
wird die E-Mail-Adresse des IAM-Dienstkontos (Identity and Access Management) angegeben, das mit dem Trigger verknüpft ist. - Optional können Sie einen relativen Pfad im Cloud Run-Zieldienst angeben, an den die Ereignisse für den Trigger durch Verwendung des Flags
--destination-run-path
gesendet werden sollen.
Beispiel:
gcloud eventarc triggers create helloworld-trigger \ --location=us-east1 \ --destination-run-service=helloworld-events \ --destination-run-region=us-east1 \ --event-filters="type=google.cloud.firestore.document.v1.updated" \ --event-filters="database=my-database" \ --event-filters-path-pattern="document=users/my-document-*" \ --event-data-content-type="application/protobuf" \ --service-account=${SERVICE_ACCOUNT_NAME}@${PROJECT_ID}.iam.gserviceaccount.com
Dieser Befehl erstellt einen Trigger mit dem Namen helloworld-trigger
für das Ereignis, das in der Datenbankinstanz my-database
im nativen Modus als google.cloud.firestore.document.v1.updated
identifiziert wird, und filtert Ereignisse für document
-Pfade die users/my-document-
entsprechen.
Trigger auflisten
Sie können die Erstellung eines Triggers bestätigen, indem Sie Eventarc-Trigger mit der Google Cloud CLI oder über die Google Cloud Console auflisten.
Console
Rufen Sie in der Google Cloud Console die Seite mit den Eventarc-Triggern auf.
Auf dieser Seite werden Ihre Trigger an allen Standorten aufgelistet. Außerdem enthält sie Details wie Namen, Regionen, Ereignisanbieter, Ziele usw.
So filtern Sie die Trigger:
- Klicken Sie auf Filter oder das Feld Trigger filtern.
- Wählen Sie in der Liste Attribute eine Option aus, nach der die Trigger gefiltert werden sollen.
Sie können ein einzelnes Attribut auswählen oder den logischen Operator
OR
verwenden, um weitere Attribute hinzuzufügen.Klicken Sie zum Sortieren der Trigger neben jeder unterstützten Spaltenüberschrift auf
Sortieren.
gcloud
Führen Sie den folgenden Befehl aus, um die Trigger aufzulisten:
gcloud eventarc triggers list --location=-
Dieser Befehl listet Ihre Trigger an allen Standorten auf und enthält Details wie Namen, Typen, Ziele und Status.
Nächste Schritte
- Weitere Informationen zur Verwendung von Eventarc und Cloud Firestore
- Weitere Informationen zu Eventarc.
- Trigger verwalten.