किसी एक्सटेंशन में उपयोगकर्ता हुक जोड़ें

आपके एक्सटेंशन को इंस्टॉल करने वाले उपयोगकर्ताओं को यह सुविधा दी जा सकती है कि वे आपके एक्सटेंशन को एक्ज़ीक्यूट करने के लिए, अपने कस्टम लॉजिक का इस्तेमाल कर सकें. इसे पूरा करने के दो तरीके हैं:

• Eventarc इवेंट: उपयोगकर्ताओं को इवेंट पर असींक्रोनस तरीके से प्रतिक्रिया देने का विकल्प देने के लिए, इन्हें Eventarc पर पब्लिश किया जा सकता है. उपयोगकर्ता, इवेंट हैंडलर फ़ंक्शन डिप्लॉय कर सकते हैं. उदाहरण के लिए, लंबे समय तक चलने वाले टास्क पूरे होने के बाद सूचनाएं भेजना या पोस्ट-प्रोसेसिंग फ़ंक्शन तय करना.

• सिंक्रोनस हुक: उपयोगकर्ताओं को आपके एक्सटेंशन में ब्लॉकिंग लॉजिक जोड़ने का तरीका देने के लिए, एक्सटेंशन के ऑपरेशन में पहले से तय किए गए पॉइंट पर सिंक्रोनस हुक जोड़े जा सकते हैं. इन पॉइंट पर, उपयोगकर्ता-प्रोवाइडर फ़ंक्शन को चलाया जाता है और इसके पूरा होने के बाद ही आगे की कार्रवाई की जाती है. प्रोसेस से पहले के टास्क अक्सर इस कैटगरी में आते हैं.

एक्सटेंशन, इनमें से किसी एक या दोनों तरीकों का इस्तेमाल कर सकता है.

Eventarc इवेंट

एक्सटेंशन से इवेंट पब्लिश करने के लिए:

1. उन इवेंट टाइप के बारे में बताएं जिन्हें आपको extension.yaml फ़ाइल में पब्लिश करना है:

   events:
     - type: publisher-id.extension-name.version.event-name
       description: event-description
     - type: publisher-id.extension-name.version.another-event-name
       description: another-event-description
   

   type आइडेंटिफ़ायर, बिंदु से अलग किए गए कई फ़ील्ड से बना होता है. पब्लिशर आईडी, एक्सटेंशन का नाम, और इवेंट का नाम वाले फ़ील्ड ज़रूरी हैं. वर्शन फ़ील्ड का सुझाव दिया जाता है. पब्लिश किए जाने वाले हर इवेंट टाइप के लिए, इवेंट का ऐसा नाम चुनें जो यूनीक हो और उससे इवेंट के बारे में जानकारी मिलती हो.

   उदाहरण के लिए, storage-resize-images एक्सटेंशन एक इवेंट टाइप का एलान करता है:

   events:
     - type: firebase.extensions.storage-resize-images.v1.complete
       description: |
         Occurs when image resizing completes. The event will contain further
         details about specific formats and sizes.
   

   एक्सटेंशन इंस्टॉल करने के बाद, उपयोगकर्ता चुन सकेंगे कि उन्हें किन इवेंट की सदस्यता लेनी है.

2. अपने एक्सटेंशन फ़ंक्शन में, Admin SDK से Eventarc API इंपोर्ट करें और उपयोगकर्ता की इंस्टॉलेशन सेटिंग का इस्तेमाल करके, इवेंट चैनल को शुरू करें. इन सेटिंग को इन एनवायरमेंट वैरिएबल का इस्तेमाल करके दिखाया जाता है:

   • EVENTARC_CHANNEL: उस Eventarc चैनल का पूरा नाम जिस पर उपयोगकर्ता ने इवेंट पब्लिश करने का विकल्प चुना है.
   • EXT_SELECTED_EVENTS: उपयोगकर्ता ने जिन इवेंट टाइप को पब्लिश करने के लिए चुना है उनकी सूची, जिसमें कॉमा लगाकर अलग किया गया है. इस वैल्यू वाले चैनल को शुरू करने पर, एडमिन SDK टूल उन इवेंट को अपने-आप फ़िल्टर कर देता है जिन्हें उपयोगकर्ता ने नहीं चुना है.
   • EVENTARC_CLOUD_EVENT_SOURCE: क्लाउड इवेंट का सोर्स आइडेंटिफ़ायर. एडमिन SDK टूल, पब्लिश किए गए इवेंट के source फ़ील्ड में इस वैल्यू को अपने-आप पास करता है. आम तौर पर, आपको इस वैरिएबल का साफ़ तौर पर इस्तेमाल करने की ज़रूरत नहीं होती.

   अगर इवेंट इंस्टॉल करते समय चालू नहीं किए गए थे, तो ये वैरिएबल तय नहीं होंगे. इवेंट चैनल को शुरू करने के लिए, इस फ़ैक्ट का इस्तेमाल सिर्फ़ तब किया जा सकता है, जब इवेंट चालू हों:

   import * as admin from "firebase-admin";
   import {getEventarc} from 'firebase-admin/eventarc';
   
   admin.initializeApp();
   
   // Set eventChannel to a newly-initialized channel, or `undefined` if events
   // aren't enabled.
   const eventChannel =
     process.env.EVENTARC_CHANNEL &&
     getEventarc().channel(process.env.EVENTARC_CHANNEL, {
       allowedEventTypes: process.env.EXT_SELECTED_EVENTS,
     });
   

3. अपने एक्सटेंशन में उन पॉइंट पर चैनल पर इवेंट पब्लिश करें जिन्हें आपको उपयोगकर्ताओं को दिखाना है. उदाहरण के लिए:

   // If events are enabled, publish a `complete` event to the configured
   // channel.
   eventChannel && eventChannel.publish({
       type: 'firebase.extensions.storage-resize-images.v1.complete',
       subject: filename,  // the name of the original file
       data: {
         // ...
       }
   });
   

4. आपके प्रकाशित किए जाने वाले इवेंट का दस्तावेज़, PREINSTALL या POSTINSTALL फ़ाइल में दें.

   हर इवेंट के लिए, यहां दी गई जानकारी का दस्तावेज़ बनाएं:

   • कॉन्टेंट का मकसद
   • आपके एक्सटेंशन के लॉजिक में वह पॉइंट जहां यह चलता है
   • इसमें शामिल आउटपुट डेटा
   • इसे लागू करने की शर्तें

   इसके अलावा, उपयोगकर्ताओं को चेतावनी दें कि वे अपने इवेंट हैंडलर में ऐसी कोई भी कार्रवाई न करें जो उसी एक्सटेंशन को ट्रिगर कर सकती हो. इस वजह से, अनगिनत लूप बन सकता है.

किसी एक्सटेंशन से इवेंट पब्लिश करने पर, उपयोगकर्ता कस्टम लॉजिक के साथ जवाब देने के लिए इवेंट हैंडलर डिप्लॉय कर सकते हैं.

उदाहरण के लिए, नीचे दिए गए उदाहरण में, साइज़ बदलने के बाद ओरिजनल इमेज को मिटा दिया जाता है. ध्यान दें कि यह उदाहरण हैंडलर इवेंट की subject प्रॉपर्टी का इस्तेमाल करता है. इस मामले में यह इमेज का मूल फ़ाइल नाम है.

exports.onimageresized = onCustomEventPublished(
    "firebase.extensions.storage-resize-images.v1.complete",
    (event) => {
      logger.info("Received image resize completed event", event);
      // For example, delete the original.
      return admin.storage()
          .bucket("my-project.appspot.com")
          .file(event.subject)
          .delete();
    });

ज़्यादा जानकारी के लिए, कस्टम इवेंट ट्रिगर देखें.

उदाहरण

इमेज का साइज़ बदलने वाला आधिकारिक एक्सटेंशन, इमेज का साइज़ बदलने के बाद Eventarc पर पब्लिश करके, असाइनमेंट पूरा होने के बाद होने वाली कार्रवाई का हुक उपलब्ध कराता है.

सिंक्रोनस हुक

जब आपको उपयोगकर्ताओं को ऐसा हुक देना हो जिसे आपके एक्सटेंशन के किसी फ़ंक्शन के काम करने के लिए पूरा करना ज़रूरी हो, तो सिंक्रोनस हुक का इस्तेमाल करें.

सिंक्रोनस हुक, उपयोगकर्ता के तय किए गए एचटीटीपीएस कॉल किए जा सकने वाले Cloud Function को कॉल करता है. साथ ही, आगे बढ़ने से पहले, कॉल के पूरा होने का इंतज़ार करता है. ऐसा हो सकता है कि कॉल के पूरा होने पर कोई वैल्यू भी मिल जाए. उपयोगकर्ता के दिए गए फ़ंक्शन में किसी गड़बड़ी की वजह से, एक्सटेंशन फ़ंक्शन में गड़बड़ी हो सकती है.

सिंक्रोनस हुक को दिखाने के लिए:

1. अपने एक्सटेंशन में ऐसा पैरामीटर जोड़ें जो उपयोगकर्ताओं को उनके कस्टम Cloud Function के लिए, यूआरएल के साथ एक्सटेंशन कॉन्फ़िगर करने की अनुमति देता हो. उदाहरण के लिए:

   - param: PREPROCESSING_FUNCTION
     label: Pre-processing function URL
     description: >
       An HTTPS callable function that will be called to transform the input data
       before it is processed by this function.
     type: string
     example: https://us-west1-my-project-id.cloudfunctions.net/preprocessData
     required: false
   

2. अपने एक्सटेंशन में उस जगह पर, फ़ंक्शन के यूआरएल का इस्तेमाल करके फ़ंक्शन को कॉल करें जहां आपको हुक को एक्सपोज़ करना है. उदाहरण के लिए:

   const functions = require('firebase-functions/v1');
   const fetch = require('node-fetch');
   
   const preprocessFunctionURL = process.env.PREPROCESSING_FUNCTION;
   
   exports.yourFunctionName = functions.firestore.document("collection/{doc_id}")
       .onWrite((change, context) => {
         // PREPROCESSING_FUNCTION hook begins here.
         // If a preprocessing function is defined, call it before continuing.
         if (preprocessFunctionURL) {
           try {
             await fetch(preprocessFunctionURL); // Could also be a POST request if you want to send data.
           } catch (e) {
             // Preprocessing failure causes the function to fail.
             functions.logger.error("Preprocessor error:", e);
             return;
           }
         }
         // End of PREPROCESSING_FUNCTION hook.
   
         // Main function logic follows.
         // ...
       });
   

3. PREINSTALL या POSTINSTALL फ़ाइल में उपलब्ध कराए गए सभी हुक को दस्तावेज़ में शामिल करें.

   हर हुक के लिए, इन बातों का ध्यान रखें:

   • कॉन्टेंट का मकसद
   • आपके एक्सटेंशन के लॉजिक में वह पॉइंट जहां यह चलता है
   • इसके इनपुट और आउटपुट
   • इसे लागू करने की शर्तें (या विकल्प)

   इसके अलावा, उपयोगकर्ताओं को चेतावनी दें कि वे हुक फ़ंक्शन में ऐसी कोई कार्रवाई न करें जिससे एक ही एक्सटेंशन ट्रिगर हो जाए. इससे अनलिमिटेड लूप बन सकता है.

उदाहरण

Algolia Search एक्सटेंशन की मदद से, एल्गोरिदम पर लिखने से पहले, उपयोगकर्ता के दिए गए ट्रांसफ़ॉर्म फ़ंक्शन को कॉल करने के लिए एक सिंक्रोनस हुक मिलता है.