Cloud Firestore wird ausgelöst

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:

1. Wartet auf Änderungen an einem bestimmten Dokument.
2. 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? ).
3. Empfängt ein Datenobjekt, das eine Momentaufnahme der im angegebenen Dokument gespeicherten Daten enthält. Bei onWrite oder onUpdate 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.

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:

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.

// Listen for any change on document `marie` in collection `users`
exports.myFunctionName = functions.firestore
    .document('users/marie').onWrite((change, context) => {
      // ... Your code here
    });
index.js

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} :

// 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"}
    });
index.js

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:

// 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"}
    });
index.js

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 :

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 ...
    });
index.js

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:

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 ...
    });
index.js

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:

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 ...
    });
index.js

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:

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 ...
    });
index.js

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.

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();
    });
index.js

Sie können wie in jedem anderen Objekt auf Eigenschaften zugreifen. Alternativ können Sie die get Funktion verwenden, um auf bestimmte Felder zuzugreifen:

// 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');
index.js

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.

// 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});
    });
index.js

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:

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.