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

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

Облачные функции (2-го поколения)

Облачные функции для Firebase (2-го поколения), основанные на Cloud Run и Eventarc , предоставляют вам более мощную инфраструктуру, расширенный контроль над производительностью и масштабируемостью, а также больший контроль над временем выполнения функций. Дополнительные сведения о втором поколении см. в разделе Облачные функции для Firebase (2-го поколения) . Чтобы узнать больше о первом поколении, см. Расширение Cloud Firestore с помощью облачных функций .

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

Cloud Functions for Firebase SDK экспортирует следующие триггеры событий Cloud Firestore, что позволяет создавать обработчики, привязанные к конкретным событиям Cloud Firestore:

Node.js

Тип события Курок
onDocumentCreated Срабатывает, когда документ записывается в первый раз.
onDocumentUpdated Срабатывает, когда документ уже существует и его значение изменено.
onDocumentDeleted Срабатывает при удалении документа.
onDocumentWritten Срабатывает, когда срабатывает onDocumentCreated , onDocumentUpdated или onDocumentDeleted .
onDocumentCreatedWithAuthContext onDocumentCreated с дополнительной информацией аутентификации
onDocumentWrittenWithAuthContext onDocumentWritten с дополнительной информацией для аутентификации
onDocumentDeletedWithAuthContext onDocumentDeleted с дополнительной информацией аутентификации
onDocumentUpdatedWithAuthContext onDocumentUpdated с дополнительной информацией аутентификации

Питон (предварительная версия)

Тип события Курок
on_document_created Срабатывает, когда документ записывается в первый раз.
on_document_updated Срабатывает, когда документ уже существует и его значение изменено.
on_document_deleted Срабатывает при удалении документа.
on_document_written Срабатывает, когда срабатывает on_document_created , on_document_updated или on_document_deleted .
on_document_created_with_auth_context on_document_created с дополнительной информацией для аутентификации
on_document_updated_with_auth_context on_document_updated с дополнительной информацией для аутентификации
on_document_deleted_with_auth_context on_document_deleted с дополнительной информацией для аутентификации
on_document_written_with_auth_context on_document_written с дополнительной информацией для аутентификации

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

Если в вашем проекте еще нет поддержки облачных функций для Firebase, прочтите статью Начало работы с облачными функциями для Firebase (2-го поколения), чтобы настроить проект Cloud Functions for Firebase.

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

Определить функциональный триггер

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

Node.js

import {
  onDocumentWritten,
  onDocumentCreated,
  onDocumentUpdated,
  onDocumentDeleted,
  Change,
  FirestoreEvent
} from "firebase-functions/v2/firestore";

exports.myfunction = onDocumentWritten("my-collection/{docId}", (event) => {
   /* ... */ 
});

Питон (предварительная версия)

from firebase_functions.firestore_fn import (
  on_document_created,
  on_document_deleted,
  on_document_updated,
  on_document_written,
  Event,
  Change,
  DocumentSnapshot,
)

@on_document_created(document="users/{userId}")
def myfunction(event: Event[DocumentSnapshot]) -> None:

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

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

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

Node.js

import {
  onDocumentWritten,
  Change,
  FirestoreEvent
} from "firebase-functions/v2/firestore";

exports.myfunction = onDocumentWritten("users/marie", (event) => {
  // Your code here
});

Питон (предварительная версия)

from firebase_functions.firestore_fn import (
  on_document_written,
  Event,
  Change,
  DocumentSnapshot,
)

@on_document_written(document="users/marie")
def myfunction(event: Event[Change[DocumentSnapshot]]) -> None:

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

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

Node.js

import {
  onDocumentWritten,
  Change,
  FirestoreEvent
} from "firebase-functions/v2/firestore";

exports.myfunction = onDocumentWritten("users/{userId}", (event) => {
  // If we set `/users/marie` to {name: "Marie"} then
  // event.params.userId == "marie"
  // ... and ...
  // event.data.after.data() == {name: "Marie"}
});

Питон (предварительная версия)

from firebase_functions.firestore_fn import (
  on_document_written,
  Event,
  Change,
  DocumentSnapshot,
)

@on_document_written(document="users/{userId}")
def myfunction(event: Event[Change[DocumentSnapshot]]) -> None:
  # If we set `/users/marie` to {name: "Marie"} then
  event.params["userId"] == "marie"  # True
  # ... and ...
  event.data.after.to_dict() == {"name": "Marie"}  # True

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

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

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

Node.js

import {
  onDocumentWritten,
  Change,
  FirestoreEvent
} from "firebase-functions/v2/firestore";

exports.myfunction = onDocumentWritten("users/{userId}/{messageCollectionId}/{messageId}", (event) => {
    // If we set `/users/marie/incoming_messages/134` to {body: "Hello"} then
    // event.params.userId == "marie";
    // event.params.messageCollectionId == "incoming_messages";
    // event.params.messageId == "134";
    // ... and ...
    // event.data.after.data() == {body: "Hello"}
});

Питон (предварительная версия)

from firebase_functions.firestore_fn import (
  on_document_written,
  Event,
  Change,
  DocumentSnapshot,
)

@on_document_written(document="users/{userId}/{messageCollectionId}/{messageId}")
def myfunction(event: Event[Change[DocumentSnapshot]]) -> None:
  # If we set `/users/marie/incoming_messages/134` to {body: "Hello"} then
  event.params["userId"] == "marie"  # True
  event.params["messageCollectionId"] == "incoming_messages"  # True
  event.params["messageId"] == "134"  # True
  # ... and ...
  event.data.after.to_dict() == {"body": "Hello"}

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

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

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

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

Node.js

import {
  onDocumentCreated,
  Change,
  FirestoreEvent
} from "firebase-functions/v2/firestore";

exports.createuser = onDocumentCreated("users/{userId}", (event) => {
    // Get an object representing the document
    // e.g. {'name': 'Marie', 'age': 66}
    const snapshot = event.data;
    if (!snapshot) {
        console.log("No data associated with the event");
        return;
    }
    const data = snapshot.data();

    // access a particular field as you would any JS property
    const name = data.name;

    // perform more operations ...
});

Для получения дополнительной информации об аутентификации используйте onDocumentCreatedWithAuthContext .

Питон (предварительная версия)

from firebase_functions.firestore_fn import (
  on_document_created,
  Event,
  DocumentSnapshot,
)

@on_document_created(document="users/{userId}")
def myfunction(event: Event[DocumentSnapshot]) -> None:
  # Get a dictionary representing the document
  # e.g. {'name': 'Marie', 'age': 66}
  new_value = event.data.to_dict()

  # Access a particular field as you would any dictionary
  name = new_value["name"]

  # Perform more operations ...

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

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

Node.js

import {
  onDocumentUpdated,
  Change,
  FirestoreEvent
} from "firebase-functions/v2/firestore";

exports.updateuser = onDocumentUpdated("users/{userId}", (event) => {
    // Get an object representing the document
    // e.g. {'name': 'Marie', 'age': 66}
    const newValue = event.data.after.data();

    // access a particular field as you would any JS property
    const name = newValue.name;

    // perform more operations ...
});

Для получения дополнительной информации об аутентификации используйте onDocumentUpdatedWithAuthContext .

Питон (предварительная версия)

from firebase_functions.firestore_fn import (
  on_document_updated,
  Event,
  Change,
  DocumentSnapshot,
)

@on_document_updated(document="users/{userId}")
def myfunction(event: Event[Change[DocumentSnapshot]]) -> None:
  # Get a dictionary representing the document
  # e.g. {'name': 'Marie', 'age': 66}
  new_value = event.data.after.to_dict()

  # Access a particular field as you would any dictionary
  name = new_value["name"]

  # Perform more operations ...

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

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

Node.js

import {
  onDocumentDeleted,
  Change,
  FirestoreEvent
} from "firebase-functions/v2/firestore";

exports.deleteuser = onDocumentDeleted("users/{userId}", (event) => {
    // Get an object representing the document
    // e.g. {'name': 'Marie', 'age': 66}
    const snap =  event.data;
    const data =  snap.data();

    // perform more operations ...
});

Для получения дополнительной информации об аутентификации используйте onDocumentDeletedWithAuthContext .

Питон (предварительная версия)

from firebase_functions.firestore_fn import (
  on_document_deleted,
  Event,
  DocumentSnapshot,
)

@on_document_deleted(document="users/{userId}")
def myfunction(event: Event[DocumentSnapshot|None]) -> None:
  # Perform more operations ...

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

Если вас не волнует тип запускаемого события, вы можете прослушивать все изменения в документе Cloud Firestore, используя триггер события «документ написан». Этот пример функции срабатывает, если пользователь создан, обновлен или удален:

Node.js

import {
  onDocumentWritten,
  Change,
  FirestoreEvent
} from "firebase-functions/v2/firestore";

exports.modifyuser = onDocumentWritten("users/{userId}", (event) => {
    // Get an object with the current document values.
    // If the document does not exist, it was deleted
    const document =  event.data.after.data();

    // Get an object with the previous document values
    const previousValues =  event.data.before.data();

    // perform more operations ...
});

Для получения дополнительной информации об аутентификации используйте onDocumentWrittenWithAuthContext .

Питон (предварительная версия)

from firebase_functions.firestore_fn import (
  on_document_written,
  Event,
  Change,
  DocumentSnapshot,
)

@on_document_written(document="users/{userId}")
def myfunction(event: Event[Change[DocumentSnapshot | None]]) -> None:
  # Get an object with the current document values.
  # If the document does not exist, it was deleted.
  document = (event.data.after.to_dict()
              if event.data.after is not None else None)

  # Get an object with the previous document values.
  # If the document does not exist, it was newly created.
  previous_values = (event.data.before.to_dict()
                     if event.data.before is not None else None)

  # Perform more operations ...

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

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

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

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

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

Node.js

exports.updateuser2 = onDocumentUpdated("users/{userId}", (event) => {
    // Get an object with the current document values.
    // If the document does not exist, it was deleted
    const newValues =  event.data.after.data();

    // Get an object with the previous document values
    const previousValues =  event.data.before.data();
});

Питон (предварительная версия)

@on_document_updated(document="users/{userId}")
def myfunction(event: Event[Change[DocumentSnapshot]]) -> None:
  # Get an object with the current document values.
  new_value = event.data.after.to_dict()

  # Get an object with the previous document values.
  prev_value = event.data.before.to_dict()

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

Node.js

// Fetch data using standard accessors
const age = event.data.after.data().age;
const name = event.data.after.data()['name'];

// Fetch data using built in accessor
const experience = event.data.after.data.get('experience');

Питон (предварительная версия)

# Get the value of a single document field.
age = event.data.after.get("age")

# Convert the document to a dictionary.
age = event.data.after.to_dict()["age"]

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

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

Ссылка на документ включает в себя такие методы, как update() , set() и remove() , поэтому вы можете изменить документ, вызвавший функцию.

Node.js

import { onDocumentUpdated } from "firebase-functions/v2/firestore";

exports.countnamechanges = onDocumentUpdated('users/{userId}', (event) => {
  // Retrieve the current and previous value
  const data = event.data.after.data();
  const previousData = event.data.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 data.after.ref.set({
    name_change_count: count + 1
  }, {merge: true});

});

Питон (предварительная версия)

@on_document_updated(document="users/{userId}")
def myfunction(event: Event[Change[DocumentSnapshot]]) -> None:
  # Get the current and previous document values.
  new_value = event.data.after
  prev_value = event.data.before

  # We'll only update if the name has changed.
  # This is crucial to prevent infinite loops.
  if new_value.get("name") == prev_value.get("name"):
      return

  # Retrieve the current count of name changes
  count = new_value.to_dict().get("name_change_count", 0)

  # Update the count
  new_value.reference.update({"name_change_count": count + 1})

Доступ к информации аутентификации пользователя

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

Node.js

  • onDocumentCreatedWithAuthContext
  • onDocumentWrittenWithAuthContext
  • onDocumentDeletedWithAuthContext
  • onDocumentUpdatedWithAuthContext

Питон (предварительная версия)

  • on_document_created_with_auth_context
  • on_document_updated_with_auth_context
  • on_document_deleted_with_auth_context
  • on_document_written_with_auth_context

Информацию о данных, доступных в контексте аутентификации, см. в разделе Контекст аутентификации . В следующем примере показано, как получить данные аутентификации:

Node.js

import { onDocumentWrittenWithAuthContext } from "firebase-functions/v2/firestore"

exports.syncUser = onDocumentWrittenWithAuthContext("users/{userId}", (event) => {
    const snapshot = event.data.after;
    if (!snapshot) {
        console.log("No data associated with the event");
        return;
    }
    const data = snapshot.data();

    // retrieve auth context from event
    const { authType, authId } = event;

    let verified = false;
    if (authType === "system") {
      // system-generated users are automatically verified
      verified = true;
    } else if (authType === "unknown" || authType === "unauthenticated") {
      // admin users from a specific domain are verified
      if (authId.endsWith("@example.com")) {
        verified = true;
      }
    }

    return data.after.ref.set({
        created_by: authId,
        verified,
    }, {merge: true}); 
});

Питон (предварительная версия)

@on_document_updated_with_auth_context(document="users/{userId}")
def myfunction(event: Event[Change[DocumentSnapshot]]) -> None:

  # Get the current and previous document values.
  new_value = event.data.after
  prev_value = event.data.before

  # Get the auth context from the event
  user_auth_type = event.auth_type
  user_auth_id = event.auth_id

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

Облачные функции выполняются в доверенной среде. Они авторизованы в качестве сервисной учетной записи в вашем проекте, и вы можете выполнять чтение и запись с помощью Firebase Admin SDK :

Node.js

const { initializeApp } = require('firebase-admin/app');
const { getFirestore, Timestamp, FieldValue } = require('firebase-admin/firestore');

initializeApp();
const db = getFirestore();

exports.writetofirestore = onDocumentWritten("some/doc", (event) => {
    db.doc('some/otherdoc').set({ ... });
  });

  exports.writetofirestore = onDocumentWritten('users/{userId}', (event) => {
    db.doc('some/otherdoc').set({
      // Update otherdoc
    });
  });

Питон (предварительная версия)

from firebase_admin import firestore, initialize_app
import google.cloud.firestore

initialize_app()

@on_document_written(document="some/doc")
def myfunction(event: Event[Change[DocumentSnapshot | None]]) -> None:
  firestore_client: google.cloud.firestore.Client = firestore.client()
  firestore_client.document("another/doc").set({
      # ...
  })

Ограничения

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

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