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

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

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

इस सुविधा के सबसे अहम इस्तेमाल के उदाहरणों में से एक है डेटा को बैकफ़िल करना. उदाहरण के लिए, मान लें कि आपने एक ऐसा एक्सटेंशन बनाया है जो बकेट में अपलोड की गई इमेज के थंबनेल की झलक जनरेट करता है.Cloud Storage आपके एक्सटेंशन का मुख्य काम , onFinalize Cloud Storage इवेंट से ट्रिगर होने वाले फ़ंक्शन में किया जाएगा. हालांकि, एक्सटेंशन इंस्टॉल होने के बाद अपलोड की गई इमेज को ही प्रोसेस किया जाएगा. अपने एक्सटेंशन में onInstall लाइफ़साइकल इवेंट से ट्रिगर होने वाला फ़ंक्शन शामिल करके, एक्सटेंशन इंस्टॉल होने पर पहले से मौजूद इमेज के थंबनेल की झलक भी जनरेट की जा सकती है.

लाइफ़साइकल इवेंट ट्रिगर के कुछ अन्य इस्तेमाल के उदाहरण यहां दिए गए हैं:

  • इंस्टॉल होने के बाद सेटअप को ऑटोमेट करना (डेटाबेस रिकॉर्ड बनाना, इंडेक्सिंग करना वगैरह)
  • अगर आपको पीछे की ओर काम न करने वाले बदलाव पब्लिश करने हैं, तो अपडेट होने पर डेटा को अपने-आप माइग्रेट करना

कम समय में पूरे होने वाले लाइफ़साइकल इवेंट हैंडलर

अगर आपका टास्क, ज़्यादा से ज़्यादा अवधि (पहली जनरेशन के एपीआई का इस्तेमाल करके नौ मिनट) में पूरी तरह से पूरा हो सकता है, तो अपने लाइफ़साइकल इवेंट हैंडलर को एक ऐसे फ़ंक्शन के तौर पर लिखा जा सकता है जो टास्क की लाइन में लगे onDispatch इवेंट पर ट्रिगर होता है:Cloud Functions

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

टास्क पूरा होने और नुकसान न पहुंचाने वाली गड़बड़ियों की जानकारी देना

टास्क पूरा होने और नुकसान न पहुंचाने वाली गड़बड़ियों (ऐसी गड़बड़ियां जिनकी वजह से एक्सटेंशन काम नहीं करता) की जानकारी देने के लिए, Admin SDK के setProcessingState() एक्सटेंशन रनटाइम के तरीके का इस्तेमाल करें:

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}.`
);

ऐसी गड़बड़ियों की जानकारी देने के लिए जिनकी वजह से एक्सटेंशन काम नहीं करता, do call setFatalError().
NONE

टास्क का स्टेटस हटाने के लिए इस्तेमाल करें. इसका इस्तेमाल, कंसोल से स्टेटस मैसेज हटाने के लिए भी किया जा सकता है उदाहरण के लिए, PROCESSING_COMPLETE सेट करने के बाद, कुछ समय बीत जाने पर उदाहरण:

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 प्रॉपर्टी ही, एक्सटेंशन की टास्क की लाइनों को कॉन्फ़िगर करने का एकमात्र तरीका है.

उदाहरण

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