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

يمكن أن تتضمن إضافتك دالة Cloud Tasks. التي يتم تشغيلها عندما يمر مثيل الإضافة بأي مما يلي الأحداث في مراحل النشاط:

• تم تثبيت مثيل للإضافة.
• يتم تحديث مثيل من الإضافة إلى إصدار جديد
• تم تغيير إعدادات النسخة الافتراضية للإضافة.

وإحدى أهم حالات الاستخدام لهذه الميزة هي إعادة تعبئة البيانات. بالنسبة لنفترض أنك تنشئ إضافة تنشئ معاينات للصور المصغرة من الصور تم تحميلها إلى حزمة Cloud Storage. الوظيفة الرئيسية للإضافة سيتم تنفيذه في دالة يتم تشغيلها بواسطة حدث Cloud Storage onFinalize. ومع ذلك، لن يتم تحميل سوى الصور التي يتم تحميلها بعد تثبيت الإضافة. ومعالجتها. من خلال تضمين دالة يتم تشغيلها بواسطة onInstall في مراحل النشاط، يمكنك أيضًا إنشاء معاينات صور مصغّرة لأي الصور الحالية عندما يتم تثبيت الإضافة.

تشمل بعض حالات الاستخدام الأخرى لمشغّلات أحداث مراحل النشاط ما يلي:

• إعداد عمليات ما بعد التثبيت تلقائيًا (إنشاء سجلات قاعدة البيانات والفهرسة وما إلى ذلك)
• إذا كان عليك نشر تغييرات غير متوافقة مع الإصدارات القديمة، انتقِل إلى البيانات التالية تلقائيًا البيانات عند التحديث

معالِجات أحداث مراحل النشاط التي تدوم لفترة قصيرة

إذا كان من الممكن تشغيل مهمتك بشكل كامل داخل الحد الأقصى للمدة Cloud Functions (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 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: {}
   

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"

اكتمال بنجاح والأخطاء غير الفادحة

للإبلاغ عن إكمال ناجح والأخطاء غير الفادحة (الأخطاء التي لا تضع الإضافة إلى حالة غير وظيفية)، فاستخدم حزمة SDK للمشرف طريقة وقت تشغيل الإضافة setProcessingState():

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 على {}، ستصبح إضافتك توفير قائمة انتظار "مهام Google" باستخدام الإعدادات التلقائية عندما تكون إحدى الإضافات المثيل المثبت. بدلاً من ذلك، يمكنك ضبط تزامن قائمة المهام السلوك وإعادة المحاولة من خلال تقديم قيم معيّنة:

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