Rozszerzanie Cloud Firestore za pomocą Cloud Functions

Dzięki Cloud Functions możesz wdrażać kod Node.js do obsługi zdarzeń wywoływanych przez zmiany w bazie danych Cloud Firestore. Dzięki temu możesz łatwo dodawać do aplikacji funkcje po stronie serwera bez konieczności uruchamiania własnych serwerów.

Przykłady zastosowań znajdziesz w artykule Co mogę zrobić za pomocą: Cloud Functions? lub Przykładowe funkcje na GitHubie.

Cloud Firestore aktywatora funkcji

Pakiet SDK Cloud Functions for Firebase eksportuje pakiet functions.firestore , który pozwala tworzyć moduły obsługi powiązane z określonymi zdarzeniami Cloud Firestore.

Jeśli nie masz jeszcze w projekcie włączonego projektu Cloud Functions for Firebase, przeczytaj Pierwsze kroki: pisanie i wdrażanie pierwszych funkcji aby skonfigurować projekt Cloud Functions for Firebase.

Zapisywanie funkcji wywoływanych przez Cloud Firestore

Zdefiniuj aktywator funkcji

Aby zdefiniować regułę Cloud Firestore, podaj ś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ów mogą odwoływać się do konkretnego dokumentu lub wzorzec wieloznaczny.

Wskaż pojedynczy dokument

Jeśli chcesz wywołać zdarzenie w przypadku dowolnej zmiany w określonym dokumencie: możesz użyć następującej 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ślanie grupy dokumentów za pomocą symboli wieloznacznych

Jeśli chcesz dołączyć czynnik uruchamiający do grupy dokumentów, takich jak dowolny dokument w dla określonej kolekcji, a następnie użyj {wildcard} zamiast identyfikator 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 zmieni się dowolne pole w dowolnym dokumencie w dokumencie users, zostanie ono dopasowane symbol wieloznaczny o nazwie userId.

Jeśli dokument w kolekcji users zawiera kolekcje podrzędne i pole w jednej z tych kolekcji dokument został zmieniony, symbol wieloznaczny userId nie zostanie wywołany.

Dopasowania do symboli wieloznacznych są wyodrębniane z ścieżki dokumentu i przechowywane w context.params. Możesz zdefiniować dowolną liczbę symboli wieloznacznych, aby zastąpić zbiór jawny identyfikatory 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ń

Wywoływanie funkcji po utworzeniu nowego dokumentu

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

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

Wywoływanie funkcji po zaktualizowaniu dokumentu

Możesz też aktywować funkcję uruchamiania po zaktualizowaniu dokumentu za pomocą funkcji onUpdate() z symbolem wieloznacznym. Ta przykładowa funkcja wywołuje updateUser, jeśli użytkownik zmienia 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

Aktywowanie funkcji po usunięciu dokumentu

Możesz też uruchomić funkcję po usunięciu dokumentu, używając funkcji onDelete() z symbolem wieloznacznym. Ten przykład funkcja wywołuje deleteUser, gdy użytkownik usunie swój profil:

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 przy wszystkich zmianach w dokumencie

Jeśli nie interesuje Cię typ wywoływanego zdarzenia, możesz nasłuchiwać zmiany w dokumencie Cloud Firestore przy użyciu funkcji onWrite() za pomocą symbolu wieloznacznego. Ta przykładowa funkcja wywołuje funkcję modifyUser, jeśli użytkownik zostanie utworzony, zaktualizowany lub usunięty:

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 wywołaniu funkcja udostępnia zrzut danych związanych z . Możesz użyć tego zrzutu do odczytu lub zapisu w dokumencie, który wywołało zdarzenie lub użyj pakietu Firebase Admin SDK, aby uzyskać dostęp do innych części. Twojej bazy danych.

Dane zdarzenia

Odczytywanie danych

Po wywołaniu funkcji warto pobrać dane z dokumentu, który została zaktualizowana, lub pobierz dane przed aktualizacją. Wcześniejsze dane możesz uzyskać, używając funkcji change.before.data(), który zawiera zrzut dokumentu przed aktualizacją. Podobnie change.after.data() zawiera stan zrzutu dokumentu po fragmencie .

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 samo jak w przypadku każdego innego obiektu. Możesz też użyć funkcji get, aby uzyskać dostęp do określonych 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. Dostęp do tego dokumentu uzyskasz jako DocumentReference w właściwości ref przechwytywania zwracanego przez funkcję.

To źródło danych (DocumentReference) pochodzi z: Cloud Firestore pakiet SDK Node.js i obejmuje metody takie jak update(), set() i remove(), dzięki czemu możesz modyfikować dokument, który uruchomił tę 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 aktywującym

Cloud Functions uruchamiać w zaufanym środowisku, co oznacza, że są autoryzowane jako konto usługi w Twoim projekcie. Za pomocą pakietu Firebase Admin SDK możesz wykonywać operacje odczytu i zapisu:

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 te ograniczenia reguł Cloud Firestore dla Cloud Functions:

• Cloud Functions (pierwsza generacja) wymaga istniejącej bazy danych „(domyślna)” w trybie natywnym Firestore. Nie obsługują nazwane bazy danych Cloud Firestore lub tryb Datastore. Użyj konta Cloud Functions (2 generacji), aby skonfigurować zdarzenia w takich przypadkach.
• Zamówienie nie jest gwarantowane. Nagłe zmiany mogą powodować wywołania funkcji w nieoczekiwanej kolejności.
• Zdarzenia są wysyłane co najmniej raz, ale pojedyncze zdarzenie może spowodować wielokrotne wywołanie funkcji. Unikaj zależnie od mechanika dokładnie raz, funkcji idempotentnych.
• Cloud Firestore w trybie Datastore wymaga Cloud Functions (2 generacji). Cloud Functions (1 generacji) nie obsługują tryb Datastore.
• 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 żadnych jej aktywatorów. reguła przestaje dostarczać zdarzenia, ale będzie istnieć do momentu jej usunięcia;
• Jeśli dopasowane zdarzenie przekracza maksymalny rozmiar żądania, w tagu zdarzenie może nie zostać dostarczone do domeny Cloud Functions (1 generacji).
  • Zdarzenia, które nie zostały dostarczone z powodu rozmiaru żądania, są rejestrowane w logach platformy. i wliczają się do wykorzystania logów w projekcie.
  • Te logi znajdziesz w eksploratorze logów z komunikatem „Event cannot deliver to Cloud function due to size exceeding the limit for 1st gen..." o poważnym error. Nazwa funkcji znajduje się w polu functionName. Jeśli pole receiveTimestamp znajduje się jeszcze w ciągu godziny, możesz określić faktycznej treści wydarzenia, odczytując dany dokument z przed sygnaturą czasową i po niej.
  • Aby ich uniknąć:
    • Przeprowadź migrację i przejdź na Cloud Functions (2 generacji)
    • Zmniejsz rozmiar dokumentu
    • Usuń: Cloud Functions, którego dotyczy problem
  • Możesz wyłączyć samo rejestrowanie za pomocą wykluczeń, ale pamiętaj, że nieprawidłowe zdarzenia nadal nie będą dostarczane.