Расширение Cloud Firestore с помощью облачных функций (1-го поколения)

С помощью Cloud Functions вы можете развернуть код Node.js для обработки событий, вызванных изменениями в вашей базе данных Cloud Firestore . Это позволяет легко добавлять серверную функциональность в ваше приложение без необходимости запуска собственных серверов.

Примеры использования можно найти в разделе «Что я могу делать с Cloud Functions ?» или в репозитории GitHub с примерами использования функций .

Функции Cloud Firestore запускают триггеры

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

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

Если у вас еще нет проекта, поддерживающего 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

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

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

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

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