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

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

• 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: Cloud इवेंट का सोर्स आइडेंटिफ़ायर. एडमिन 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 फ़ंक्शन के यूआरएल के साथ एक्सटेंशन को कॉन्फ़िगर कर सकें. उदाहरण के लिए:

   - 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 एक्सटेंशन, Algolia में डेटा लिखने से पहले, उपयोगकर्ता के दिए गए ट्रांसफ़ॉर्म फ़ंक्शन को कॉल करने के लिए सिंक्रोनस हुक उपलब्ध कराता है.