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