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

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

• 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 Event का सोर्स आइडेंटिफ़ायर. Admin 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 फ़ंक्शन को कॉल करता है जिसे उपयोगकर्ता ने तय किया है. वह आगे बढ़ने से पहले, पूरा होने का इंतज़ार करता है. आम तौर पर, इसके लिए रिस्पॉन्स की वैल्यू दिखाई जाती है. उपयोगकर्ता के दिए गए फ़ंक्शन में गड़बड़ी होने पर, एक्सटेंशन फ़ंक्शन में भी गड़बड़ी होती है.

सिंक्रोनस हुक को एक्सपोज़ करने के लिए:

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