Триггеры Realtime Database (первое поколение)

С помощью Cloud Functions можно обрабатывать события в Firebase Realtime Database без необходимости обновлять код клиента. Cloud Functions позволяет выполнять операции Realtime Database с полными правами администратора и гарантирует, что каждое изменение в Realtime Database будет обработано отдельно. Вы можете вносить Firebase Realtime Database изменения с помощью DataSnapshot или Admin SDK.

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

1. Ожидает изменений в определенном местоположении Realtime Database.
2. Активируется при наступлении события и выполняет свои задачи (см. раздел Что можно делать с помощью Cloud Functions?). Примеры использования приведены ниже.
3. Получает объект данных, содержащий снимок данных, хранящихся в указанном документе.

Как запустить функцию Realtime Database

Создавайте новые функции для событий Realtime Database с помощью functions.database. Чтобы указать, когда должна запускаться функция, задайте один из обработчиков событий и путь к Realtime Database, где будут отслеживаться события.

Как задать обработчик событий

Функции позволяют обрабатывать события Realtime Database на двух уровнях детализации: можно отслеживать только события создания, обновления или удаления или любые изменения по определенному пути. Cloud Functions поддерживает следующие обработчики событий для Realtime Database:

• onWrite(), который срабатывает при создании, изменении или удалении данных в Realtime Database.
• onCreate(), который активируется при создании новых данных в Realtime Database.
• onUpdate(), который активируется при обновлении данных в Realtime Database .
• onDelete(), который активируется при удалении данных из Realtime Database .

Как указать экземпляр и путь

Чтобы указать, когда и где должна запускаться функция, вызовите метод ref(path), чтобы задать путь, и при необходимости укажите экземпляр Realtime Database с помощью instance('INSTANCE_NAME'). Если вы не укажете экземпляр, функция будет развернута в экземпляре Realtime Database по умолчанию для проекта Firebase. Пример:

• Экземпляр Realtime Database по умолчанию: functions.database.ref('/foo/bar')
• Экземпляр с именем my-app-db-2: functions.database.instance('my-app-db-2').ref('/foo/bar')

Эти методы указывают функции, как обрабатывать записи по определенному пути в экземпляре Realtime Database. Спецификации пути соответствуют всем операциям записи, которые затрагивают путь, включая операции записи, которые происходят в любом месте ниже. Если вы зададите для функции путь /foo/bar, она будет сопоставлять события в обоих следующих местоположениях:

 /foo/bar
 /foo/bar/baz/really/deep/path

В обоих случаях Firebase интерпретирует событие как произошедшее в момент времени /foo/bar, а данные о событии включают старые и новые данные на момент /foo/bar. Если данных о событиях может быть много, попробуйте использовать несколько функций на более глубоких уровнях, а не одну функцию в корне базы данных. Чтобы повысить производительность, запрашивайте данные только на самом глубоком уровне.

Вы можете указать компонент пути как подстановочный знак, заключив его в фигурные скобки. ref('foo/{bar}') соответствует любому дочернему элементу /foo. Значения этих компонентов пути с подстановочными знаками доступны в объекте EventContext.params вашей функции. В этом примере значение доступно как context.params.bar.

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

{
  "foo": {
    "hello": "world",
    "firebase": "functions"
  }
}

соответствует пути "/foo/{bar}" дважды: один раз с "hello": "world" и ещё раз с "firebase": "functions".

Как обрабатывать данные о событиях

При обработке события Realtime Database возвращаемый объект данных является объектом DataSnapshot. Для событий onWrite или onUpdate первым параметром является объект Change, содержащий два снимка, которые представляют состояние данных до и после запуска события. Для событий onCreate и onDelete возвращаемый объект данных представляет собой снимок созданных или удаленных данных.

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

// Listens for new messages added to /messages/:pushId/original and creates an
// uppercase version of the message to /messages/:pushId/uppercase
exports.makeUppercase = functions.database.ref('/messages/{pushId}/original')
    .onCreate((snapshot, context) => {
      // Grab the current value of what was written to the Realtime Database.
      const original = snapshot.val();
      functions.logger.log('Uppercasing', context.params.pushId, original);
      const uppercase = original.toUpperCase();
      // You must return a Promise when performing asynchronous tasks inside a Functions such as
      // writing to the Firebase Realtime Database.
      // Setting an "uppercase" sibling in the Realtime Database returns a Promise.
      return snapshot.ref.parent.child('uppercase').set(uppercase);
    });
index.js

Как получить доступ к информации об аутентификации пользователей

Из EventContext.auth и EventContext.authType можно получить доступ к информации о пользователе, в том числе к разрешениям, для пользователя, который вызвал функцию. Это может быть полезно для применения правил безопасности, позволяя функции выполнять различные операции в зависимости от уровня разрешений пользователя:

const functions = require('firebase-functions/v1');
const admin = require('firebase-admin');

exports.simpleDbFunction = functions.database.ref('/path')
    .onCreate((snap, context) => {
      if (context.authType === 'ADMIN') {
        // do something
      } else if (context.authType === 'USER') {
        console.log(snap.val(), 'written by', context.auth.uid);
      }
    });

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

exports.impersonateMakeUpperCase = functions.database.ref('/messages/{pushId}/original')
    .onCreate((snap, context) => {
      const appOptions = JSON.parse(process.env.FIREBASE_CONFIG);
      appOptions.databaseAuthVariableOverride = context.auth;
      const app = admin.initializeApp(appOptions, 'app');
      const uppercase = snap.val().toUpperCase();
      const ref = snap.ref.parent.child('uppercase');

      const deleteApp = () => app.delete().catch(() => null);

      return app.database().ref(ref).set(uppercase).then(res => {
        // Deleting the app is necessary for preventing concurrency leaks
        return deleteApp().then(() => res);
      }).catch(err => {
        return deleteApp().then(() => Promise.reject(err));
      });
    });

Прочитать предыдущее значение

У объекта Change есть свойство before, которое позволяет проверить, что было сохранено в Realtime Database до события. Свойство before возвращает значение DataSnapshot, где все методы (например, val() и exists()) относятся к предыдущему значению. Чтобы снова прочитать новое значение, используйте исходное свойство DataSnapshot или свойство after. Это свойство любого объекта Change – ещё один объект DataSnapshot, представляющий состояние данных после события.

Например, свойство before можно использовать, чтобы функция переводила текст в верхний регистр только при его создании:

exports.makeUppercase = functions.database.ref('/messages/{pushId}/original')
    .onWrite((change, context) => {
      // Only edit data when it is first created.
      if (change.before.exists()) {
        return null;
      }
      // Exit when the data is deleted.
      if (!change.after.exists()) {
        return null;
      }
      // Grab the current value of what was written to the Realtime Database.
      const original = change.after.val();
      console.log('Uppercasing', context.params.pushId, original);
      const uppercase = original.toUpperCase();
      // You must return a Promise when performing asynchronous tasks inside a Functions such as
      // writing to the Firebase Realtime Database.
      // Setting an "uppercase" sibling in the Realtime Database returns a Promise.
      return change.after.ref.parent.child('uppercase').set(uppercase);
    });