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

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

• इवेंटार्क इवेंट : उपयोगकर्ताओं को घटनाओं पर अतुल्यकालिक रूप से प्रतिक्रिया करने का तरीका देने के लिए, आप इवेंटार्क पर प्रकाशित कर सकते हैं। उपयोगकर्ता ईवेंट हैंडलर फ़ंक्शंस को तैनात कर सकते हैं, उदाहरण के लिए, लंबे समय से चल रहे कार्यों के पूरा होने के बाद सूचनाएं भेज सकते हैं, या वे अपने स्वयं के पोस्ट-प्रोसेसिंग फ़ंक्शंस को परिभाषित कर सकते हैं।

• सिंक्रोनस हुक : उपयोगकर्ताओं को आपके एक्सटेंशन में ब्लॉकिंग लॉजिक जोड़ने का तरीका देने के लिए, आप एक्सटेंशन के संचालन में पूर्वनिर्धारित बिंदुओं पर सिंक्रोनस हुक जोड़ सकते हैं। इन बिंदुओं पर, आप उपयोगकर्ता-प्रदाता फ़ंक्शन चलाते हैं और इसके पूरा होने के बाद ही आगे बढ़ते हैं। प्री-प्रोसेसिंग कार्य अक्सर इसी श्रेणी में आते हैं।

एक एक्सटेंशन किसी एक या दोनों तरीकों का उपयोग कर सकता है।

इवेंटआर्क घटनाएँ

किसी एक्सटेंशन से ईवेंट प्रकाशित करने के लिए:

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. अपने एक्सटेंशन फ़ंक्शंस में, एडमिन एसडीके से इवेंटार्क एपीआई आयात करें और उपयोगकर्ता की इंस्टॉलेशन सेटिंग्स का उपयोग करके एक इवेंट चैनल प्रारंभ करें। ये सेटिंग्स निम्नलिखित पर्यावरण चर का उपयोग करके प्रदर्शित की जाती हैं:

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

अधिक जानकारी के लिए कस्टम ईवेंट ट्रिगर देखें।

उदाहरण

आधिकारिक रिसाइज़ इमेज एक्सटेंशन एक छवि का आकार बदलने के बाद इवेंटार्क पर प्रकाशित करके एक अतुल्यकालिक हुक प्रदान करता है।

तुल्यकालिक हुक

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

एक सिंक्रोनस हुक उपयोगकर्ता द्वारा परिभाषित HTTPS कॉल करने योग्य क्लाउड फ़ंक्शन को कॉल करता है और जारी रखने से पहले पूरा होने की प्रतीक्षा करता है (संभवतः लौटाए गए मान के साथ)। उपयोगकर्ता द्वारा प्रदत्त फ़ंक्शन में त्रुटि के परिणामस्वरूप एक्सटेंशन फ़ंक्शन में त्रुटि होती है।

एक तुल्यकालिक हुक को उजागर करने के लिए:

1. अपने एक्सटेंशन में एक पैरामीटर जोड़ें जो उपयोगकर्ताओं को अपने कस्टम क्लाउड फ़ंक्शन के URL के साथ एक्सटेंशन को कॉन्फ़िगर करने की अनुमति देता है। उदाहरण के लिए:

   - 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. अपने एक्सटेंशन के उस बिंदु पर जहां आप हुक को उजागर करना चाहते हैं, उसके URL का उपयोग करके फ़ंक्शन को कॉल करें। उदाहरण के लिए:

   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 फ़ाइल में दस्तावेज़ित करें।

   प्रत्येक हुक के लिए, निम्नलिखित दस्तावेज करें:

   • इसका इच्छित उद्देश्य
   • आपके एक्सटेंशन के तर्क में यह बिंदु चलता है
   • इसके अपेक्षित इनपुट और आउटपुट
   • इसके निष्पादन के लिए शर्तें (या विकल्प)।

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

उदाहरण

अल्गोलिया सर्च एक्सटेंशन अल्गोलिया को लिखने से पहले उपयोगकर्ता द्वारा प्रदत्त ट्रांसफॉर्म फ़ंक्शन को कॉल करने के लिए एक सिंक्रोनस हुक प्रदान करता है।