Za pomocą Cloud Functions możesz wdrożyć kod do obsługi wywoływanych zdarzeń przez zmiany w bazie danych Cloud Firestore. Dzięki temu możesz łatwo dodawać tagi po stronie serwera z funkcjami aplikacji bez konieczności uruchamiania własnych serwerów.
Cloud Functions (2 generacja)
Technologia Cloud Run i Eventarc, Cloud Functions for Firebase (2 generacja) daje Ci więcej możliwości infrastrukturę, zaawansowaną kontrolę nad wydajnością i skalowalnością oraz wiele więcej nad środowiskiem wykonawczym funkcji. Więcej informacji o 2 generacji znajdziesz na stronie Cloud Functions dla Firebase (2 generacji). Aby zobaczyć więcej o 1 generacji, zobacz Rozszerz zakres Cloud Firestore za pomocą Cloud Functions.
Cloud Firestore aktywatora funkcji
Pakiet SDK Cloud Functions for Firebase eksportuje te zasoby (Cloud Firestore) aktywatory zdarzeń umożliwiające tworzenie modułów obsługi powiązanych z konkretnym elementem Cloud Firestore wydarzenia:
Node.js
Typ zdarzenia | Aktywator |
---|---|
onDocumentCreated |
Wywoływane, gdy dokument jest zapisany po raz pierwszy. |
onDocumentUpdated |
Wywoływane, gdy dokument już istnieje, ale jego wartość uległa zmianie. |
onDocumentDeleted |
Wywoływane po usunięciu dokumentu. |
onDocumentWritten |
Wywoływane po wywołaniu funkcji onDocumentCreated , onDocumentUpdated lub onDocumentDeleted . |
onDocumentCreatedWithAuthContext |
onDocumentCreated z dodatkowymi informacjami uwierzytelniającymi |
onDocumentWrittenWithAuthContext |
onDocumentWritten z dodatkowymi informacjami uwierzytelniającymi |
onDocumentDeletedWithAuthContext |
onDocumentDeleted z dodatkowymi informacjami uwierzytelniającymi |
onDocumentUpdatedWithAuthContext |
onDocumentUpdated z dodatkowymi informacjami uwierzytelniającymi |
Python (wersja testowa)
Typ zdarzenia | Aktywator |
---|---|
on_document_created |
Wywoływane, gdy dokument jest zapisany po raz pierwszy. |
on_document_updated |
Wywoływane, gdy dokument już istnieje, ale jego wartość uległa zmianie. |
on_document_deleted |
Wywoływane po usunięciu dokumentu. |
on_document_written |
Wywoływane po wywołaniu funkcji on_document_created , on_document_updated lub on_document_deleted . |
on_document_created_with_auth_context |
on_document_created z dodatkowymi informacjami uwierzytelniającymi |
on_document_updated_with_auth_context |
on_document_updated z dodatkowymi informacjami uwierzytelniającymi |
on_document_deleted_with_auth_context |
on_document_deleted z dodatkowymi informacjami uwierzytelniającymi |
on_document_written_with_auth_context |
on_document_written z dodatkowymi informacjami uwierzytelniającymi |
Tylko aktywatory zdarzeń Cloud Firestore o zmianach w dokumencie. Aktualizacja dokumentu Cloud Firestore, w którym dane nie zmienia się (zapis no-op) nie generuje aktualizacji ani nie zapisuje zdarzenia. Jest nie można dodawać zdarzeń do określonych pól.
Jeśli nie masz jeszcze w projekcie włączonego projektu Cloud Functions for Firebase, przeczytaj Pierwsze kroki z Cloud Functions for Firebase (2 generacji) aby skonfigurować projekt Cloud Functions for Firebase.
Zapisywanie funkcji wywoływanych przez Cloud Firestore
Zdefiniuj aktywator funkcji
Aby zdefiniować regułę Cloud Firestore, podaj ścieżkę dokumentu i typ zdarzenia:
Node.js
import {
onDocumentWritten,
onDocumentCreated,
onDocumentUpdated,
onDocumentDeleted,
Change,
FirestoreEvent
} from "firebase-functions/v2/firestore";
exports.myfunction = onDocumentWritten("my-collection/{docId}", (event) => {
/* ... */
});
Python (wersja testowa)
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:
Ścieżki dokumentów mogą odwoływać się do konkretnego dokumentu lub wzorzec wieloznaczny.
Wskaż pojedynczy dokument
Jeśli chcesz wywołać zdarzenie w przypadku dowolnej zmiany w określonym dokumencie: możesz użyć następującej funkcji.
Node.js
import {
onDocumentWritten,
Change,
FirestoreEvent
} from "firebase-functions/v2/firestore";
exports.myfunction = onDocumentWritten("users/marie", (event) => {
// Your code here
});
Python (wersja testowa)
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:
Określ grupę dokumentów przy użyciu symboli wieloznacznych
Jeśli chcesz dołączyć czynnik uruchamiający do grupy dokumentów, takich jak dowolny dokument w
dla określonej kolekcji, a następnie użyj {wildcard}
zamiast
identyfikator dokumentu:
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"}
});
Python (wersja testowa)
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
W tym przykładzie, gdy zmieni się dowolne pole w dowolnym dokumencie w dokumencie users
, zostanie ono dopasowane
symbol wieloznaczny o nazwie userId
.
Jeśli dokument w elemencie users
ma kolekcje podrzędne i pole w jednej z tych
podkolekcji dokument został zmieniony, symbol wieloznaczny userId
nie zostanie wywołany.
Dopasowania zawierające symbole wieloznaczne są wyodrębniane ze ścieżki dokumentu i przechowywane w elemencie event.params
.
Możesz zdefiniować dowolną liczbę symboli wieloznacznych, aby zastąpić zbiór jawny
identyfikatory dokumentów, na przykład:
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"}
});
Python (wersja testowa)
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"}
Wyzwalacz musi zawsze wskazywać dokument, nawet jeśli używasz symbolu wieloznacznego.
Przykład: users/{userId}/{messageCollectionId}
nie jest prawidłowy, ponieważ {messageCollectionId}
jest zbiorem. Jednak users/{userId}/{messageCollectionId}/{messageId}
to
prawidłowa, ponieważ {messageId}
zawsze będzie wskazywać dokument.
Wyzwalacze zdarzeń
Aktywuj funkcję podczas tworzenia nowego dokumentu
Możesz aktywować tę funkcję za każdym razem, gdy w kolekcji zostanie utworzony nowy dokument. Ta przykładowa funkcja jest wyzwalana za każdym razem, gdy dodawany jest nowy profil użytkownika:
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 ...
});
Aby uzyskać dodatkowe informacje dotyczące uwierzytelniania, użyj onDocumentCreatedWithAuthContext
.
Python (wersja testowa)
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 ...
Wywoływanie funkcji po zaktualizowaniu dokumentu
Możesz też wyzwalać tę funkcję po zaktualizowaniu dokumentu. Ta przykładowa funkcja jest uruchamiana, gdy użytkownik zmieni swój profil:
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 ...
});
Aby uzyskać dodatkowe informacje dotyczące uwierzytelniania, użyj onDocumentUpdatedWithAuthContext
.
Python (wersja testowa)
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 ...
Aktywowanie funkcji po usunięciu dokumentu
Możesz też uruchomić tę funkcję po usunięciu dokumentu. Ten przykład uruchamia się, gdy użytkownik usunie swój profil:
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 ...
});
Aby uzyskać dodatkowe informacje dotyczące uwierzytelniania, użyj onDocumentDeletedWithAuthContext
.
Python (wersja testowa)
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 ...
Aktywowanie funkcji przy wszystkich zmianach w dokumencie
Jeśli nie interesuje Cię typ wywoływanego zdarzenia, możesz nasłuchiwać zmiany w dokumencie Cloud Firestore przy użyciu „napisanego dokumentu” wydarzenie . Ta przykładowa funkcja uruchamia się, gdy użytkownik zostanie utworzony, zaktualizowany lub usunięty:
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 ...
});
Aby uzyskać dodatkowe informacje dotyczące uwierzytelniania, użyj onDocumentWrittenWithAuthContext
.
Python (wersja testowa)
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 ...
Odczytywanie i zapisywanie danych
Po wywołaniu funkcja udostępnia zrzut danych związanych z . Możesz użyć tego zrzutu do odczytu lub zapisu w dokumencie, który wywołało zdarzenie lub użyj pakietu Firebase Admin SDK, aby uzyskać dostęp do innych części. Twojej bazy danych.
Dane zdarzenia
Odczytywanie danych
Po wywołaniu funkcji warto pobrać dane z dokumentu, który
została zaktualizowana, lub pobierz dane przed aktualizacją. Wcześniejsze dane możesz uzyskać, używając funkcji
event.data.before
, który zawiera zrzut dokumentu przed aktualizacją.
Podobnie event.data.after
zawiera stan zrzutu dokumentu po fragmencie
.
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();
});
Python (wersja testowa)
@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()
Możesz uzyskać dostęp do właściwości tak samo jak w przypadku każdego innego obiektu. Ewentualnie
może użyć funkcji get
, aby uzyskać dostęp do określonych pól:
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');
Python (wersja testowa)
# 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"]
Zapisywanie danych
Każde wywołanie funkcji jest powiązane z określonym dokumentem w tabeli Baza danych Cloud Firestore. Dostęp do tego dokumentu możesz uzyskać w zrzut zwrócony do funkcji.
Odniesienie do dokumentu obejmuje metody takie jak update()
, set()
i remove()
dzięki czemu możesz zmodyfikować dokument, który uruchomił tę funkcję.
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});
});
Python (wersja testowa)
@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})
Uzyskiwanie dostępu do informacji uwierzytelniających użytkowników
Jeśli używasz jednego z tych typów zdarzeń, masz dostęp do: informacje uwierzytelniające użytkownika dotyczące podmiotu zabezpieczeń, który wywołał zdarzenie. Są one uzupełnieniem informacji zwracanych w zdarzeniu podstawowym.
Node.js
onDocumentCreatedWithAuthContext
onDocumentWrittenWithAuthContext
onDocumentDeletedWithAuthContext
onDocumentUpdatedWithAuthContext
Python (wersja testowa)
on_document_created_with_auth_context
on_document_updated_with_auth_context
on_document_deleted_with_auth_context
on_document_written_with_auth_context
Informacje o danych dostępnych w kontekście uwierzytelniania znajdziesz tutaj: Auth Context (Kontekst uwierzytelniania). Ten przykład pokazuje, jak pobrać informacje uwierzytelniające:
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});
});
Python (wersja testowa)
@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
Dane poza zdarzeniem aktywującym
Cloud Functions są wykonywane w zaufanym środowisku. Są autoryzowane jako konto usługi w projekcie, a Ty możesz wykonywać odczyty zapisy za pomocą pakietu SDK Firebase Admin:
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
});
});
Python (wersja testowa)
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({
# ...
})
Ograniczenia
Zwróć uwagę na te ograniczenia reguł Cloud Firestore dla Cloud Functions:
- Cloud Functions (1 generacji) wymaga dotychczasowego ustawienia „(domyślnie)” w trybie natywnym Firestore. Nie obsługują nazwane bazy danych Cloud Firestore lub tryb Datastore. Użyj konta Cloud Functions (2 generacji), aby skonfigurować zdarzenia w takich przypadkach.
- Zamówienie nie jest gwarantowane. Szybkie zmiany mogą aktywować wywołania funkcji w nieoczekiwanej kolejności.
- Zdarzenia są wywoływane co najmniej raz, ale jedno zdarzenie może spowodować wiele wywołań funkcji. Unikaj zależnie od mechanika dokładnie raz, funkcji idempotentnych.
- Cloud Firestore w trybie Datastore wymaga Cloud Functions (2 generacji). Cloud Functions (1 generacji) nie obsługują tryb Datastore.
- Aktywator jest powiązany z jedną bazą danych. Nie można utworzyć aktywatora pasującego do wielu baz danych.
- Usunięcie bazy danych nie powoduje automatycznego usunięcia żadnych jej aktywatorów. reguła przestaje dostarczać zdarzenia, ale będzie istnieć do momentu jej usunięcia;
- Jeśli dopasowane zdarzenie przekracza maksymalny rozmiar żądania, w tagu
zdarzenie może nie zostać dostarczone do domeny Cloud Functions (1 generacji).
- Zdarzenia, które nie zostały dostarczone z powodu rozmiaru żądania, są rejestrowane w logach platformy. i wliczają się do wykorzystania logów w projekcie.
- Te logi znajdziesz w eksploratorze logów z komunikatem „Zdarzenie nie może dostarczyć do
Funkcja w Cloud Functions z powodu przekroczenia limitu dla 1 generacji...” z
error
wagi. Nazwę funkcji znajdziesz pod polemfunctionName
. Jeśli polereceiveTimestamp
znajduje się jeszcze w ciągu godziny, możesz określić faktycznej treści wydarzenia, odczytując dany dokument z przed sygnaturą czasową i po niej. - Aby ich uniknąć:
- Przeprowadź migrację i przejdź na Cloud Functions (2 generacji)
- Zmniejsz rozmiar dokumentu
- Usuń: Cloud Functions, którego dotyczy problem
- Logowanie możesz wyłączyć przy użyciu wykluczeń. Pamiętaj jednak, że zdarzenia naruszające zasady nadal nie zostaną dostarczone.