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

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

• 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. अपने एक्सटेंशन फ़ंक्शन में, एडमिन SDK से Eventarc API को इंपोर्ट करें. साथ ही, उपयोगकर्ता की इंस्टॉलेशन सेटिंग का इस्तेमाल करके, इवेंट चैनल शुरू करें. ये सेटिंग, यहां दिए गए एनवायरमेंट वैरिएबल का इस्तेमाल करके दिखती हैं:

   • EVENTARC_CHANNEL: उस Eventarc चैनल का पूरी तरह क्वालिफ़ाइड नाम जिसके लिए उपयोगकर्ता ने इवेंट पब्लिश करने का विकल्प चुना है.
   • EXT_SELECTED_EVENTS: उन इवेंट टाइप की सूची जिन्हें कॉमा लगाकर अलग किया जाता है. इन इवेंट टाइप को उपयोगकर्ता ने पब्लिश करने का विकल्प चुना है. इस वैल्यू वाले चैनल को शुरू करने पर, एडमिन SDK टूल उन इवेंट को अपने-आप फ़िल्टर कर देता है जिन्हें उपयोगकर्ता ने नहीं चुना है.
   • EVENTARC_CLOUD_EVENT_SOURCE: क्लाउड इवेंट का सोर्स आइडेंटिफ़ायर. 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();
    });

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

उदाहरण

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

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

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

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

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

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