Триггеры Cloud Firestore

2-е поколение 1-е поколение

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

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

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

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

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

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

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

Примечание. События Cloud Firestore срабатывают только при изменении документа. Обновление документа Cloud Firestore, в котором данные не изменяются (бездействующая запись), не будет генерировать событие обновления или записи. Невозможно добавлять события в определенные поля.

Если в вашем проекте еще нет поддержки Cloud Functions for Firebase , прочтите статью «Начало работы: напишите и разверните свои первые функции» , чтобы настроить проект Cloud Functions for 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
    });
index.js

Укажите группу документов, используя подстановочные знаки

Если вы хотите прикрепить триггер к группе документов, например к любому документу в определенной коллекции, используйте {wildcard} вместо идентификатора документа:

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

В этом примере, когда любое поле в любом документе 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"}
    });
index.js

Примечание. Ваш триггер всегда должен указывать на документ, даже если вы используете подстановочный знак. Например, users/{userId}/{messageCollectionId} недопустимы, поскольку {messageCollectionId} — это коллекция. Однако users/{userId}/{messageCollectionId}/{messageId} допустимы , поскольку {messageId} всегда будет указывать на документ.

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

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

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

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

Вы также можете активировать функцию при обновлении документа с помощью функции 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 ...
    });
index.js

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

Вы также можете вызвать функцию при удалении документа, используя функцию 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 ...
    });
index.js

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

Если вас не волнует тип запускаемого события, вы можете прослушивать все изменения в документе Cloud 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 ...
    });
index.js

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

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

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

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

Каждый вызов функции связан с определенным документом в вашей базе данных 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});
    });
index.js

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

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

Cloud Functions выполняются в доверенной среде, что означает, что они авторизованы в качестве сервисной учетной записи в вашем проекте. Вы можете выполнять чтение и запись с помощью 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 Functions не контролируются вашими правилами безопасности, они могут получить доступ к любой части вашей базы данных.

Ограничения

Обратите внимание на следующие ограничения для триггеров Cloud Firestore для Cloud Functions :

• Cloud Functions (1-го поколения) требуют наличия существующей базы данных «(по умолчанию)» в собственном режиме Firestore. Он не поддерживает именованные базы данных Cloud Firestore или режим хранилища данных. В таких случаях для настройки событий используйте Cloud Functions (2-го поколения).
• Заказ не гарантируется. Быстрые изменения могут вызвать вызовы функций в неожиданном порядке.
• События доставляются как минимум один раз, но одно событие может привести к множественным вызовам функций. Избегайте зависимости от механики «точно один раз» и пишите идемпотентные функции .
• Cloud Firestore в режиме хранилища данных требует Cloud Functions (2-го поколения). Cloud Functions (1-го поколения) не поддерживают режим хранилища данных.
• Триггер связан с одной базой данных. Вы не можете создать триггер, который соответствует нескольким базам данных.
• Удаление базы данных не приводит к автоматическому удалению триггеров для этой базы данных. Триггер перестает доставлять события, но продолжает существовать до тех пор, пока вы не удалите триггер .
• Если сопоставленное событие превышает максимальный размер запроса , оно может не быть доставлено в Cloud Functions (1-го поколения).
  • События, которые не были доставлены из-за размера запроса, регистрируются в журналах платформы и учитываются при использовании журнала для проекта.
  • Вы можете найти эти журналы в обозревателе журналов с сообщением «Событие не может быть доставлено в функцию Cloud из-за размера, превышающего предел для 1-го поколения...» серьезности error . Имя функции можно найти в поле functionName . Если поле receiveTimestamp по-прежнему находится в пределах часа, вы можете сделать вывод о фактическом содержимом события, прочитав соответствующий документ со снимком до и после отметки времени.
  • Чтобы избежать такой каденции, вы можете:
    • Миграция и обновление до Cloud Functions (2-го поколения)
    • Уменьшить размер документа
    • Удалите рассматриваемые Cloud Functions .
  • Вы можете отключить само ведение журнала с помощью исключений , но учтите, что нарушающие события все равно не будут доставлены.