Cloud Firestore-Trigger

Mit Cloud Functions können Sie Ereignisse in Cloud Firestore verarbeiten, ohne den Clientcode aktualisieren zu müssen. Sie können Cloud - Firestor Änderungen über das machen DocumentSnapshot Schnittstelle oder über die Admin SDK .

In einem typischen Lebenszyklus führt eine Cloud Firestore-Funktion Folgendes aus:

  1. Wartet auf Änderungen an einem bestimmten Dokument.
  2. Trigger , wenn ein Ereignis auftritt , und führt seine Aufgaben (siehe Was kann ich mit Cloud - Funktionen tun? Beispiele für Anwendungsfälle).
  3. Empfängt ein Datenobjekt, das eine Momentaufnahme der im angegebenen Dokument gespeicherten Daten enthält. Für onWrite oder onUpdate Ereignisse enthält das Datenobjekt zwei Schnappschüsse , die den Datenzustand vor und nach dem auslösenden Ereignis darstellen.

Die Entfernung zwischen dem Standort der Firestore-Instanz und dem Standort der Funktion kann zu erheblichen Netzwerklatenzen führen. Zur Optimierung der Leistung, sollten Sie die Angabe Funktion Ort , wo anwendbar.

Auslöser der Cloud Firestore-Funktion

Die Cloud - Funktionen für die Firebase SDK exportieren ein functions.firestore Objekt , das Sie Handler gebunden an bestimmten Cloud - Firestor Ereignisse erstellen kann.

Ereignistyp Abzug
onCreate Wird ausgelöst, wenn ein Dokument zum ersten Mal beschrieben wird.
onUpdate Wird ausgelöst, wenn ein Dokument bereits vorhanden ist und sich ein Wert geändert hat.
onDelete Wird ausgelöst, wenn ein Dokument mit Daten gelöscht wird.
onWrite Ausgelöst , wenn onCreate , onUpdate oder onDelete ausgelöst wird.

Wenn Sie für Cloud - Funktionen für die Firebase noch nicht aktiviert ein Projekt haben, dann lesen Erste Schritte: Schreiben und Bereitstellen Ihre erste Funktionen zur Konfiguration und richten Sie Ihre Cloud - Funktionen für die Firebase - Projekt.

Von Cloud Firestore ausgelöste Funktionen schreiben

Definieren Sie einen Funktionstrigger

Geben Sie zum Definieren eines Cloud Firestore-Triggers einen Dokumentpfad und einen Ereignistyp an:

Node.js

const functions = require('firebase-functions');

exports.myFunction = functions.firestore
  .document('my-collection/{docId}')
  .onWrite((change, context) => { /* ... */ });

Dokumentenpfade können entweder ein Bezug bestimmtes Dokuments oder ein Platzhalter - Musters .

Geben Sie ein einzelnes Dokument an

Wenn Sie ein Ereignis für jede Änderung zu einem bestimmten Dokument auslösen wollen , dann 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 mit Platzhaltern an

Wenn Sie einen Trigger auf eine Gruppe von Dokumenten, wie jedes Dokument in einer bestimmten Sammlung anhängen möchten, dann verwenden Sie ein {wildcard} anstelle der Dokument - ID:

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"}
    });

In diesem Beispiel , wenn alle Felder auf jedes beliebige Dokument in users geändert wird, passt es eine Wildcard genannt userId .

Wenn ein Dokument in users Subkollektionen hat, und ein Feld in einem dieser Subkollektionen Dokumente geändert wird, die userId wird Wildcard nicht ausgelöst.

Wildcard Spiele werden aus dem Dokumentenpfad extrahiert und in gespeicherte context.params . Sie können beliebig viele Platzhalter definieren, um explizite Sammlungs- oder Dokument-IDs zu ersetzen, zum 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

Eine Funktion auslösen, wenn ein neues Dokument erstellt wird

Sie können eine Funktion auslösen jederzeit ein neues Dokument in einer Sammlung erstellt wird Feuer durch einen mit onCreate() Handler mit einer Wildcard . Dieses Beispiel Funktion ruft createUser jedes Mal , wenn ein neues Benutzerprofil hinzugefügt:

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

Auslösen einer Funktion, wenn ein Dokument aktualisiert wird

Sie können auch eine Funktion Feuer auslösen , wenn ein Dokument , das die Aktualisierung mit onUpdate() Funktion mit einem Platzhalter . Dieses Beispiel Funktion 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 ...
    });

Beim Löschen eines Dokuments eine Funktion auslösen

Sie können auch eine Funktion ausgelöst werden, wenn ein Dokument , das gelöscht wird , mit onDelete() mit einer Funktion Wildcard . Diese Beispiel - Funktion aufruft deleteUser , wenn ein Benutzer ihr 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 ...
    });

Eine Funktion für alle Änderungen an einem Dokument auslösen

Wenn Sie nicht über die Art der Veranstaltung ist es egal Entlassung, können Sie für alle Änderungen in einem Wolke Firestor Dokument hören mit der onWrite() mit einer Funktion Wildcard . Diese Beispiel - Funktion aufruft modifyUser wenn ein Benutzer erstellt, aktualisiert oder gelöscht werden :

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

Lesen und Schreiben von Daten

Wenn eine Funktion ausgelöst wird, liefert sie eine Momentaufnahme der Daten in Bezug auf das Ereignis. Sie können diesen Snapshot verwenden, um aus dem Dokument zu lesen oder zu schreiben, das das Ereignis ausgelöst hat, oder das Firebase Admin SDK verwenden, um auf andere Teile Ihrer Datenbank zuzugreifen.

Ereignisdaten

Daten lesen

Wenn eine Funktion ausgelöst wird, möchten Sie möglicherweise Daten aus einem aktualisierten Dokument abrufen oder die Daten vor der Aktualisierung abrufen. Sie können die vorherigen Daten erhalten , indem mit change.before.data() , die das Dokument Snapshot vor dem Update enthält. In ähnlicher Weise change.after.data() enthält das Dokument Snapshot - Zustand nach dem Update.

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 auf Eigenschaften wie auf jedes andere Objekt zugreifen. Alternativ können Sie das verwenden get Funktion für den Zugriff bestimmter Bereiche:

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');

Schreiben von Daten

Jeder Funktionsaufruf ist einem bestimmten Dokument in Ihrer Cloud Firestore-Datenbank zugeordnet. Sie können dieses Dokument als Zugang DocumentReference in der ref Eigenschaft der auf Ihre Funktion zurückzuMomentAufnahme.

Das DocumentReference stammt aus der Wolke Firestor Node.js SDK und umfasst Methoden wie update() , set() und remove() , so können Sie einfach das Dokument ändern, das die Funktion ausgelöst.

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 Functions werden in einer vertrauenswürdigen Umgebung ausgeführt, d. h. sie sind als Dienstkonto für Ihr Projekt autorisiert. Sie können ausführen liest und schreibt die Verwendung von Firebase Admin SDK :

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

Beachten Sie die folgenden Einschränkungen für Cloud Firestore-Trigger für Cloud Functions:

  • Die Bestellung ist nicht garantiert. Schnelle Änderungen können Funktionsaufrufe in unerwarteter Reihenfolge auslösen.
  • Ereignisse werden mindestens einmal zugestellt, aber ein einzelnes Ereignis kann zu mehreren Funktionsaufrufen führen. Vermeiden Sie je nach genau einmal Mechanik und Schreib Idempotent Funktionen .
  • Cloud Firestor Auslöser für Cloud - Funktionen ist nur für Cloud Firestor in einheitlichem Modus . Sie ist für Cloud Firestore im Datastore-Modus nicht verfügbar.