Mit Cloud Functions (2nd gen) erweitern
Mit Cloud Functions können Sie Code bereitstellen, um ausgelöste Ereignisse zu verarbeiten durch Änderungen in Ihrer Firestore-Datenbank. So können Sie ohne eigene Server betreiben zu müssen.
Firestore mit Cloud Functions (2nd gen) erweitern
Cloud Functions (2nd gen) unterstützt das folgende Firestore-Ereignis Trigger, mit denen Sie Handler erstellen können, die an Firestore-Ereignisse gebunden 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 ausgelöst zu Dokumentänderungen. Eine Aktualisierung eines Firestore-Dokuments, in der Daten unverändert ist (ein No-Op-Schreibvorgang) generiert kein Aktualisierungs- oder Schreibereignis. Es ist ist es nicht möglich, bestimmten Feldern Ereignisse hinzuzufügen.
Authentifizierungskontext in das Ereignis aufnehmen
Verwenden Sie ein Ereignis, um zusätzliche Authentifizierungsinformationen für das Ereignis anzugeben.
mit der Erweiterung withAuthContext
auslösen. Mit dieser Erweiterung werden zusätzliche
Informationen zum Hauptkonto, das das Ereignis ausgelöst hat. Die Funktion fügt die
authtype
- und authid
-Attribute zusätzlich zu den zurückgegebenen Informationen
das Basisereignis. Weitere Informationen finden Sie in der
In der Referenz authcontext
finden Sie weitere Informationen zu Attributwerten.
Durch Firestore ausgelöste Funktion schreiben
Um eine Funktion zu schreiben, die auf Firestore-Ereignisse reagiert, Bereiten Sie sich vor, um während der Bereitstellung Folgendes anzugeben:
- 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 festlegen, können Sie entweder ein genaues Dokument
oder ein Pfadmuster sein. Verwenden Sie ein Pfadmuster für den Abgleich mehrerer Dokumente mit
Platzhaltern, *
oder **
.
Sie können beispielsweise auf Änderungen am folgenden Dokument reagieren:
users/marie
Verwenden Sie Platzhalter wie *
oder **
, um auf Änderungen in Dokumenten zu reagieren
die einem Muster entsprechen. Der Platzhalter *
entspricht einem einzelnen Segment und
Der Platzhalter **
aus mehreren Segmenten stimmt mit null oder mehr Segmenten im Muster überein.
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, weil {messageCollectionId=*}
ist eine Sammlung. users/{userId=*}/{messageCollectionId}/{messageId=*}
ist jedoch
gültig, weil {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 value
und
old_value
-Feldern.
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 ein Dokument vor dem Vorgang enthält. Snapshot. 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.
Verwenden Sie protobufjs, um die Ereignisdaten zu decodieren. 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 konvertiert, die in das Feld original
einer
betroffene Dokumente in Großbuchstaben und schreibt den neuen Wert in dasselbe Dokument:
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.
Verwenden Sie protobufjs, um die Ereignisdaten zu decodieren. 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 den Firestore-data.proto
angeben
im Quellverzeichnis für Ihre Funktion. Diese Datei importiert Folgendes
Protos, die Sie auch in Ihr Quellverzeichnis aufnehmen müssen:
Verwenden Sie für die Abhängigkeiten dieselbe Verzeichnisstruktur. Beispiel:
struct.proto
in google/protobuf
.
Diese Dateien werden benötigt, um Ereignisdaten zu decodieren. Wenn Ihre Funktionsquelle diese Dateien nicht enthält, wird bei der Ausführung ein Fehler zurückgegeben.
Ereignisattribute
Jedes Ereignis enthält Datenattribute die Informationen zum Ereignis enthalten, z. B. die Uhrzeit, zu der das Ereignis ausgelöst wurde. Firestore fügt zusätzliche Daten zur Datenbank und zum Dokument hinzu die an dem Ereignis beteiligt sind. 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 bereitstellen oder in der Google Cloud Console. Das folgende Beispiel zeigt die Bereitstellung mit über die gcloud CLI. Weitere Informationen zur Bereitstellung mit der Google Cloud Console Siehe Cloud Functions-Funktionen bereitstellen
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.
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 eine Region in der Nähe Ihres Firestore fest, um die Nähe zu maximieren. Datenbank. Wenn sich Ihre Firestore-Datenbank an einem multiregionalen Standort befindet Speicherort, für Datenbanken in
nam5
aufus-central1
und aufeurope-west4
für Datenbanken ineur3
. Für regionale Firestore-Standorte, die auf dieselbe Region festgelegt sind.Die
--trigger-location
gibt den Standort des Triggers an. Sie müssen dieses Flag auf die Speicherort Ihrer Firestore-Datenbank.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: für weitere Informationen: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
: Ereignis wird gesendet, wenn ein in das Dokument zum ersten Mal geschrieben wird.google.cloud.firestore.document.v1.updated
: Ereignis wird gesendet, wenn ein Dokument ist bereits vorhanden und hat sich ein Wert geändert.google.cloud.firestore.document.v1.deleted
: Ereignis wird gesendet, wenn ein Dokument gelöscht.google.cloud.firestore.document.v1.written
: Ereignis wird gesendet, wenn ein Dokument erstellt, aktualisiert oder gelöscht wird.google.cloud.firestore.document.v1.created.withAuthContext
: Ereignis wird gesendet, wenn ein in das Dokument zum ersten Mal geschrieben wird und das Ereignis zusätzliche Authentifizierungsinformationen enthält.google.cloud.firestore.document.v1.updated.withAuthContext
: Ereignis wird gesendet, wenn ein Dokument ist bereits vorhanden und hat sich ein Wert geändert. Enthält zusätzliche Authentifizierungsinformationengoogle.cloud.firestore.document.v1.deleted.withAuthContext
: Ereignis wird gesendet, wenn ein Dokument gelöscht. Enthält zusätzliche Authentifizierungsinformationengoogle.cloud.firestore.document.v1.written.withAuthContext
: Ereignis wird gesendet, wenn ein Dokument erstellt, aktualisiert oder gelöscht wird. Enthält zusätzliche Authentifizierungsinformationen
DATABASE
: Firestore-Datenbank. Verwenden Sie(default)
als Standarddatenbanknamen.DOCUMENT
: der Datenbankpfad, der Löst Ereignisse aus, wenn Daten erstellt, aktualisiert oder gelöscht. 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 ein vorhandener „(Standard)“ erforderlich im nativen Modus von Firestore verwenden. Nicht unterstützen benannte Firestore-Datenbanken oder den Datastore-Modus. Verwenden Sie Cloud Functions (2. Generation), um in solchen Fällen 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. Die Der Trigger liefert keine Ereignisse mehr. Er bleibt jedoch bestehen, bis Sie den Trigger löschen.
- Überschreitet ein übereinstimmendes Ereignis die maximale Anfragegröße, wird das Ereignis
wird möglicherweise nicht an Cloud Functions (1st gen) gesendet.
- Ereignisse, die aufgrund der Größe der Anfrage nicht zugestellt wurden, 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
befindet sich immer noch in einer Stunde, können Sie ableiten, des Veranstaltungsinhalts ansehen, indem Sie das entsprechende Dokument mit einem Snapshot vor und nach dem Zeitstempel. - So kannst du einen solchen Ablauf vermeiden:
<ph type="x-smartling-placeholder">
- </ph>
- Zu Cloud Functions (2nd gen) migrieren und upgraden
- Dokument verkleinern
- Betreffende Cloud Functions-Funktionen löschen
- Sie können das Logging selbst mithilfe von Ausschlüssen deaktivieren. Beachten Sie jedoch, dass die betreffenden Ereignisse dennoch nicht übermittelt werden.
Eventarc- und Firestore-Standorte
Eventarc unterstützt keine Mehrfachregionen für Firestore-Ereignisse Trigger, aber Sie können trotzdem Trigger für Firestore-Datenbanken erstellen an multiregionalen Standorten. Eventarc-Zuordnung in Firestore Multiregionale Standorte in die folgenden Eventarc-Regionen:
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 für nur einige Laufzeiten. Eventarc-Ereignisse führen zu folgenden Unterschieden Cloud Functions (1. Generation)
Die Firestore-Trigger für die Eventarc-Unterstützung zusätzliche Ziele neben Cloud Functions. Du kannst
CloudEvents
. mit einer Reihe von Zielen, darunter: aber nicht beschränkt auf Cloud Run, GKE und WorkflowsFirestore-Trigger für Eventarc rufen die Triggerdefinition zu Beginn eines Datenbankschreibvorgangs um zu entscheiden, ob Firestore ein Ereignis ausgeben soll. Die Beim Schreibvorgang werden keine Änderungen an der Triggerdefinition berücksichtigt. was während der Ausführung passieren kann.
Cloud Functions (1st gen) ruft die Triggerdefinition während der Auswertung des Datenbankschreibvorgangs und Änderungen am Trigger während kann sich darauf auswirken, ob Firestore ein Ereignis ausgibt oder nicht.
Weitere Informationen finden Sie im Vergleich der Cloud Functions-Versionen.