التعامل مع أحداث مراحل نشاط الإضافة

يمكن أن تتضمّن إضافتك وظائف 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 للإضافة، نفِّذ ما يلي:

1. سجِّل وظيفتك كمورد إضافات باستخدام مجموعة السمات 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: {}
   

2. تسجيل الدالة كمعالِج لحدث واحد أو أكثر في مراحل النشاط:

   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. كل هذه الأحداث اختيارية.

3. إجراء مقترَح: إذا لم تكن مهمة المعالجة مطلوبة حتى تعمل الإضافة، أضِف مَعلمة تم ضبطها من قِبل المستخدم تتيح للمستخدمين اختيار تفعيلها أو عدم تفعيلها.

   على سبيل المثال، أضِف مَعلمة مثل ما يلي:

   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);

يمكنك ضبط الحالات التالية:

getExtensions().runtime().setProcessingState(
  "PROCESSING_COMPLETE",
  `Backfill complete. Successfully processed ${numSuccess} documents.`
);

getExtensions().runtime().setProcessingState(
  "PROCESSING_WARNING",
  `Backfill complete. ${numSuccess} documents processed successfully.`
    + ` ${numFailed} documents failed to process. ${listOfErrors}.`
    + ` ${instructionsToFixTheProblem}`
);

getExtensions().runtime().setProcessingState(
  "PROCESSING_FAILED",
  `Backfill failed. ${errorMsg} ${optionalInstructionsToFixTheProblem}.`
);

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 معالِجات أحداث مراحل النشاط لإضافة البيانات السابقة.