ด้วย Cloud Functions คุณสามารถติดตั้งใช้งานโค้ดเพื่อจัดการเหตุการณ์ที่ทริกเกอร์ โดยการเปลี่ยนแปลงในฐานข้อมูล Cloud Firestore ซึ่งช่วยให้คุณเพิ่มฟังก์ชันการทำงานฝั่งเซิร์ฟเวอร์ลงในแอปได้โดยไม่ต้องเรียกใช้เซิร์ฟเวอร์ของคุณเอง
Cloud Functions (รุ่นที่ 2)
Cloud Functions for Firebase (รุ่นที่ 2) ขับเคลื่อนโดย Cloud Run และ Eventarc จึงมีโครงสร้างพื้นฐานที่ทรงพลังยิ่งขึ้น การควบคุมประสิทธิภาพและความสามารถในการปรับขนาดขั้นสูง รวมถึงการควบคุมรันไทม์ของฟังก์ชันได้มากขึ้นCloud Functions for Firebase ดูข้อมูลเพิ่มเติมเกี่ยวกับรุ่นที่ 2 ได้ที่ Cloud Functions for Firebase (รุ่นที่ 2)
ทริกเกอร์ฟังก์ชัน Cloud Firestore
SDK ของ Cloud Functions for Firebase จะส่งออกทริกเกอร์Cloud Firestore เหตุการณ์ต่อไปนี้เพื่อให้คุณสร้างแฮนเดิลเลอร์ที่เชื่อมโยงกับCloud Firestore เหตุการณ์ที่เฉพาะเจาะจงได้
Node.js
| ประเภทเหตุการณ์ | ทริกเกอร์ |
|---|---|
onDocumentCreated |
ทริกเกอร์เมื่อมีการเขียนเอกสารเป็นครั้งแรก |
onDocumentUpdated |
ทริกเกอร์เมื่อเอกสารมีอยู่แล้วและมีการเปลี่ยนแปลงค่า |
onDocumentDeleted |
ทริกเกอร์เมื่อมีการลบเอกสาร |
onDocumentWritten |
ทริกเกอร์เมื่อ onDocumentCreated, onDocumentUpdated หรือ onDocumentDeleted ทริกเกอร์ |
onDocumentCreatedWithAuthContext |
onDocumentCreated พร้อมข้อมูลการตรวจสอบสิทธิ์เพิ่มเติม |
onDocumentWrittenWithAuthContext |
onDocumentWritten พร้อมข้อมูลการตรวจสอบสิทธิ์เพิ่มเติม |
onDocumentDeletedWithAuthContext |
onDocumentDeleted พร้อมข้อมูลการตรวจสอบสิทธิ์เพิ่มเติม |
onDocumentUpdatedWithAuthContext |
onDocumentUpdated พร้อมข้อมูลการตรวจสอบสิทธิ์เพิ่มเติม |
Python
| ประเภทเหตุการณ์ | ทริกเกอร์ |
|---|---|
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
const {
onDocumentWritten,
onDocumentCreated,
onDocumentUpdated,
onDocumentDeleted,
Change,
FirestoreEvent
} = require('firebase-functions/v2/firestore');
exports.myfunction = onDocumentWritten("my-collection/{docId}", (event) => {
/* ... */
});
Python
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
const {
onDocumentWritten,
Change,
FirestoreEvent
} = require('firebase-functions/v2/firestore');
exports.myfunction = onDocumentWritten("users/marie", (event) => {
// Your code here
});
Python
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
const {
onDocumentWritten,
Change,
FirestoreEvent
} = require('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
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
ระบบจะแยกการจับคู่ไวลด์การ์ดออกจากเส้นทางเอกสารและจัดเก็บไว้ใน event.params
ทริกเกอร์ต้องชี้ไปที่เอกสาร เสมอ แม้ว่าคุณจะใช้ไวลด์การ์ดก็ตาม
ทริกเกอร์เหตุการณ์
ทริกเกอร์ฟังก์ชันเมื่อมีการสร้างเอกสารใหม่
คุณสามารถทริกเกอร์ฟังก์ชันให้เริ่มทำงานทุกครั้งที่สร้างเอกสารใหม่ในคอลเล็กชัน ฟังก์ชันตัวอย่างนี้จะทริกเกอร์ทุกครั้งที่มีการเพิ่มโปรไฟล์ผู้ใช้ใหม่
Node.js
const {
onDocumentCreated,
Change,
FirestoreEvent
} = require('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
Python
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
const {
onDocumentUpdated,
Change,
FirestoreEvent
} = require('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
Python
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
const {
onDocumentDeleted,
Change,
FirestoreEvent
} = require('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
Python
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
const {
onDocumentWritten,
Change,
FirestoreEvent
} = require('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
Python
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();
});
Python
@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');
Python
# 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
const {onDocumentUpdated} = require('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 event.data.after.ref.set({
name_change_count: count + 1
}, {merge: true});
});
Python
@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
onDocumentCreatedWithAuthContextonDocumentWrittenWithAuthContextonDocumentDeletedWithAuthContextonDocumentUpdatedWithAuthContext
Python
on_document_created_with_auth_contexton_document_updated_with_auth_contexton_document_deleted_with_auth_contexton_document_written_with_auth_context
ดูข้อมูลเกี่ยวกับข้อมูลที่มีอยู่ในบริบทการตรวจสอบสิทธิ์ได้ที่ บริบทการตรวจสอบสิทธิ์ ตัวอย่างต่อไปนี้แสดงวิธีดึงข้อมูลการตรวจสอบสิทธิ์
Node.js
const {onDocumentWrittenWithAuthContext} = require('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
@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
});
});
Python
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({
# ...
})
ข้อจำกัด
- ไม่มีการรับประกันลำดับ การเปลี่ยนแปลงอย่างรวดเร็วอาจทริกเกอร์การเรียกใช้ฟังก์ชันตามลำดับที่ไม่คาดคิด
- ระบบจะส่งเหตุการณ์อย่างน้อย 1 ครั้ง แต่เหตุการณ์เดียวอาจส่งผลให้มีการเรียกใช้ฟังก์ชันหลายครั้ง หลีกเลี่ยงการพึ่ง กลไกการทำงานแบบ "ส่งครั้งเดียว" และเขียน ฟังก์ชันที่ไม่มีผลข้างเคียง
- ทริกเกอร์จะเชื่อมโยงกับฐานข้อมูลเดียว คุณไม่สามารถสร้างทริกเกอร์ที่ตรงกับฐานข้อมูลหลายรายการได้
- การลบฐานข้อมูลจะไม่ลบทริกเกอร์สำหรับฐานข้อมูลนั้นโดยอัตโนมัติ ทริกเกอร์จะหยุดส่งเหตุการณ์แต่จะยังคงอยู่จนกว่าคุณจะ ลบทริกเกอร์
- เอกสารที่มีขนาดใหญ่กว่า 10 MiB จะไม่รวมอยู่ในเพย์โหลดเหตุการณ์ หากต้องการดึงเอกสารที่จัดเวอร์ชัน ให้ใช้เวลาอ่านการกู้คืน ณ จุดเวลาหนึ่ง