ส่วนขยายของคุณอาจมีฟังก์ชัน Cloud Tasks ที่จะทริกเกอร์เมื่ออินสแตนซ์ของส่วนขยายผ่านเหตุการณ์อายุการใช้งานอย่างใดอย่างหนึ่งต่อไปนี้
- ติดตั้งส่วนขยายแล้ว 1 รายการ
- อินสแตนซ์ของส่วนขยายได้รับการอัปเดตเป็นเวอร์ชันใหม่
- เปลี่ยนแปลงการกำหนดค่าของอินสแตนซ์ส่วนขยายแล้ว
กรณีการใช้งานที่สำคัญที่สุดอย่างหนึ่งของฟีเจอร์นี้คือการทดแทนข้อมูล ตัวอย่างเช่น สมมติว่าคุณสร้างส่วนขยายที่สร้างตัวอย่างภาพขนาดย่อของรูปภาพที่อัปโหลดไปยังที่เก็บข้อมูล Cloud Storage งานหลักของส่วนขยายคือในฟังก์ชันที่ทริกเกอร์โดยเหตุการณ์ Cloud Storage ของ onFinalize
อย่างไรก็ตาม ระบบจะประมวลผลเฉพาะรูปภาพที่อัปโหลดหลังจากติดตั้งส่วนขยายแล้วเท่านั้น การรวมฟังก์ชันที่ทริกเกอร์โดยเหตุการณ์ในวงจร onInstall
ไว้ในส่วนขยายจะช่วยให้คุณสร้างตัวอย่างภาพขนาดย่อของรูปภาพที่มีอยู่ได้เมื่อติดตั้งส่วนขยายแล้ว
กรณีการใช้งานทริกเกอร์เหตุการณ์วงจรอื่นๆ บางส่วน ได้แก่
- ทำให้การตั้งค่าหลังการติดตั้งเป็นแบบอัตโนมัติ (การสร้างระเบียนฐานข้อมูล การจัดทำดัชนี ฯลฯ)
- หากคุณจำเป็นต้องเผยแพร่การเปลี่ยนแปลงที่เข้ากันไม่ได้กับเวอร์ชันก่อน ให้ย้ายข้อมูลโดยอัตโนมัติเมื่อมีการอัปเดต
เครื่องจัดการเหตุการณ์อายุการใช้งานสั้น
หากงานทำงานได้โดยสมบูรณ์ภายในระยะเวลา Cloud Functions สูงสุด (9 นาทีเมื่อใช้ API รุ่นที่ 1) คุณจะเขียนเครื่องมือจัดการเหตุการณ์วงจรให้เป็นฟังก์ชันเดียวที่จะทริกเกอร์ในเหตุการณ์ onDispatch
ของคิวงานได้ โดยทำดังนี้
export const myTaskFunction = functions.tasks.taskQueue()
.onDispatch(async () => {
// Complete your lifecycle event handling task.
// ...
// When processing is complete, report status to the user (see below).
});
จากนั้นในไฟล์ extension.yaml
ของส่วนขยาย ให้ทำดังนี้
ลงทะเบียนฟังก์ชันเป็นทรัพยากรส่วนขยายที่มีชุดพร็อพเพอร์ตี้
taskQueueTrigger
หากตั้งค่าtaskQueueTrigger
เป็นแผนที่ว่างเปล่า ({}
) ส่วนขยายจะจัดสรรคิว Cloud Tasks โดยใช้การตั้งค่าเริ่มต้น โดยคุณจะปรับแต่งการตั้งค่าเหล่านี้หรือไม่ก็ได้resources: - name: myTaskFunction type: firebaseextensions.v1beta.function description: >- Describe the task performed when the function is triggered by a lifecycle event properties: location: ${LOCATION} taskQueueTrigger: {}
ลงทะเบียนฟังก์ชันเป็นตัวแฮนเดิลสําหรับเหตุการณ์ในวงจรอย่างน้อย 1 เหตุการณ์ ดังนี้
resources: - ... lifecycleEvents: onInstall: function: myTaskFunction processingMessage: Resizing your existing images onUpdate: function: myOtherTaskFunction processingMessage: Setting up your extension onConfigure: function: myOtherTaskFunction processingMessage: Setting up your extension
คุณสามารถลงทะเบียนฟังก์ชันสําหรับเหตุการณ์ใดก็ได้ต่อไปนี้
onInstall
,onUpdate
และonConfigure
กิจกรรมทั้งหมดเหล่านี้เป็นตัวเลือกแนะนำ: หากส่วนขยายไม่จำเป็นต้องทำงานในการประมวลผล ให้เพิ่มพารามิเตอร์ที่กำหนดค่าโดยผู้ใช้เพื่อให้ผู้ใช้เลือกว่าจะเปิดใช้หรือไม่
ตัวอย่างเช่น เพิ่มพารามิเตอร์ต่อไปนี้
params: - param: DO_BACKFILL label: Backfill existing images description: > Should existing, unresized images in the Storage bucket be resized as well? type: select options: - label: Yes value: true - label: No value: false
และในฟังก์ชัน หากตั้งค่าพารามิเตอร์เป็น
false
ให้ออกก่อนกำหนดexport const myTaskFunction = functions.tasks.taskQueue() .onDispatch(async () => { if (!process.env.DO_BACKFILL) { await runtime.setProcessingState( "PROCESSING_COMPLETE", "Existing images were not resized." ); return; } // Complete your lifecycle event handling task. // ... });
การดำเนินงานที่ใช้เวลานาน
หากงานไม่เสร็จสมบูรณ์ภายในระยะเวลาสูงสุดของ Cloud Functions ให้แบ่งงานเป็นงานย่อยและดำเนินการแต่ละงานย่อยตามลำดับโดยจัดคิวงานด้วยเมธอด TaskQueue.enqueue()
ของ Admin SDK
ตัวอย่างเช่น สมมติว่าคุณต้องการทดแทนข้อมูล Cloud Firestore คุณสามารถแบ่งคอลเล็กชันเอกสารออกเป็นส่วนๆ ได้โดยใช้เคอร์เซอร์การค้นหา หลังจากประมวลผลกลุ่ม ให้เลื่อนออฟเซ็ตเริ่มต้นและจัดคิวการเรียกใช้ฟังก์ชันอื่นตามที่แสดงด้านล่าง
import { getFirestore } from "firebase-admin/firestore";
import { getFunctions } from "firebase-admin/functions";
exports.backfilldata = functions.tasks.taskQueue().onDispatch(async (data) => {
// When a lifecycle event triggers this function, it doesn't pass any data,
// so an undefined offset indicates we're on our first invocation and should
// start at offset 0. On subsequent invocations, we'll pass an explicit
// offset.
const offset = data["offset"] ?? 0;
// Get a batch of documents, beginning at the offset.
const snapshot = await getFirestore()
.collection(process.env.COLLECTION_PATH)
.startAt(offset)
.limit(DOCS_PER_BACKFILL)
.get();
// Process each document in the batch.
const processed = await Promise.allSettled(
snapshot.docs.map(async (documentSnapshot) => {
// Perform the processing.
})
);
// If we processed a full batch, there are probably more documents to
// process, so enqueue another invocation of this function, specifying
// the offset to start with.
//
// If we processed less than a full batch, we're done.
if (processed.length == DOCS_PER_BACKFILL) {
const queue = getFunctions().taskQueue(
"backfilldata",
process.env.EXT_INSTANCE_ID
);
await queue.enqueue({
offset: offset + DOCS_PER_BACKFILL,
});
} else {
// Processing is complete. Report status to the user (see below).
}
});
เพิ่มฟังก์ชันลงใน extension.yaml
ตามที่อธิบายไว้ในส่วนก่อนหน้า
สถานะการรายงาน
เมื่อฟังก์ชันการประมวลผลทั้งหมดเสร็จสิ้นหรือมีข้อผิดพลาด ให้รายงานสถานะของงานโดยใช้วิธีรันไทม์ของส่วนขยายของ Admin SDK ผู้ใช้ดูสถานะนี้ได้ในหน้ารายละเอียดส่วนขยายในคอนโซล Firebase
ข้อผิดพลาดที่ไม่ร้ายแรงและเสร็จสมบูรณ์แล้ว
หากต้องการรายงานข้อผิดพลาดที่สำเร็จและข้อผิดพลาดที่ไม่ร้ายแรง (ข้อผิดพลาดที่ไม่ได้ทำให้ส่วนขยายอยู่ในสถานะไม่ทำงาน) ให้ใช้เมธอดรันไทม์ของส่วนขยาย setProcessingState()
ของ Admin SDK ดังนี้
import { getExtensions } from "firebase-admin/extensions";
// ...
getExtensions().runtime().setProcessingState(processingState, message);
คุณตั้งค่าสถานะต่อไปนี้ได้
รัฐที่ไม่ร้ายแรง | |
---|---|
PROCESSING_COMPLETE |
ใช้เพื่อรายงานงานที่ทำสำเร็จ เช่น getExtensions().runtime().setProcessingState( "PROCESSING_COMPLETE", `Backfill complete. Successfully processed ${numSuccess} documents.` ); |
PROCESSING_WARNING |
ใช้เพื่อรายงานความสำเร็จบางส่วน เช่น getExtensions().runtime().setProcessingState( "PROCESSING_WARNING", `Backfill complete. ${numSuccess} documents processed successfully.` + ` ${numFailed} documents failed to process. ${listOfErrors}.` + ` ${instructionsToFixTheProblem}` ); |
PROCESSING_FAILED |
ใช้เพื่อรายงานข้อผิดพลาดที่ทำให้งานไม่สำเร็จ แต่ไม่ปล่อยให้ส่วนขยายใช้งานไม่ได้ เช่น getExtensions().runtime().setProcessingState( "PROCESSING_FAILED", `Backfill failed. ${errorMsg} ${optionalInstructionsToFixTheProblem}.` ); หากต้องการรายงานข้อผิดพลาดที่ทำให้ส่วนขยายใช้งานไม่ได้ โปรดเรียกใช้
|
NONE |
ใช้เพื่อล้างสถานะของงาน คุณเลือกใช้ตัวเลือกนี้เพื่อล้างข้อความสถานะจากคอนโซลได้ (เช่น เมื่อเวลาผ่านไประยะหนึ่งนับตั้งแต่การตั้งค่า getExtensions().runtime().setProcessingState("NONE"); |
ข้อผิดพลาดร้ายแรง
หากเกิดข้อผิดพลาดที่ทำให้ส่วนขยายไม่ทำงาน เช่น งานการตั้งค่าที่จำเป็นล้มเหลว ให้รายงานข้อผิดพลาดร้ายแรงที่มี setFatalError()
ดังนี้
import { getExtensions } from "firebase-admin/extensions";
// ...
getExtensions().runtime().setFatalError(`Post-installation setup failed. ${errorMessage}`);
การปรับแต่งคิวงาน
หากคุณตั้งค่าพร็อพเพอร์ตี้ taskQueueTrigger
เป็น {}
ส่วนขยายจะจัดสรรคิว Cloud Tasks ตามการตั้งค่าเริ่มต้นเมื่อมีการติดตั้งอินสแตนซ์ของส่วนขยาย หรือปรับขีดจำกัดการเกิดขึ้นพร้อมกันของคิวงานและพยายามดำเนินการอีกครั้งได้ด้วยการระบุค่าที่เจาะจง ดังนี้
resources:
- name: myTaskFunction
type: firebaseextensions.v1beta.function
description: >-
Perform a task when triggered by a lifecycle event
properties:
location: ${LOCATION}
taskQueueTrigger:
rateLimits:
maxConcurrentDispatches: 1000
maxDispatchesPerSecond: 500
retryConfig:
maxAttempts: 100 # Warning: setting this too low can prevent the function from running
minBackoffSeconds: 0.1
maxBackoffSeconds: 3600
maxDoublings: 16
lifecycleEvents:
onInstall:
function: myTaskFunction
processingMessage: Resizing your existing images
onUpdate:
function: myTaskFunction
processingMessage: Setting up your extension
onConfigure:
function: myOtherTaskFunction
processingMessage: Setting up your extension
โปรดดูรายละเอียดเกี่ยวกับพารามิเตอร์เหล่านี้ที่หัวข้อกำหนดค่าคิว Cloud Tasks ในเอกสารของ Google Cloud
อย่าพยายามระบุพารามิเตอร์คิวงานด้วยการส่งผ่านไปยัง taskQueue()
ระบบจะไม่พิจารณาการตั้งค่าเหล่านี้เพื่อใช้การกำหนดค่าใน extension.yaml
และค่าเริ่มต้นของการกำหนดค่า
ตัวอย่างเช่น วิธีนี้ไม่ได้ผล
export const myBrokenTaskFunction = functions.tasks
// DON'T DO THIS IN AN EXTENSION! THESE SETTINGS ARE IGNORED.
.taskQueue({
retryConfig: {
maxAttempts: 5,
minBackoffSeconds: 60,
},
rateLimits: {
maxConcurrentDispatches: 1000,
maxDispatchesPerSecond: 10,
},
})
.onDispatch(
// ...
);
พร็อพเพอร์ตี้ taskQueueTrigger
ใน extension.yaml
เป็นวิธีเดียวในการกำหนดค่าคิวงานของส่วนขยาย
ตัวอย่าง
ส่วนขยาย storage-resize-images
,
firestore-bigquery-export
และ firestore-translate-text
อย่างเป็นทางการทั้งหมดใช้เครื่องจัดการเหตุการณ์ตลอดอายุการใช้งานเพื่อทดแทนข้อมูล