يمكن أن تتضمّن إضافتك وظائف Cloud Tasks التي يتم تشغيلها عندما يمر مثيل إضافة في أي من أحداث مراحل النشاط التالية:
- تم تثبيت مثيل للإضافة.
- يتم تحديث مثيل من الإضافة إلى إصدار جديد
- تم تغيير إعدادات النسخة الافتراضية للإضافة.
وإحدى أهم حالات الاستخدام لهذه الميزة هي إعادة تعبئة البيانات. على سبيل المثال، لنفترض أنّك تنشئ إضافة تنشئ معاينات للصور المصغّرة للصور التي تم تحميلها إلى حزمة Cloud Storage. سيتم تنفيذ العمل الرئيسي للإضافة من خلال
دالة يشغلها حدث onFinalize
Cloud Storage.
ومع ذلك، لن تتمّ معالجة سوى الصور التي يتم تحميلها بعد تثبيت الإضافة. من خلال تضمين دالة يتم تشغيلها أثناء مرحلة نشاط onInstall
، يمكنك أيضًا إنشاء معاينات صور مصغّرة لأي
صور حالية عند تثبيت الإضافة.
تشمل بعض حالات الاستخدام الأخرى لمشغّلات أحداث مراحل النشاط ما يلي:
- إعداد عمليات ما بعد التثبيت تلقائيًا (إنشاء سجلات قاعدة البيانات والفهرسة وما إلى ذلك)
- إذا كان عليك نشر تغييرات غير متوافقة مع الإصدارات القديمة، يمكنك ترحيل البيانات تلقائيًا عند إجراء تحديث
معالِجات أحداث مراحل النشاط التي تدوم لفترة قصيرة
إذا كان من الممكن تنفيذ مهمتك بالكامل خلال
المدة القصوى لوظائف Cloud (9
دقائق باستخدام الجيل الأول من واجهة برمجة التطبيقات)، يمكنك كتابة معالج أحداث مراحل النشاط
كوظيفة واحدة يتم تشغيلها في حدث 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" باستخدام الإعدادات التلقائية، ويمكنك اختياريًا ضبط هذه الإعدادات.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: {}
تسجيل الدالة كمعالِج لحدث واحد أو أكثر في مراحل النشاط:
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()
في "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
كما هو موضّح في القسم السابق.
حالة إعداد التقارير
عند انتهاء جميع وظائف المعالجة، سواء بنجاح أو عند وجود خطأ، يمكنك الإبلاغ عن حالة المهمة باستخدام طرق تشغيل إضافة SDK للمشرف. ويمكن للمستخدمين الاطّلاع على هذه الحالة في صفحة تفاصيل الإضافة في وحدة تحكُّم Firebase.
اكتمال بنجاح والأخطاء غير الفادحة
للإبلاغ عن عملية إكمال ناجحة وأخطاء غير فادحة (أي الأخطاء التي لا تضع الإضافة في حالة معطّلة)، استخدِم طريقة وقت تشغيل الإضافة setProcessingState()
في "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" باستخدام الإعدادات التلقائية عند تثبيت
مثيل الإضافة. بدلاً من ذلك، يمكنك ضبط حدود التزامن في قائمة انتظار المهام وإعادة المحاولة من خلال توفير قيم محددة:
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
يُرجى الاطّلاع على ضبط قوائم انتظار "مهام Google" في Cloud في مستندات 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
معالِجات أحداث مراحل النشاط لإضافة البيانات السابقة.