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

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

• 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: उपयोगकर्ता ने जिन इवेंट टाइप को पब्लिश करने का विकल्प चुना है उनकी कॉमा लगाकर अलग की गई लिस्ट. इस वैल्यू के साथ चैनल शुरू करने पर, Admin 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.firebasestorage.app")
          .file(event.subject)
          .delete();
    });

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

उदाहरण

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

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

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

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