Aktywatory Cloud Firestore


Dzięki Cloud Functions możesz obsługiwać zdarzenia w Cloud Firestore bez konieczności aktualizowania kodu klienta. Zmiany w Cloud Firestore możesz wprowadzić za pomocą interfejsu zrzutów dokumentów lub pakietu Admin SDK.

W typowym cyklu życia funkcja Cloud Firestore wykonuje te działania:

  1. Oczekiwanie na zmiany w określonym dokumencie.
  2. Wyzwalacz, gdy nastąpi zdarzenie i wykona ono swoje zadania.
  3. Otrzymuje obiekt danych zawierający migawkę danych przechowywanych w określonym dokumencie. W przypadku zdarzeń zapisu lub aktualizacji obiekt danych zawiera 2 zrzuty, które reprezentują stan danych przed zdarzeniem aktywującym i po nim.

Odległość między lokalizacją instancji Firestore a lokalizacją funkcji może powodować duże opóźnienia w sieci. Aby zoptymalizować wydajność, określ lokalizację funkcji w odpowiednich miejscach.

Aktywatory funkcji Cloud Firestore

Pakiet SDK Cloud Functions dla Firebase eksportuje obiekt functions.firestore, który umożliwia tworzenie modułów obsługi powiązanych z określonymi zdarzeniami Cloud Firestore.

Typ zdarzenia Aktywator
onCreate Wywoływane przy pierwszym zapisie dokumentu.
onUpdate Wywoływane, gdy dokument już istnieje i ma dowolną wartość.
onDelete Wywoływane, gdy dokument z danymi zostanie usunięty.
onWrite Wywoływane po wywołaniu funkcji onCreate, onUpdate lub onDelete.

Jeśli nie masz jeszcze projektu korzystającego z Cloud Functions dla Firebase, zapoznaj się z artykułem Pierwsze kroki: zapisz i wdróż swoje pierwsze funkcje, aby skonfigurować projekt Cloud Functions dla Firebase.

Zapisywanie funkcji aktywowanych przez Cloud Firestore

Zdefiniuj aktywator funkcji

Aby zdefiniować aktywator Cloud Firestore, podaj ścieżkę dokumentu i typ zdarzenia:

Node.js

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

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

Ścieżki dokumentów mogą odwoływać się do konkretnego dokumentu lub do wzorca symboli wieloznacznych.

Określ pojedynczy dokument

Jeśli chcesz wywoływać zdarzenie w przypadku dowolnej zmiany w określonym dokumencie, możesz użyć poniższej funkcji.

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

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

Jeśli chcesz dołączyć regułę do grupy dokumentów, np. dowolnego dokumentu w określonej kolekcji, użyj {wildcard} zamiast identyfikatora dokumentu:

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

W tym przykładzie zmiana dowolnego pola w dokumencie w obiekcie users spowoduje dopasowanie go do symbolu wieloznacznego o nazwie userId.

Jeśli dokument w kolekcji users ma kolekcje podrzędne, a pole w jednym z dokumentów z kolekcji podrzędnych zostanie zmienione, symbol wieloznaczny userId nie zostanie wywołany.

Dopasowania symboli wieloznacznych są wyodrębniane ze ścieżki dokumentu i zapisywane w pliku context.params. Możesz zdefiniować dowolną liczbę symboli wieloznacznych w stosunku do jawnych identyfikatorów dokumentów lub kolekcji, na przykład:

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

Aktywatory zdarzeń

Aktywowanie funkcji przy tworzeniu nowego dokumentu

Możesz aktywować funkcję uruchamiania funkcji za każdym razem, gdy w kolekcji zostanie utworzony nowy dokument, używając modułu obsługi onCreate() z symbolem wieloznacznym. Ta przykładowa funkcja wywołuje funkcję createUser za każdym razem, gdy dodawany jest nowy profil użytkownika:

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

Aktywowanie funkcji po zaktualizowaniu dokumentu

Możesz też aktywować funkcję uruchamiającą się po zaktualizowaniu dokumentu za pomocą funkcji onUpdate() z symbolem wieloznacznym. Ta przykładowa funkcja wywołuje updateUser, jeśli użytkownik zmieni swój profil:

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

Aktywowanie funkcji po usunięciu dokumentu

Możesz też aktywować funkcję po usunięciu dokumentu za pomocą funkcji onDelete() z symbolem wieloznacznym. Ta przykładowa funkcja wywołuje deleteUser, gdy użytkownik usuwa swój profil:

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

Aktywowanie funkcji w przypadku wszystkich zmian w dokumencie

Jeśli nie interesuje Cię typ wywoływanego zdarzenia, możesz nasłuchiwać wszystkich zmian w dokumencie Cloud Firestore za pomocą funkcji onWrite() z symbolem wieloznacznym. Ta przykładowa funkcja wywołuje modifyUser, jeśli konto użytkownika zostało utworzone, zaktualizowane lub usunięte:

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

Odczytywanie i zapisywanie danych

Po aktywowaniu funkcji wyświetla ona migawkę danych związanych ze zdarzeniem. Możesz użyć tego zrzutu do odczytu lub zapisu w dokumencie, który wywołał zdarzenie, albo za pomocą pakietu Firebase Admin SDK, aby uzyskać dostęp do innych części bazy danych.

Dane zdarzenia

Odczytywanie danych

Po uruchomieniu funkcji możesz pobrać dane z dokumentu, który został zaktualizowany, lub uzyskać je przed aktualizacją. Wcześniejsze dane możesz uzyskać, korzystając z dyrektywy change.before.data(), która zawiera zrzut dokumentu przed aktualizacją. Podobnie change.after.data() zawiera stan zrzutu dokumentu po aktualizacji.

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

Do właściwości możesz uzyskać dostęp tak samo jak w przypadku każdego innego obiektu. Aby uzyskać dostęp do określonych pól, możesz też użyć funkcji get:

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

Zapisywanie danych

Każde wywołanie funkcji jest powiązane z konkretnym dokumentem w bazie danych Cloud Firestore. Możesz uzyskać dostęp do tego dokumentu jako DocumentReference we właściwości ref zrzutu dysku zwróconego do Twojej funkcji.

DocumentReference pochodzi z pakietu SDK Cloud Firestore Node.js i zawiera metody takie jak update(), set() i remove(), dzięki czemu możesz łatwo zmodyfikować dokument, który uruchomił funkcję.

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

Dane spoza zdarzenia aktywującego

Funkcje Cloud Functions są wykonywane w zaufanym środowisku, co oznacza, że są autoryzowane jako konto usługi w Twoim projekcie. Odczyty i zapisy możesz wykonywać za pomocą pakietu 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({ ... });
  });

Ograniczenia

Pamiętaj o tych ograniczeniach dotyczących aktywatorów Cloud Firestore dla Cloud Functions:

  • Zamówienie nie jest gwarantowane. Szybkie zmiany mogą aktywować wywołania funkcji w nieoczekiwanej kolejności.
  • Zdarzenia są dostarczane co najmniej raz, ale 1 zdarzenie może powodować wiele wywołań funkcji. Unikaj stosowania funkcji „dokładnie raz” i pisz funkcje idempotentne.
  • Cloud Firestore w trybie Datastore wymaga Cloud Functions (2 generacji). Cloud Functions (1 generacji) nie obsługuje trybu Datastore.
  • Cloud Functions (1 generacji) działa tylko z bazą danych „(domyślnie)” i nie obsługuje nazwanych baz danych Cloud Firestore. Skonfiguruj zdarzenia dla nazwanych baz danych za pomocą Cloud Functions (2 generacji).
  • Aktywator jest powiązany z jedną bazą danych. Nie można utworzyć aktywatora pasującego do wielu baz danych.
  • Usunięcie bazy danych nie powoduje automatycznego usunięcia jej aktywatorów. Reguła przestanie dostarczać zdarzenia, ale będzie istnieć, dopóki jej nie usuniesz.
  • Jeśli dopasowane zdarzenie przekracza maksymalny rozmiar żądania, może ono nie zostać dostarczone do Cloud Functions (1 generacji).
    • Zdarzenia niedostarczone z powodu rozmiaru żądania są rejestrowane w logach platformy i wliczane do wykorzystania logów w projekcie.
    • W eksploratorze logów możesz znaleźć te logi z komunikatem „Zdarzenie nie może zostać dostarczone do funkcji w Cloud Functions z powodu przekroczenia limitu rozmiaru pierwszej generacji...” o poziomie ważności error. Nazwę funkcji znajdziesz pod polem functionName. Jeśli w polu receiveTimestamp pozostało jeszcze więcej niż godzina, możesz wywnioskować rzeczywistą treść zdarzenia, odczytując dany dokument za pomocą zrzutu ekranu przed sygnaturą czasową i po niej.
    • Aby uniknąć takiej częstotliwości, możesz:
      • Migracja do Cloud Functions (2 generacji) i przejście na nią
      • Zmniejsz rozmiar dokumentu
      • Usunąć dane w Cloud Functions
    • Możesz wyłączyć samo logowanie za pomocą wykluczeń. Pamiętaj jednak, że zdarzenia naruszające zasady nie będą dostarczane.