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

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

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

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

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