Wyzwalacze Cloud Firestore

Dzięki Cloud Functions możesz obsługiwać zdarzenia w Cloud Firestore bez konieczności aktualizowania kodu klienta. Można dokonać zmiany Chmura FireStore pośrednictwem DocumentSnapshot interfejs lub za pośrednictwem Admin SDK .

W typowym cyklu życia funkcja Cloud Firestore wykonuje te czynności:

1. Czeka na zmiany w konkretnym dokumencie.
2. Wyzwalacze, gdy wystąpi zdarzenie i wykonuje swoje zadania (patrz Co mogę zrobić z funkcji Cloud przykłady przypadków użycia).
3. Odbiera obiekt danych zawierający migawkę danych przechowywanych w określonym dokumencie. Dla onWrite lub onUpdate zdarzeń, obiekt danych zawiera dwie migawki, które przedstawiają stan danych przed i po zdarzeniu wyzwalającym.

Odległość między lokalizacją instancji Firestore a lokalizacją funkcji może powodować znaczne opóźnienia w sieci. Aby zoptymalizować wydajność, należy rozważyć określając lokalizację funkcji gdzie stosowne.

Wyzwalacze funkcji Cloud Firestore

Funkcje Chmura Firebase SDK eksportuje functions.firestore obiekt, który pozwala na tworzenie procedur obsługi związane z konkretnymi wydarzeniami Chmura FireStore.

Jeśli nie masz projektu włączono funkcji Chmura Firebase jeszcze, a następnie odczytać zacząć: napisać i wdrożyć pierwsze funkcje , aby skonfigurować i ustawić swoje funkcje Chmura dla projektu Firebase.

Pisanie funkcji uruchamianych przez Cloud Firestore

Zdefiniuj wyzwalacz funkcji

Aby zdefiniować wyzwalacz Cloud Firestore, określ ścieżkę dokumentu i typ zdarzenia:

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

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

Ścieżki dokument może odwołać albo dokument specyficzny lub wieloznaczny wzór .

Określ jeden dokument

Jeśli chcesz wyzwolić zdarzenie dla każdej zmiany do dokumentu określonego następnie można użyć następujących funkcji.

// 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

Określ grupę dokumentów za pomocą symboli wieloznacznych

Jeśli chcesz dołączyć do grupy spust dokumentów, takich jak wszelkiego rodzaju dokumentów w pewnej kolekcji, a następnie użyć {wildcard} zamiast identyfikatora dokumentu:

// 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

W tym przykładzie, gdy każde pole na dowolnym dokumencie w users zostanie zmieniony, to pasuje do wieloznaczny o nazwie userId .

Jeśli dokument w users ma podzbiorów, a pola w jednym z dokumentów tych podzbiorów zostanie zmieniona, userId wieloznaczny nie jest wyzwalany.

Wieloznaczne mecze są wyodrębniane ze ścieżki dokumentów i przechowywane w context.params . Możesz zdefiniować tyle symboli wieloznacznych, ile chcesz, aby zastąpić jawne identyfikatory kolekcji lub dokumentów, na przykład:

// 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

Wyzwalacze zdarzeń

Uruchom funkcję po utworzeniu nowego dokumentu

Można wywołać funkcję do ognia w każdej chwili nowy dokument jest tworzony w kolekcji przy użyciu onCreate() obsługi z zamiennika . Ten przykład funkcja zwraca createUser za każdym razem nowy profil użytkownika w brzmieniu:

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

Uruchom funkcję, gdy dokument zostanie zaktualizowany

Można również wywołać funkcję do ognia, gdy dokument jest aktualizowany przy użyciu onUpdate() funkcji z zamiennika . Ten przykład funkcja zwraca updateUser jeśli użytkownik zmieni swój profil:

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

Uruchom funkcję po usunięciu dokumentu

Można również wywołać funkcję, gdy dokument jest usuwany za pomocą onDelete() funkcji z zamiennika . Ten przykład funkcja zwraca deleteUser gdy użytkownik usunie swój profil użytkownika:

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

Uruchom funkcję dla wszystkich zmian w dokumencie

Jeśli nie dbają o rodzaju zdarzenia wyrzuceniu, można słuchać do wszystkich zmian w dokumencie Chmura FireStore wykorzystaniem onWrite() funkcji z zamiennika . Ten przykład funkcja zwraca modifyUser jeśli użytkownik jest tworzony, zaktualizowane lub usunięte:

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

Odczytywanie i zapisywanie danych

Gdy funkcja zostanie wyzwolona, ​​zapewnia migawkę danych związanych ze zdarzeniem. Możesz użyć tego zrzutu, aby odczytywać lub zapisywać w dokumencie, który wyzwolił zdarzenie, albo użyć pakietu Firebase Admin SDK, aby uzyskać dostęp do innych części bazy danych.

Dane zdarzenia

Czytanie danych

Gdy funkcja zostanie wyzwolona, ​​możesz chcieć pobrać dane z dokumentu, który został zaktualizowany, lub uzyskać dane przed aktualizacją. Można uzyskać wcześniejsze dane za pomocą change.before.data() , która zawiera migawkę dokumentu przed aktualizacją. Podobnie change.after.data() zawiera stan migawki dokument po aktualizacji.

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

Możesz uzyskać dostęp do właściwości tak jak w każdym innym obiekcie. Alternatywnie, można użyć get funkcję dostępu do poszczególnych pól:

// 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

Zapisywanie danych

Każde wywołanie funkcji jest powiązane z konkretnym dokumentem w Twojej bazie danych Cloud Firestore. Możesz uzyskać dostęp do tego dokumentu jako DocumentReference w ref własności migawce powrócił do swojej funkcji.

Ten DocumentReference pochodzi z cloud FireStore node.js SDK i zawiera metody takie jak update() , set() i remove() , dzięki czemu można łatwo zmodyfikować dokument, który wywołał funkcję.

// 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

Dane poza zdarzeniem wyzwalającym

Funkcje Cloud Functions działają w zaufanym środowisku, co oznacza, że ​​są autoryzowane jako konto usługi w Twoim projekcie. Można wykonywać odczytuje i zapisuje za pomocą Firebase Admin SDK :

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

Ograniczenia

Zwróć uwagę na następujące ograniczenia wyzwalaczy Cloud Firestore dla Cloud Functions:

• Zamówienie nie jest gwarantowane. Szybkie zmiany mogą wyzwalać wywołania funkcji w nieoczekiwanej kolejności.
• Zdarzenia są dostarczane co najmniej raz, ale jedno zdarzenie może skutkować wieloma wywołaniami funkcji. Uniknąć zależności od dokładnie jednokrotnego mechaniki i napisać funkcji idempotent .
• Wyzwalacze chmura FireStore dla funkcji chmury jest dostępny tylko dla chmurze FireStore w trybie macierzystym . Nie jest dostępna w Cloud Firestore w trybie Datastore.