Mit Cloud Functions (2nd gen) erweitern
Mit Cloud Functions können Sie Code bereitstellen, um Ereignisse zu verarbeiten, die durch Änderungen in Ihrer Firestore-Datenbank ausgelöst werden. Auf diese Weise können Sie serverseitige Funktionen hinzufügen, ohne eigene Server betreiben zu müssen.
Firestore mit Cloud Functions (2nd gen) erweitern
Cloud Functions (2nd gen) unterstützt die folgenden Firestore-Ereignistrigger, damit Sie Handler erstellen können, die mit Firestore-Ereignissen verknüpft sind:
Ereignistyp | Trigger |
---|---|
google.cloud.firestore.document.v1.created |
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 gelöscht wird |
google.cloud.firestore.document.v1.written |
Wird ausgelöst, wenn created , updated oder deleted ausgelöst wird. |
google.cloud.firestore.document.v1.created.withAuthContext |
Wie „created “, aber es werden Authentifizierungsinformationen hinzugefügt. |
google.cloud.firestore.document.v1.updated.withAuthContext |
Wie „updated “, aber es werden Authentifizierungsinformationen hinzugefügt. |
google.cloud.firestore.document.v1.deleted.withAuthContext |
Wie „deleted “, aber es werden Authentifizierungsinformationen hinzugefügt. |
google.cloud.firestore.document.v1.written.withAuthContext |
Wie „written “, aber es werden Authentifizierungsinformationen hinzugefügt. |
Firestore-Ereignisse werden nur bei Dokumentänderungen ausgelöst. Eine Aktualisierung eines Firestore-Dokuments, bei der die Daten unverändert sind (ein No-Op-Schreiben), generiert kein Aktualisierungs- oder Schreibereignis. Es ist nicht möglich, bestimmten Feldern Ereignisse hinzuzufügen.
Authentifizierungskontext in das Ereignis aufnehmen
Wenn Sie dem Ereignis zusätzliche Authentifizierungsinformationen hinzufügen möchten, verwenden Sie einen Ereignistrigger mit der Erweiterung withAuthContext
. Durch diese Erweiterung werden zusätzliche Informationen zum 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 Firestore ausgelöste Funktion schreiben
Wenn Sie eine Funktion schreiben möchten, die auf Firestore-Ereignisse reagiert, müssen Sie bei der Bereitstellung Folgendes angeben:
- Triggerereignistyp
- Triggerereignisfilter, um die mit der Funktion verknüpften Dokumente auszuwählen
- Funktionscode für die Ausführung
Filter für Triggerereignisse
Wenn Sie einen Ereignisfilter angeben, können Sie entweder eine genaue Dokumentübereinstimmung oder ein Pfadmuster angeben. Verwenden Sie ein Pfadmuster, um mehrere Dokumente mit den Platzhaltern *
oder **
abzugleichen.
Sie können beispielsweise auf Änderungen am folgenden Dokument reagieren:
users/marie
Verwenden Sie die Platzhalter *
oder **
, um auf Änderungen in Dokumenten zu reagieren, die einem Muster entsprechen. Ein Platzhalter *
entspricht einem einzelnen Segment und der Platzhalter **
aus mehreren Segmenten entspricht null oder mehr Segmenten im Muster.
Für einzelne Segmentübereinstimmungen (*
) können Sie auch eine benannte Erfassungsgruppe verwenden. Beispiel: users/{userId}
Beispiel:
Muster | Beschreibung |
---|---|
/users/* oder /users/{userId} |
Entspricht allen Dokumenten in der Sammlung /users . Stimmt nicht mit Dokumenten in untergeordneten Sammlungen wie /users/marie/messages/33e2IxYBD9enzS50SJ68 überein |
/users/** |
Stimmt mit allen Dokumenten in der Sammlung /users und Dokumenten in untergeordneten Sammlungen wie /users/marie/messages/33e2IxYBD9enzS50SJ68 überein |
Weitere Informationen zu Pfadmustern finden Sie unter Eventarc-Pfadmuster.
Der Trigger muss immer auf ein Dokument verweisen, auch wenn Sie einen Platzhalter verwenden.
users/{userId=*}/{messageCollectionId=*}
ist beispielsweise ungültig, da {messageCollectionId=*}
eine Sammlung ist. users/{userId=*}/{messageCollectionId}/{messageId=*}
ist jedoch gültig, da {messageId=*}
immer auf ein Dokument verweist.
Beispielfunktionen
Im folgenden Beispiel wird gezeigt, wie Firestore-Ereignisse empfangen werden.
Wenn Sie mit den Dokumentdaten eines Ereignisses arbeiten möchten, sehen Sie sich die Felder value
und old_value
an.
value
: EinDocument
-Objekt, das einen Dokument-Snapshot post-operation enthält. Dieses Feld wird bei Löschereignissen nicht ausgefüllt.old_value
: EinDocument
-Objekt, das einen Dokument-Snapshot vor dem Vorgang enthält. Dieses Feld wird nur bei Aktualisierungs- und Löschereignissen ausgefüllt.
Go
Richten Sie Standardanmeldedaten für Anwendungen ein, um sich bei Firestore zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Java
Richten Sie Standardanmeldedaten für Anwendungen ein, um sich bei Firestore zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Node.js
Richten Sie Standardanmeldedaten für Anwendungen ein, um sich bei Firestore zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Decodieren Sie die Ereignisdaten mit protobufjs. Fügen Siegoogle.events.cloud.firestore.v1
data.proto
in Ihre Quelle ein.
Python
Richten Sie Standardanmeldedaten für Anwendungen ein, um sich bei Firestore zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
C#
Richten Sie Standardanmeldedaten für Anwendungen ein, um sich bei Firestore zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
In den folgenden Beispielen werden Strings, die dem Feld original
eines betroffenen Dokuments hinzugefügt wurden, in Großbuchstaben umgewandelt und der neue Wert in dasselbe Dokument geschrieben:
Go
Richten Sie Standardanmeldedaten für Anwendungen ein, um sich bei Firestore zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Java
Richten Sie Standardanmeldedaten für Anwendungen ein, um sich bei Firestore zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Node.js
Richten Sie Standardanmeldedaten für Anwendungen ein, um sich bei Firestore zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Decodieren Sie die Ereignisdaten mit protobufjs. Fügen Siegoogle.events.cloud.firestore.v1
data.proto
in Ihre Quelle ein.
Python
Richten Sie Standardanmeldedaten für Anwendungen ein, um sich bei Firestore zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
C#
Richten Sie Standardanmeldedaten für Anwendungen ein, um sich bei Firestore zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Proto-Abhängigkeiten in die Quelle aufnehmen
Sie müssen die Firestore-Datei data.proto
in das Quellverzeichnis für Ihre Funktion einfügen. Diese Datei importiert die folgenden Proto-Dateien, die Sie auch in Ihr Quellverzeichnis aufnehmen müssen:
Verwenden Sie für die Abhängigkeiten dieselbe Verzeichnisstruktur. Platziere beispielsweise struct.proto
innerhalb von google/protobuf
.
Diese Dateien werden benötigt, um Ereignisdaten zu decodieren. Wenn Ihre Funktionsquelle diese Dateien nicht enthält, gibt sie bei der Ausführung einen Fehler zurück.
Ereignisattribute
Jedes Ereignis enthält Datenattribute mit Informationen zum Ereignis, z. B. zu dem Zeitpunkt, zu dem das Ereignis ausgelöst wurde. Firestore fügt zusätzliche Daten über die Datenbank und das Dokument hinzu, das vom Ereignis betroffen ist. So können Sie auf diese Attribute zugreifen:
Java
logger.info("Function triggered by event on: " + event.getSource()); logger.info("Event type: " + event.getType()); 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 document: " + event.getExtension("document")); // For withAuthContext events logger.info("Auth information: " + event.getExtension("authid")); logger.info("Auth information: " + event.getExtension("authtype"));
Node.js
console.log(`Function triggered by event on: ${cloudEvent.source}`); console.log(`Event type: ${cloudEvent.type}`); console.log(`Event time: ${cloudEvent.time}`); console.log(`Event project: ${cloudEvent.project}`); console.log(`Event location: ${cloudEvent.location}`); console.log(`Database name: ${cloudEvent.database}`); console.log(`Document name: ${cloudEvent.document}`); // For withAuthContext events console.log(`Auth information: ${cloudEvent.authid}`); console.log(`Auth information: ${cloudEvent.authtype}`);
Python
print(f"Function triggered by change to: {cloud_event['source']}") print(f"Event type: {cloud_event['type']}") print(f"Event time: {cloud_event['time']}") print(f"Event project: {cloud_event['project']}") print(f"Location: {cloud_event['location']}") print(f"Database name: {cloud_event['database']}") print(f"Document: {cloud_event['document']}") // For withAuthContext events print(f"Auth information: {cloud_event['authid']}") print(f"Auth information: {cloud_event['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.
gcloud
-
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 YOUR_FUNCTION_NAME \ --gen2 \ --region=FUNCTION_LOCATION \ --trigger-location=TRIGGER_LOCATION \ --runtime=YOUR_RUNTIME \ --source=YOUR_SOURCE_LOCATION \ --entry-point=YOUR_CODE_ENTRYPOINT \ --trigger-event-filters="type=EVENT_FILTER_TYPE" \ --trigger-event-filters="database=DATABASE" \ --trigger-event-filters-path-pattern="document=DOCUMENT" \
Das erste Argument,
YOUR_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.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
gibt die Region an, in der die Funktion bereitgestellt werden soll.Legen Sie zum Maximieren der Nähe eine Region in der Nähe Ihrer Firestore-Datenbank fest. Wenn sich Ihre Firestore-Datenbank an einem multiregionalen Standort befindet, legen Sie für Datenbanken in
nam5
us-central1
und für Datenbanken ineur3
aufeurope-west4
fest. Legen Sie für regionale Firestore-Standorte dieselbe Region fest.Das Flag
--trigger-location
gibt den Speicherort des Triggers an. Sie müssen dieses Flag auf den Speicherort Ihrer Firestore-Datenbank festlegen.Das Flag
--runtime
gibt an, welche Sprachlaufzeit die Funktion verwendet. Cloud Functions unterstützt mehrere Laufzeiten. Weitere Informationen finden Sie unter Laufzeiten.Das Flag
--source
gibt den Speicherort des Quellcodes der Funktion an. Weitere Informationen dazu finden Sie hier:Das Flag
--entry-point
gibt den Einstiegspunkt für die Funktion in Ihrem Quellcode an. Dies ist der Code, der beim Ausführen der Funktion ausgeführt wird. Der Wert dieses Flags muss ein Funktionsname oder ein voll qualifizierter Klassenname sein, der in Ihrem Quellcode vorhanden ist. Weitere Informationen finden Sie unter Funktionseinstiegspunkt.EVENT_FILTER_TYPE
: Firestore unterstützt die folgenden Ereignistypen.google.cloud.firestore.document.v1.created
: Das Ereignis wird gesendet, wenn zum ersten Mal ein Dokument geschrieben wird.google.cloud.firestore.document.v1.updated
: Das Ereignis wird gesendet, wenn ein Dokument bereits vorhanden ist und sich ein Wert geändert hat.google.cloud.firestore.document.v1.deleted
: Das Ereignis wird gesendet, wenn ein Dokument gelöscht wird.google.cloud.firestore.document.v1.written
: Das Ereignis wird gesendet, wenn ein Dokument erstellt, aktualisiert oder gelöscht wird.google.cloud.firestore.document.v1.created.withAuthContext
: Das Ereignis wird gesendet, wenn ein Dokument zum ersten Mal geschrieben wird und das Ereignis zusätzliche Authentifizierungsinformationen enthält.google.cloud.firestore.document.v1.updated.withAuthContext
: Das Ereignis wird gesendet, wenn ein Dokument bereits vorhanden ist und sich ein Wert geändert hat. Enthält zusätzliche Authentifizierungsinformationengoogle.cloud.firestore.document.v1.deleted.withAuthContext
: Das Ereignis wird gesendet, wenn ein Dokument gelöscht wird. Enthält zusätzliche Authentifizierungsinformationengoogle.cloud.firestore.document.v1.written.withAuthContext
: Ereignis wird gesendet, wenn ein Dokument erstellt, aktualisiert oder gelöscht wird, sowie ein Ereignis. Enthält zusätzliche Authentifizierungsinformationen
DATABASE
: Firestore-Datenbank. Verwenden Sie(default)
als Standarddatenbanknamen.DOCUMENT
: der Datenbankpfad, der beim Erstellen, Aktualisieren oder Löschen von Daten Ereignisse auslöst. Als Operator kommen die folgenden Zeichen infrage:- Gleich. Beispiel:
--trigger-event-filters=document='users/marie'
- Pfadmuster. Beispiel:
--trigger-event-filters-path-pattern=document='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 zeigen 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-firestore-node \
--gen2 \
--region=us-west2 \
--trigger-location=us-west2 \
--runtime=nodejs18 \
--source=gs://CLOUD_STORAGE_BUCKET/firestoreEventFunction.zip \
--entry-point=makeUpperCase \
--trigger-event-filters=type=google.cloud.firestore.document.v1.written \
--trigger-event-filters=database='(default)' \
--trigger-event-filters-path-pattern=document='messages/{pushId}'
Stellen Sie eine Funktion für eine Datenbank am multiregionalen Standort nam5
bereit:
gcloud functions deploy gcfv2-trigger-firestore-python \
--gen2 \
--region=us-central1 \
--trigger-location=nam5 \
--runtime=python311 \
--source=gs://CLOUD_STORAGE_BUCKET/firestoreEventFunction.zip \
--entry-point=make_upper_case \
--trigger-event-filters=type=google.cloud.firestore.document.v1.written.withAuthContext \
--trigger-event-filters=database='(default)' \
--trigger-event-filters-path-pattern=document='messages/{pushId}'
Beschränkungen
Beachten Sie die folgenden Einschränkungen für Firestore-Trigger für Cloud Functions:
- Für Cloud Functions (1. Generation) ist eine vorhandene „(Standard)-Datenbank im nativen Modus von Firestore erforderlich. Er unterstützt weder benannte Firestore-Datenbanken noch den Datastore-Modus. Verwenden Sie in solchen Fällen Cloud Functions (2nd gen), 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 nicht automatisch die Trigger für diese Datenbank gelöscht. Der Trigger liefert 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 (1st gen) übertragen.
- Ereignisse, die aufgrund der Größe der Anfrage nicht zugestellt 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 ist, können Sie den tatsächlichen Ereignisinhalt ableiten. Lesen Sie dazu das betreffende Dokument mit einem Snapshot vor und nach dem Zeitstempel. - Um eine solche Uploadhäufigkeit zu vermeiden, können Sie Folgendes tun:
- Zu Cloud Functions (2nd gen) migrieren und upgraden
- Dokument verkleinern
- Betreffende Cloud Functions-Funktionen löschen
- Sie können die Protokollierung selbst mithilfe von Ausschlüssen deaktivieren. Die betreffenden Ereignisse werden jedoch nicht gesendet.
Eventarc- und Firestore-Standorte
Eventarc unterstützt keine Mehrfachregionen für Firestore-Ereignistrigger. Sie können jedoch 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 |
Unterschiede zwischen Cloud Functions (2. Generation und 1. Generation)
Cloud Functions (2nd gen) verwendet Eventarc-Ereignisse für alle Laufzeiten. Bisher hat Cloud Functions (1. Generation) Eventarc-Ereignisse nur für einige Laufzeiten verwendet. Eventarc-Ereignisse bringen die folgenden Unterschiede zu Cloud Functions (1st gen) mit sich.
Die Firestore-Trigger für Eventarc unterstützen neben Cloud Functions weitere Ziele. Sie können
CloudEvents
an eine Reihe von Zielen weiterleiten, einschließlich, aber nicht beschränkt auf Cloud Run, GKE und Workflows.Firestore-Trigger für Eventarc rufen die Triggerdefinition zu Beginn eines Datenbankschreibvorgangs ab und entscheiden anhand dieser Definition, ob Firestore ein Ereignis ausgeben soll. Der Schreibvorgang berücksichtigt keine Änderungen an der Triggerdefinition, die während der Ausführung vorgenommen werden könnten.
Cloud Functions (1. Generation) ruft die Triggerdefinition während der Auswertung des Datenbankschreibvorgangs ab. Änderungen am Trigger während der Bewertung können sich darauf auswirken, ob Firestore ein Ereignis ausgibt.
Weitere Informationen finden Sie im Vergleich der Cloud Functions-Versionen.