Mit Cloud Functions und Eventarc können Sie Code bereitstellen, um Ereignisse zu verarbeiten, die durch Änderungen an Ihrer Datenbank im Datastore-Modus von Firestore ausgelöst werden. So können Sie serverseitige Funktionen hinzufügen, ohne eigene Server betreiben zu müssen.
Trigger für den Datastore-Modus
Eventarc unterstützt die folgenden Ereignistrigger für Firestore im Datastore-Modus, mit denen Sie Cloud Functions-Handler (2. Generation) erstellen können, die an Firestore-Ereignisse im Datastore-Modus gebunden sind:
Ereignistyp | Trigger |
---|---|
google.cloud.datastore.entity.v1.created |
Wird ausgelöst, wenn eine Entität zum ersten Mal geschrieben wird. |
google.cloud.datastore.entity.v1.updated |
Wird ausgelöst, wenn eine Entität bereits vorhanden ist und sich ein Wert geändert hat. |
google.cloud.datastore.entity.v1.deleted |
Wird ausgelöst, wenn eine Entität gelöscht wird. |
google.cloud.datastore.entity.v1.written |
Wird ausgelöst, wenn created , updated oder deleted ausgelöst wird. |
google.cloud.datastore.entity.v1.created.withAuthContext |
Wie created , fügt jedoch Authentifizierungsinformationen hinzu. |
google.cloud.datastore.entity.v1.updated.withAuthContext |
Wie updated , fügt jedoch Authentifizierungsinformationen hinzu. |
google.cloud.datastore.entity.v1.deleted.withAuthContext |
Wie deleted , fügt jedoch Authentifizierungsinformationen hinzu. |
google.cloud.datastore.entity.v1.written.withAuthContext |
Wie written , fügt jedoch Authentifizierungsinformationen hinzu. |
Trigger für Datastore-Modus-Ereignisse reagieren nur auf Entitätsänderungen. Eine Aktualisierung einer Entität im Datastore-Modus, bei der die Daten unverändert sind (also ein No-Op-Schreibvorgang), führt nicht zu einem Aktualisierungs- oder Schreibereignis. Es ist nicht möglich, Ereignisse nur für bestimmte Properties zu generieren.
Authentifizierungskontext in das Ereignis aufnehmen
Wenn Sie zusätzliche Informationen zur Authentifizierung zum Ereignis hinzufügen möchten, verwenden Sie einen Ereignistrigger mit der Erweiterung withAuthContext
. Durch diese Erweiterung werden zusätzliche Informationen über das Hauptkonto hinzugefügt, das das Ereignis ausgelöst hat. Zusätzlich zu den im Basisereignis zurückgegebenen Informationen werden die Attribute authtype
und authid
hinzugefügt. Weitere Informationen zu Attributwerten finden Sie in der Referenz zu authcontext
.
Durch Entitäten ausgelöste Funktion schreiben
Wenn Sie eine Funktion schreiben möchten, die auf Ereignisse in Firestore im Datastore-Modus reagiert, müssen Sie während der Bereitstellung Folgendes angeben:
- einen Triggerereignistyp
- Einen Triggerereignisfilter, um die mit der Funktion verknüpften Entitäten auszuwählen
- Funktionscode, der ausgeführt werden soll
Filter für Triggerereignisse
Wenn Sie einen Ereignisfilter angeben, können Sie entweder eine genaue Entitätsübereinstimmung oder ein Pfadmuster angeben. Verwenden Sie ein Pfadmuster, um mehrere Entitäten mit den Platzhaltern *
oder **
abzugleichen.
Sie können beispielsweise eine genaue Entitätsübereinstimmung angeben, um auf Änderungen an der folgenden Entität zu reagieren:
users/marie
Verwenden Sie Platzhalter (*
oder **
), um auf Änderungen in Entitäten zu reagieren, die einem Muster entsprechen. Der Platzhalter *
entspricht einem einzelnen Segment und der Platzhalter **
für mehrere Segmente entspricht null oder mehr Segmenten im Muster.
Für Übereinstimmungen mit einem einzelnen Segment (*
) können Sie auch eine benannte Erfassungsgruppe verwenden, z. B. users/{userId}
.
In der folgenden Tabelle sehen Sie gültige Pfadmuster:
Muster | Beschreibung |
---|---|
users/* oder users/{userId} |
Stimmt mit allen Entitäten der Art users überein. Stimmt nicht mit der Ebene der untergeordneten Entitäten wie /users/marie/messages/33e2IxYBD9enzS50SJ68 überein |
users/** |
Stimmt mit allen Entitäten der Art users und allen untergeordneten Entitäten wie /users/marie/messages/33e2IxYBD9enzS50SJ68 überein. |
Weitere Informationen zu Pfadmustern finden Sie unter Eventarc-Pfadmuster.
Der Trigger muss immer auf eine Entität verweisen, auch wenn Sie einen Platzhalter verwenden. Betrachten Sie die folgenden Beispiele:
users/{userId=*}/{messages=*}
ist ungültig, da{messages=*}
eine Art-ID ist.users/{userId=*}/{messages}/{messageId=*}
ist gültig, da{messageId=*}
immer auf eine Entität verweist.
Maskierung von Zeichen
In diesem Abschnitt werden Situationen beschrieben, in denen Zeichen in Art- und Entitäts-IDs mit Escapezeichen versehen werden müssen. Wenn Sie ein Zeichen maskieren, kann der Ereignisfilter die ID korrekt interpretieren.
Wenn eine Typ- oder Entitäts-ID ein
~
- oder/
-Zeichen enthält, müssen Sie die ID in Ihrem Ereignisfilter maskieren. Als Escapezeichen für eine ID wird das Format__escENCODED_ID__
verwendet. Ersetzen Sie ENCODED_ID durch eine Art- oder Entitäts-ID, bei der alle~
- und/
-Zeichen durch ihre Codierungs-IDs ersetzt werden:~
:~0
/
:~1
Die Typ-ID
user/profile
wird beispielsweise zu__escusers~1profile__
. Ein Beispiel für ein Pfadmuster mit dieser Art-ID ist__escusers~1profile__/{userId}
Wenn Sie im Ereignisfilter
.
oder..
als Typ- oder Entitäts-ID verwenden, müssen Sie die ID so mit Escapezeichen versehen:.
:__esc~2__
..
:__esc~2~2__
Das
.
-Zeichen muss nur maskiert werden, wenn die ID genau.
oder..
lautet. Für die Typ-IDcustomers.info
ist beispielsweise kein Escapezeichen erforderlich.Wenn die Art- oder Entitäts-ID ein numerischer Wert anstelle eines Stringwerts ist, müssen Sie die ID mit
__idNUMERIC_VALUE__
maskieren. Das Pfadmuster für eine Entität der Art111
und die Entitäts-ID222
ist beispielsweise__id111__/__id222__
.Wenn Sie von Legacy-Cloud-Datenspeicher zu Firestore im Datastore-Modus migriert sind, enthält Ihre Datenbank möglicherweise Legacy-IDs in einer Nicht-UTF8-Codierung. Diese IDs müssen mit
__bytesBASE64_ENCODING__
maskiert werden. Ersetzen Sie BASE64_ENCODING durch die Base64-Codierung der ID. Das PfadmusterTask/{task}
mit Maskierung für eine Nicht-UTF8-Art-IDTask
wird beispielsweise zu__bytesVGFzaw==__/{task}
.
Beispielfunktionen
Im folgenden Beispiel wird gezeigt, wie Ereignisse im Datastore-Modus empfangen werden.
Um die Daten eines Ereignisses zu nutzen, sehen Sie sich die Felder value
und old_value
an.
value
: EinEntityResult
-Objekt, das einen Entitäts-Snapshot nach Nach dem Vorgang enthält. Dieses Feld wird bei Löschereignissen nicht ausgefüllt.old_value
: EinEntityResult
-Objekt, das einen Entitäts-Snapshot vor dem Vorgang enthält. Dieses Feld wird nur bei Update- und Löschereignissen ausgefüllt.
Java
Informationen zum Installieren und Verwenden der Clientbibliothek für den Datastore-Modus finden Sie unter Clientbibliotheken im Datastore-Modus. Weitere Informationen finden Sie in der Referenzdokumentation zur Java API im Datastore-Modus.
Richten Sie Standardanmeldedaten für Anwendungen ein, um sich im Datastore-Modus zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Proto-Abhängigkeiten in die Quelle einbeziehen
Sie müssen die Datei data.proto
im Datastore-Modus in das Quellverzeichnis für Ihre Funktion aufnehmen. Mit dieser Datei werden die folgenden Protokolle importiert, die Sie auch in das Quellverzeichnis aufnehmen müssen:
Verwenden Sie für die Abhängigkeiten dieselbe Verzeichnisstruktur. Fügen Sie beispielsweise struct.proto
innerhalb von google/protobuf
ein.
Diese Dateien werden zum Decodieren von Ereignisdaten benötigt. Wenn die Funktionsquelle diese Dateien nicht enthält, gibt sie bei der Ausführung einen Fehler zurück.
Ereignisattribute
Jedes Ereignis umfasst Datenattribute mit Informationen über das Ereignis, z. B. die Zeit, zu der das Ereignis ausgelöst wurde. Firestore im Datastore-Modus fügt zusätzliche Daten zur Datenbank und Entität hinzu, die am Ereignis beteiligt ist. Sie können folgendermaßen auf diese Attribute zugreifen:
Java
logger.info("Event time " + event.getTime()); logger.info("Event project: " + event.getExtension("project")); logger.info("Event location: " + event.getExtension("location")); logger.info("Database name: " + event.getExtension("database")); logger.info("Database namespace: " + event.getExtension("namespace")); logger.info("Database entity: " + event.getExtension("entity")); // For withAuthContext events logger.info("Auth information: " + event.getExtension("authid")); logger.info("Auth information: " + event.getExtension("authtype"));
Funktion bereitstellen
Nutzer, die Cloud Functions bereitstellen, müssen die IAM-Rolle Cloud Functions-Entwickler oder eine Rolle mit denselben Berechtigungen haben. Siehe auch Zusätzliche Konfiguration für die Bereitstellung.
Sie können eine Funktion entweder über die gcloud CLI oder die Google Cloud Console bereitstellen. Im folgenden Beispiel wird die Bereitstellung mit der gcloud CLI veranschaulicht. Weitere Informationen zur Bereitstellung mit der Google Cloud Console finden Sie unter Cloud Functions-Funktionen bereitstellen.
-
Aktivieren Sie Cloud Shell in der Google Cloud Console.
Unten in der Google Cloud Console wird eine Cloud Shell-Sitzung gestartet und eine Eingabeaufforderung angezeigt. Cloud Shell ist eine Shell-Umgebung, in der das Google Cloud CLI bereits installiert ist und Werte für Ihr aktuelles Projekt bereits festgelegt sind. Das Initialisieren der Sitzung kann einige Sekunden dauern.
Verwenden Sie den Befehl
gcloud functions deploy
, um eine Funktion bereitzustellen:gcloud functions deploy FUNCTION_NAME \ --gen2 \ --region=FUNCTION_LOCATION \ --trigger-location=TRIGGER_LOCATION \ --runtime=RUNTIME \ --source=SOURCE_LOCATION \ --entry-point=CODE_ENTRYPOINT \ --trigger-event-filters="type=EVENT_FILTER_TYPE" \ --trigger-event-filters="database=DATABASE" \ --trigger-event-filters="namespace=NAMESPACE" \ --trigger-event-filters-path-pattern="entity=ENTITY_OR_PATH" \
Das erste Argument, FUNCTION_NAME, ist ein Name für Ihre bereitgestellte Funktion. Der Name muss mit einem Buchstaben beginnen, gefolgt von bis zu 62 Buchstaben, Ziffern, Bindestrichen oder Unterstrichen. Das letzte Zeichen muss ein Buchstabe oder eine Ziffer sein. Ersetzen Sie FUNCTION_NAME durch einen gültigen Funktionsnamen. Fügen Sie dann die folgenden Flags hinzu:
Das Flag
--gen2
gibt an, dass Sie die Bereitstellung in Cloud Functions (2. Generation) vornehmen möchten. Wenn Sie dieses Flag weglassen, erfolgt die Bereitstellung in Cloud Functions (1. Generation).Das Flag
--region=FUNCTION_LOCATION
gibt die Region an, in der die Funktion bereitgestellt werden soll.Legen Sie für FUNCTION_LOCATION eine Region in der Nähe Ihrer Firestore-Datenbank fest, um die Nähe zu maximieren. Wenn sich Ihre Firestore-Datenbank an einem multiregionalen Standort befindet, legen Sie den Wert für Datenbanken in
nam5
aufus-central1
und für Datenbanken ineur3
aufeurope-west4
fest. Legen Sie für regionale Firestore-Standorte dieselbe Region fest.Das Flag
--trigger-location=TRIGGER_LOCATION
gibt den Ort des Triggers an. Sie müssen TRIGGER_LOCATION auf den Standort der Datenbank im Datastore-Modus festlegen.Das Flag
--runtime=RUNTIME
gibt an, welche Sprachlaufzeit die Funktion verwendet. Cloud Functions unterstützt mehrere Laufzeiten. Weitere Informationen finden Sie unter Laufzeiten. Legen Sie für RUNTIME eine unterstützte Laufzeit fest.Das Flag
--source=SOURCE_LOCATION
gibt den Speicherort des Quellcodes der Funktion an. Nachfolgend finden Sie weitere Informationen:- Vom lokalen Computer bereitstellen
- Über Cloud Storage bereitstellen
- Aus Quell-Repository bereitstellen
Legen Sie für SOURCE_LOCATION den Speicherort des Funktionsquellcodes fest.
Das Flag
--entry-point=CODE_ENTRYPOINT
gibt den Einstiegspunkt für die Funktion in Ihrem Quellcode an. Dies ist der Code, den die Funktion bei der Ausführung ausführt. Sie müssen CODE_ENTRYPOINT auf einen Funktionsnamen oder einen voll qualifizierten Klassennamen festlegen, der im Quellcode vorhanden ist. Weitere Informationen finden Sie unter Funktionseinstiegspunkt.Die Flags
--trigger-event-filters
definieren den Ereignisfilter, der den Triggertyp und die Entität oder den Pfad enthält, der die Ereignisse auslöst. Legen Sie die folgenden Attributwerte fest, um den Ereignisfilter zu definieren:type=EVENT_FILTER_TYPE
: Firestore unterstützt die folgenden Ereignistypen:google.cloud.datastore.entity.v1.created
: Das Ereignis wird gesendet, wenn eine Entität zum ersten Mal geschrieben wird.google.cloud.datastore.entity.v1.updated
: Das Ereignis wird gesendet, wenn eine Entität bereits vorhanden ist und ein Wert geändert wurde.google.cloud.datastore.entity.v1.deleted
: Das Ereignis wird gesendet, wenn eine Entität gelöscht wird.google.cloud.datastore.entity.v1.written
: Ereignis wird gesendet, wenn eine Entität erstellt, aktualisiert oder gelöscht wird.google.cloud.datastore.entity.v1.created.withAuthContext
: Das Ereignis wird gesendet, wenn zum ersten Mal in ein Dokument geschrieben wird und das Ereignis zusätzliche Authentifizierungsinformationen enthält.google.cloud.datastore.entity.v1.updated.withAuthContext
: Das Ereignis wird gesendet, wenn ein Dokument bereits vorhanden ist und sich ein Wert geändert hat. Enthält zusätzliche Informationen zur Authentifizierunggoogle.cloud.datastore.entity.v1.deleted.withAuthContext
: Das Ereignis wird gesendet, wenn ein Dokument gelöscht wird. Enthält zusätzliche Informationen zur Authentifizierunggoogle.cloud.datastore.entity.v1.written.withAuthContext
: Das Ereignis wird gesendet, wenn ein Dokument und ein Ereignis erstellt, aktualisiert oder gelöscht werden. Enthält zusätzliche Informationen zur Authentifizierung
Legen Sie für EVENT_FILTER_TYPE einen dieser Ereignistypen fest.
database=DATABASE
: Firestore-Datenbank. Legen Sie für den Standarddatenbanknamen DATABASE auf(default)
fest.namespace=NAMESPACE
: der Namespace der Datenbank. Legen Sie für den Standarddatenbanknamen NAMESPACE auf(default)
fest. Entfernen Sie das Flag, um einem beliebigen Namespace zu entsprechen.entity=ENTITY_OR_PATH
: der Datenbankpfad, der Ereignisse auslöst, wenn Daten erstellt, aktualisiert oder gelöscht werden. Zulässige Werte für ENTITY_OR_PATH sind:- Gleich. Beispiel:
--trigger-event-filters="entity='users/marie'"
- Pfadmuster. Beispiel:
--trigger-event-filters-path-pattern="entity='users/*'"
. Weitere Informationen finden Sie unter Informationen zu Pfadmustern.
- Gleich. Beispiel:
Sie können optional weitere Konfigurations-, Netzwerk- und Sicherheitsoptionen angeben, wenn Sie eine Funktion bereitstellen.
Eine vollständige Referenz zum Bereitstellungsbefehl und seinen Flags finden Sie in der Dokumentation zu
gcloud functions deploy
.
Beispielbereitstellungen
Die folgenden Beispiele veranschaulichen Bereitstellungen mit der Google Cloud CLI.
Stellen Sie eine Funktion für eine Datenbank in der Region us-west2
bereit:
gcloud functions deploy gcfv2-trigger-datastore-node \
--gen2 \
--region=us-west2 \
--trigger-location=us-west2 \
--runtime=nodejs18 \
--source=gs://example_bucket-1/datastoreEventFunction.zip \
--entry-point=makeUpperCase \
--trigger-event-filters=type=google.cloud.datastore.entity.v1.written \
--trigger-event-filters=database='(default)' \
--trigger-event-filters-path-pattern="entity='messages/{pushId}'"
Stellen Sie eine Funktion für eine Datenbank am multiregionalen Standort nam5
bereit:
gcloud functions deploy gcfv2-trigger-datastore-python \
--gen2 \
--region=us-central1 \
--trigger-location=nam5 \
--runtime=python311 \
--source=gs://example_bucket-1/datastoreEventFunction.zip \
--entry-point=make_upper_case \
--trigger-event-filters=type=google.cloud.datastore.entity.v1.written.withAuthContext \
--trigger-event-filters=database='(default)' \
--trigger-event-filters-path-pattern="entity='messages/{pushId}'"
Beschränkungen
Beachten Sie die folgenden Einschränkungen für Firestore-Trigger für Cloud Functions:
- Für Cloud Functions (1. Generation) wird eine vorhandene „(Standard)-Datenbank“ im nativen Firestore-Modus vorausgesetzt. Firestore-Datenbanken oder der Datastore-Modus werden nicht unterstützt. Verwenden Sie in solchen Fällen Cloud Functions (2. Generation), um Ereignisse zu konfigurieren.
- Die Reihenfolge ist nicht garantiert. Schnelle Änderungen können Funktionsaufrufe in einer unvorhergesehenen Reihenfolge auslösen.
- Ereignisse werden mindestens einmal übergeben. Ein einzelnes Ereignis kann aber zu mehreren Funktionsaufrufen führen. Vermeiden Sie die Abhängigkeit von genau einmal vorkommenden Verfahren und schreiben Sie idempotente Funktionen.
- Firestore im Datastore-Modus erfordert Cloud Functions (2nd gen). Cloud Functions (1st Gen) unterstützt den Datastore-Modus nicht.
- Ein Trigger ist einer einzelnen Datenbank zugeordnet. Sie können keinen Trigger erstellen, der mit mehreren Datenbanken übereinstimmt.
- Durch das Löschen einer Datenbank werden die Trigger für diese Datenbank nicht automatisch gelöscht. Der Trigger sendet keine Ereignisse mehr, bleibt aber bestehen, bis Sie den Trigger löschen.
- Wenn ein übereinstimmendes Ereignis die maximale Anfragegröße überschreitet, wird das Ereignis möglicherweise nicht an Cloud Functions (1. Generation) gesendet.
- Ereignisse, die aufgrund der Größe der Anfrage nicht gesendet werden, werden in Plattformlogs protokolliert und auf die Lognutzung für das Projekt angerechnet.
- Sie finden diese Logs im Log-Explorer mit der Meldung "Ereignis kann nicht an die Cloud Functions-Funktion gesendet werden, da die Größe das Limit für die 1. Generation überschreitet..." mit dem Schweregrad
error
. Sie finden den Funktionsnamen unter dem FeldfunctionName
. Wenn das FeldreceiveTimestamp
noch innerhalb einer Stunde ab jetzt angezeigt wird, können Sie den tatsächlichen Ereignisinhalt ableiten. Lesen Sie dazu das betreffende Dokument mit einem Snapshot vor und nach dem Zeitstempel. - So können Sie solche Frequenzen vermeiden:
- Zu Cloud Functions (2nd gen) migrieren und upgraden
- Dokument verkleinern
- Löschen Sie die betreffenden Cloud Functions-Funktionen
- Sie können das Logging selbst mithilfe von Ausschlüssen deaktivieren. Beachten Sie jedoch, dass die betroffenen Ereignisse weiterhin nicht ausgeliefert werden.
Standorte für Eventarc und Firestore im Datastore-Modus
Eventarc unterstützt keine regionsübergreifenden Trigger für Firestore-Ereignis-Trigger. Sie können aber trotzdem Trigger für Firestore-Datenbanken an multiregionalen Standorten erstellen. Eventarc ordnet multiregionale Firestore-Standorte den folgenden Eventarc-Regionen zu:
Firestore (multiregional) | Eventarc-Region |
---|---|
nam5 |
us-central1 |
eur3 |
europe-west4 |