Catch up on everthing we announced at this year's Firebase Summit. Learn more

Триггеры Cloud Firestore

С помощью облачных функций вы можете обрабатывать события в Cloud Firestore без необходимости обновлять клиентский код. Вы можете внести изменения Облако Firestore через DocumentSnapshot интерфейс или через Admin SDK .

В типичном жизненном цикле функция Cloud Firestore выполняет следующие действия:

  1. Ожидает изменений в конкретном документе.
  2. Триггеры , когда происходит событие , и выполняет свои задачи (см Что я могу сделать с облачных функций? Примеры вариантов использования).
  3. Получает объект данных, содержащий моментальный снимок данных, хранящихся в указанном документе. Для onWrite или onUpdate событий, объект данных содержит два снимка , которые представляют состояние данных до и после инициирующего события.

Расстояние между местоположением экземпляра Firestore и местоположением функции может создавать значительную задержку в сети. Для оптимальной производительности, рассмотрим с указанием местоположения функции , когда это применимо.

Триггеры функции Cloud Firestore

Функции Облака для Firebase SDK экспортирует functions.firestore объект , который позволяет создавать обработчики привязанные к конкретным событиям Облака Firestore.

Тип события Курок
onCreate Срабатывает, когда документ записывается в первый раз.
onUpdate Срабатывает, когда документ уже существует и для него изменилось какое-либо значение.
onDelete Срабатывает при удалении документа с данными.
onWrite Срабатывает , когда onCreate , onUpdate или onDelete срабатывает.

Если вы не имеете проект включены для облачных функций для Firebase еще, то читайте НАЧАТЬ: Write и развертывание Первых функции для настройки и настроить функции Облака для проекта Firebase.

Написание функций, запускаемых Cloud Firestore

Определите триггер функции

Чтобы определить триггер Cloud Firestore, укажите путь к документу и тип события:

Node.js

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

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

Пути документов могут ссылаться либо конкретный документ или подстановочных шаблон .

Укажите единый документ

Если вы хотите , чтобы вызвать событие для любого изменения к конкретному документу , то вы можете использовать следующую функцию.

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

Укажите группу документов с помощью подстановочных знаков

Если вы хотите присоединить триггер к группе документов, таких , как любой документ , в определенной коллекции, а затем использовать {wildcard} вместо документа 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"}
    });

В этом примере, когда любое поле в любом документе в users меняется, когда она совпадает с групповым символом , называемым userId .

Если документ users имеют подколлекции, и поле в одном из документов этой Подколлекции изменяется, userId подстановочный не запускаются.

Подстановочные матчей извлекаются из пути документа и хранятся в context.params . Вы можете определить столько подстановочных знаков, сколько захотите, чтобы заменить явные идентификаторы коллекции или документа, например:

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

Триггеры событий

Запускать функцию при создании нового документа

Вы можете вызвать функцию стрелять в любое время новый документ создается в коллекции с помощью onCreate() обработчика с шаблоном . В этом примере функция вызывает createUser каждый раз , когда добавляется новый профиль:

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

Запускать функцию при обновлении документа

Вы можете также вызвать функцию огня , когда документ обновляется с использованием onUpdate() функцию с групповым символом . В этом примере функция вызывает updateUser , если пользователь меняет свой профиль:

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

Запускать функцию при удалении документа

Вы можете также вызвать функцию , когда документ будет удален с помощью onDelete() функции с групповым символом . В этом примере функция вызывает deleteUser , когда пользователь удаляет свой профиль:

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

Запускать функцию для всех изменений в документе

Если вы не заботитесь о типе событий увольняют, вы можете слушать все изменения в документе Облака Firestore с помощью onWrite() функции с групповым символом . В этом примере функция вызывает modifyUser , если пользователь будет создан, обновлен или удален:

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

Чтение и запись данных

Когда функция запускается, она предоставляет моментальный снимок данных, связанных с событием. Вы можете использовать этот снимок для чтения или записи в документ, вызвавший событие, или использовать Firebase Admin SDK для доступа к другим частям вашей базы данных.

Данные о событиях

Чтение данных

Когда функция запускается, вы можете захотеть получить данные из документа, который был обновлен, или получить данные до обновления. Вы можете получить предварительные данные с помощью change.before.data() , который содержит снимок документа перед обновлением. Точно так же, change.after.data() содержит состояние документа снимок после обновления.

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

Вы можете получить доступ к свойствам, как и к любому другому объекту. Кроме того , вы можете использовать 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');

Запись данных

Каждый вызов функции связан с определенным документом в базе данных Cloud Firestore. Вы можете получить доступ к этому документу как DocumentReference в ref свойстве снимка возвращенного к вашей функции.

Это DocumentReference происходит от Cloud Firestore Node.js SDK и включает в себя такие методы , как update() , set() и remove() , так что вы можете легко изменить документ , который вызвал функцию.

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

Данные вне триггерного события

Облачные функции выполняются в доверенной среде, что означает, что они авторизованы в качестве учетной записи службы в вашем проекте. Вы можете выполнять операции чтения и записи с помощью 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({ ... });
  });

Ограничения

Обратите внимание на следующие ограничения для триггеров Cloud Firestore для облачных функций:

  • Заказ не гарантируется. Быстрые изменения могут вызывать вызовы функций в неожиданном порядке.
  • События доставляются как минимум один раз, но одно событие может привести к вызову нескольких функций. Избегайте в зависимости от точности-Once механики и запись функции идемпотентной .
  • Облако Firestore триггера для облачных функций доступны только для облачных Firestore в основном режиме . Он недоступен для Cloud Firestore в режиме хранилища данных.