Mit Cloud-Funktionen können Sie Ereignisse im Cloud Firestore verarbeiten, ohne den Clientcode aktualisieren zu müssen. Sie können Cloud Firestore-Änderungen über die DocumentSnapshot
Oberfläche oder über das Admin-SDK vornehmen.
In einem typischen Lebenszyklus führt eine Cloud Firestore-Funktion Folgendes aus:
- Wartet auf Änderungen an einem bestimmten Dokument.
- Wird ausgelöst, wenn ein Ereignis auftritt und seine Aufgaben ausführt (Beispiele für Anwendungsfälle finden Sie unter Was kann ich mit Cloud-Funktionen tun? ).
- Empfängt ein Datenobjekt, das eine Momentaufnahme der im angegebenen Dokument gespeicherten Daten enthält. Bei
onWrite
oderonUpdate
Ereignissen enthält das Datenobjekt zwei Snapshots, die den Datenstatus vor und nach dem auslösenden Ereignis darstellen.
Die Entfernung zwischen dem Speicherort der Firestore-Instanz und dem Speicherort der Funktion kann zu einer erheblichen Netzwerklatenz führen. Um die Leistung zu optimieren, sollten Sie gegebenenfalls den Funktionsort angeben.
Die Cloud Firestore-Funktion wird ausgelöst
Das Cloud-Funktionen für Firebase SDK exportiert ein functions.firestore
Objekt, mit dem Sie Handler erstellen können, die an bestimmte Cloud Firestore-Ereignisse gebunden sind.
Ereignistyp | Auslösen |
---|---|
onCreate | Wird ausgelöst, wenn zum ersten Mal in ein Dokument geschrieben wird. |
onUpdate | Wird ausgelöst, wenn ein Dokument bereits vorhanden ist und ein Wert geändert wurde. |
onDelete | Wird ausgelöst, wenn ein Dokument mit Daten gelöscht wird. |
onWrite | onCreate ausgelöst, wenn onCreate , onUpdate oder onDelete ausgelöst wird. |
Wenn Sie noch kein Projekt für Cloud-Funktionen für Firebase aktiviert haben, lesen Sie Erste Schritte: Schreiben und Bereitstellen Ihrer ersten Funktionen , um Ihr Cloud-Funktionen für Firebase-Projekt zu konfigurieren und einzurichten.
Schreiben von durch Cloud Firestore ausgelösten Funktionen
Definieren Sie einen Funktionsauslöser
Geben Sie einen Dokumentpfad und einen Ereignistyp an, um einen Cloud Firestore-Trigger zu definieren:
Node.js
const functions = require('firebase-functions');
exports.myFunction = functions.firestore
.document('my-collection/{docId}')
.onWrite((change, context) => { /* ... */ });
Dokumentpfade können entweder auf ein bestimmtes Dokument oder auf ein Platzhaltermuster verweisen.
Geben Sie ein einzelnes Dokument an
Wenn Sie ein Ereignis für eine Änderung an einem bestimmten Dokument auslösen möchten, können Sie die folgende Funktion verwenden.
Node.js
// Listen for any change on document `marie` in collection `users` exports.myFunctionName = functions.firestore .document('users/marie').onWrite((change, context) => { // ... Your code here });
Geben Sie eine Gruppe von Dokumenten mithilfe von Platzhaltern an
Wenn Sie einer Gruppe von Dokumenten, z. B. einem Dokument in einer bestimmten Sammlung, einen Auslöser hinzufügen möchten, verwenden Sie anstelle der Dokument-ID einen {wildcard}
:
Node.js
// Listen for changes in all documents in the 'users' collection exports.useWildcard = functions.firestore .document('users/{userId}') .onWrite((change, context) => { // If we set `/users/marie` to {name: "Marie"} then // context.params.userId == "marie" // ... and ... // change.after.data() == {name: "Marie"} });
Wenn in diesem Beispiel ein Feld in einem Dokument in users
geändert wird, entspricht es einem Platzhalter namens userId
.
Wenn ein Dokument in users
Untersammlungen enthält und ein Feld in einem der Dokumente dieser userId
geändert wird, wird der userId
nicht ausgelöst.
Platzhalterübereinstimmungen werden aus dem Dokumentpfad extrahiert und in context.params
gespeichert. Sie können beliebig viele Platzhalter definieren, um explizite Sammlungs- oder Dokument-IDs zu ersetzen. Beispiel:
Node.js
// Listen for changes in all documents in the 'users' collection and all subcollections exports.useMultipleWildcards = functions.firestore .document('users/{userId}/{messageCollectionId}/{messageId}') .onWrite((change, context) => { // If we set `/users/marie/incoming_messages/134` to {body: "Hello"} then // context.params.userId == "marie"; // context.params.messageCollectionId == "incoming_messages"; // context.params.messageId == "134"; // ... and ... // change.after.data() == {body: "Hello"} });
Ereignisauslöser
Lösen Sie eine Funktion aus, wenn ein neues Dokument erstellt wird
Sie können eine Funktion auslösen, die jedes Mal ausgelöst wird, wenn ein neues Dokument in einer Sammlung erstellt wird, indem Sie einen onCreate()
Handler mit einem Platzhalter verwenden . Diese Beispielfunktion ruft jedes Mal, wenn ein neues Benutzerprofil hinzugefügt wird, createUser
:
Node.js
exports.createUser = functions.firestore .document('users/{userId}') .onCreate((snap, context) => { // Get an object representing the document // e.g. {'name': 'Marie', 'age': 66} const newValue = snap.data(); // access a particular field as you would any JS property const name = newValue.name; // perform desired operations ... });
Lösen Sie eine Funktion aus, wenn ein Dokument aktualisiert wird
Sie können auch eine Funktion auslösen, die ausgelöst wird, wenn ein Dokument mithilfe der Funktion onUpdate()
mit einem Platzhalter aktualisiert wird. Diese Beispielfunktion ruft updateUser
wenn ein Benutzer sein Profil ändert:
Node.js
exports.updateUser = functions.firestore .document('users/{userId}') .onUpdate((change, context) => { // Get an object representing the document // e.g. {'name': 'Marie', 'age': 66} const newValue = change.after.data(); // ...or the previous value before this update const previousValue = change.before.data(); // access a particular field as you would any JS property const name = newValue.name; // perform desired operations ... });
Lösen Sie eine Funktion aus, wenn ein Dokument gelöscht wird
Sie können eine Funktion auch auslösen, wenn ein Dokument mithilfe der Funktion onDelete()
mit einem Platzhalter gelöscht wird. Diese Beispielfunktion ruft deleteUser
wenn ein Benutzer sein Benutzerprofil löscht:
Node.js
exports.deleteUser = functions.firestore .document('users/{userID}') .onDelete((snap, context) => { // Get an object representing the document prior to deletion // e.g. {'name': 'Marie', 'age': 66} const deletedValue = snap.data(); // perform desired operations ... });
Lösen Sie eine Funktion für alle Änderungen an einem Dokument aus
Wenn Sie sich nicht für die Art des Ereignisses interessieren, das ausgelöst wird, können Sie mithilfe der Funktion onWrite()
mit einem Platzhalter auf alle Änderungen in einem Cloud Firestore-Dokument onWrite()
. Diese Beispielfunktion ruft modifyUser
wenn ein Benutzer erstellt, aktualisiert oder gelöscht wird:
Node.js
exports.modifyUser = functions.firestore .document('users/{userID}') .onWrite((change, context) => { // Get an object with the current document value. // If the document does not exist, it has been deleted. const document = change.after.exists ? change.after.data() : null; // Get an object with the previous document value (for update or delete) const oldDocument = change.before.data(); // perform desired operations ... });
Daten lesen und schreiben
Wenn eine Funktion ausgelöst wird, wird eine Momentaufnahme der Daten bereitgestellt, die sich auf das Ereignis beziehen. Mit diesem Snapshot können Sie aus dem Dokument lesen oder in das Dokument schreiben, das das Ereignis ausgelöst hat, oder mit dem Firebase Admin SDK auf andere Teile Ihrer Datenbank zugreifen.
Ereignisdaten
Daten lesen
Wenn eine Funktion ausgelöst wird, möchten Sie möglicherweise Daten aus einem Dokument abrufen, das aktualisiert wurde, oder die Daten vor der Aktualisierung abrufen. Sie können die vorherigen Daten mithilfe von change.before.data()
, das den Dokumentschnappschuss vor dem Update enthält. In ähnlicher change.after.data()
enthält change.after.data()
den Dokument-Snapshot-Status nach der Aktualisierung.
Node.js
exports.updateUser2 = functions.firestore .document('users/{userId}') .onUpdate((change, context) => { // Get an object representing the current document const newValue = change.after.data(); // ...or the previous value before this update const previousValue = change.before.data(); });
Sie können wie in jedem anderen Objekt auf Eigenschaften zugreifen. Alternativ können Sie die get
Funktion verwenden, um auf bestimmte Felder zuzugreifen:
Node.js
// Fetch data using standard accessors const age = snap.data().age; const name = snap.data()['name']; // Fetch data using built in accessor const experience = snap.get('experience');
Daten schreiben
Jeder Funktionsaufruf ist einem bestimmten Dokument in Ihrer Cloud Firestore-Datenbank zugeordnet. Sie können auf dieses Dokument als DocumentReference
in der ref
Eigenschaft des an Ihre Funktion zurückgegebenen Snapshots zugreifen.
Diese DocumentReference
stammt aus dem SDK des Cloud Firestore Node.js und enthält Methoden wie update()
, set()
und remove()
sodass Sie das Dokument, das die Funktion ausgelöst hat, problemlos ändern können.
Node.js
// Listen for updates to any `user` document. exports.countNameChanges = functions.firestore .document('users/{userId}') .onUpdate((change, context) => { // Retrieve the current and previous value const data = change.after.data(); const previousData = change.before.data(); // We'll only update if the name has changed. // This is crucial to prevent infinite loops. if (data.name == previousData.name) { return null; } // Retrieve the current count of name changes let count = data.name_change_count; if (!count) { count = 0; } // Then return a promise of a set operation to update the count return change.after.ref.set({ name_change_count: count + 1 }, {merge: true}); });
Daten außerhalb des Triggerereignisses
Cloud-Funktionen werden in einer vertrauenswürdigen Umgebung ausgeführt. Dies bedeutet, dass sie als Dienstkonto für Ihr Projekt autorisiert sind. Mit dem Firebase Admin SDK können Sie Lese- und Schreibvorgänge ausführen:
Node.js
const admin = require('firebase-admin');
admin.initializeApp();
const db = admin.firestore();
exports.writeToFirestore = functions.firestore
.document('some/doc')
.onWrite((change, context) => {
db.doc('some/otherdoc').set({ ... });
});
Einschränkungen und Garantien
Cloud Firestore-Trigger für Cloud-Funktionen sind eine Beta-Funktion mit einigen bekannten Einschränkungen:
- Es kann bis zu 10 Sekunden dauern, bis eine Funktion auf Änderungen im Cloud Firestore reagiert.
- Die Bestellung ist nicht garantiert. Schnelle Änderungen können Funktionsaufrufe in unerwarteter Reihenfolge auslösen.
- Ereignisse werden mindestens einmal ausgeliefert, aber ein einzelnes Ereignis kann zu mehreren Funktionsaufrufen führen. Vermeiden Sie es, von genau einmaligen Mechaniken abhängig zu sein, und schreiben Sie idempotente Funktionen .
- Cloud Firestore-Trigger für Cloud-Funktionen sind nur für Cloud Firestore im Native-Modus verfügbar. Es ist nicht für Cloud Firestore im Datenspeichermodus verfügbar.