अपने एक्सटेंशन के लाइफ़साइकल इवेंट मैनेज करना

आपके एक्सटेंशन में ऐसे Cloud Tasks फ़ंक्शन शामिल किए जा सकते हैं जो एक्सटेंशन इंस्टेंस के लाइफ़साइकल के इनमें से किसी भी इवेंट के दौरान ट्रिगर होते हैं:

• एक्सटेंशन का कोई इंस्टेंस इंस्टॉल हो
• एक्सटेंशन के किसी इंस्टेंस को नए वर्शन में अपडेट किया जाता है
• एक्सटेंशन इंस्टेंस का कॉन्फ़िगरेशन बदला गया हो

इस सुविधा का इस्तेमाल करने के सबसे अहम उदाहरणों में से एक है डेटा को बैकफ़िल करना. उदाहरण के लिए, मान लें कि आपने एक ऐसा एक्सटेंशन बनाया है जो Cloud Storage बकेट में अपलोड की गई इमेज के थंबनेल जनरेट करता है. आपके एक्सटेंशन का मुख्य काम, onFinalize Cloud Storage इवेंट से ट्रिगर किए गए फ़ंक्शन में किया जाएगा. हालांकि, एक्सटेंशन इंस्टॉल होने के बाद अपलोड की गई इमेज ही प्रोसेस की जाएंगी. अपने एक्सटेंशन में 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 की तय सीमा के अंदर पूरा नहीं हो पा रहा है, तो टास्क को सबटास्क में बांटें और Admin SDK के TaskQueue.enqueue() तरीके से जॉब को लाइन में लगाकर, हर सबटास्क को क्रम से पूरा करें.

उदाहरण के लिए, मान लें कि आपको 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 कंसोल में एक्सटेंशन की जानकारी वाले पेज पर यह स्टेटस देख सकते हैं.

प्रोसेस पूरी हो गई और गड़बड़ियां नहीं हुईं

एक्सटेंशन के इंस्टॉल होने और गड़बड़ियों की रिपोर्ट करने के लिए, Admin 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 प्रॉपर्टी को {} पर सेट किया है, तो एक्सटेंशन इंस्टॉल होने पर, आपका एक्सटेंशन डिफ़ॉल्ट सेटिंग के साथ 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

इन पैरामीटर के बारे में ज़्यादा जानने के लिए, Google Cloud के दस्तावेज़ों में Cloud Tasks की सूचियों को कॉन्फ़िगर करना लेख पढ़ें.

टास्क कतार के पैरामीटर को 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(
    // ...
  );

extension.yaml में मौजूद taskQueueTrigger प्रॉपर्टी, एक्सटेंशन की टास्क सूचियों को कॉन्फ़िगर करने का एकमात्र तरीका है.

उदाहरण

डेटा को बैकफ़िल करने के लिए, आधिकारिक storage-resize-images, firestore-bigquery-export, और firestore-translate-text एक्सटेंशन, लाइफ़साइकल इवेंट हैंडलर का इस्तेमाल करते हैं.