लाइब्रेरी

लाइब्रेरी एक स्क्रिप्ट प्रोजेक्ट है, जिसके फ़ंक्शन को अन्य स्क्रिप्ट में फिर से इस्तेमाल किया जा सकता है.

चेतावनी: लाइब्रेरी का इस्तेमाल करने वाली स्क्रिप्ट, एक स्क्रिप्ट प्रोजेक्ट में मौजूद सभी कोड के मुकाबले ज़्यादा तेज़ी से नहींचलती. लाइब्रेरी से डेवलपमेंट और रखरखाव को ज़्यादा आसान बनाया जा सकता है. हालांकि, उन प्रोजेक्ट में इसका कम इस्तेमाल करें जहां तेज़ी ज़रूरी है. इस समस्या की वजह से, ऐड-ऑन में लाइब्रेरी का इस्तेमाल सीमित तौर पर किया जाना चाहिए.

लाइब्रेरी का ऐक्सेस पाना

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

आपको उस लाइब्रेरी का स्क्रिप्ट आईडी चाहिए जिसे शामिल करना है. लाइब्रेरी का ऐक्सेस होने पर, प्रोजेक्ट सेटिंग पेज पर स्क्रिप्ट आईडी देखा जा सकता है.

स्क्रिप्ट प्रोजेक्ट में लाइब्रेरी जोड़ना

1. Apps Script एडिटर की बाईं ओर, "लाइब्रेरी" के बगल में, लाइब्रेरी जोड़ें पर क्लिक करें.
2. "स्क्रिप्ट आईडी" फ़ील्ड में, लाइब्रेरी का स्क्रिप्ट आईडी चिपकाएं.
3. खोजें पर क्लिक करें.
   अगर आपको कोई गड़बड़ी मिलती है, तो पक्का करें कि आपके पास उस प्रोजेक्ट का कम से कम व्यू-लेवल ऐक्सेस हो जिसे आपको शामिल करना है.
4. वर्शन ड्रॉपडाउन पर क्लिक करें और इस्तेमाल करने के लिए लाइब्रेरी का वर्शन चुनें.
5. देखें कि डिफ़ॉल्ट "आइडेंटिफ़ायर" का नाम वही है या नहीं जिसका इस्तेमाल आपको इस लाइब्रेरी के साथ करना है. यह वह नाम है जिसका इस्तेमाल आपकी स्क्रिप्ट, लाइब्रेरी के बारे में बताने के लिए करती है. उदाहरण के लिए, अगर आपने इसे Test पर सेट किया है, तो उस लाइब्रेरी के किसी तरीके को इस तरह से कॉल किया जा सकता है: Test.libraryMethod().
   अगर आपने किसी ऐसे आइडेंटिफ़ायर का इस्तेमाल किया है जो पहले से मौजूद किसी सेवा, जैसे कि MailApp या पहले से जोड़ी गई लाइब्रेरी के नाम से मेल खाता है, तो हाल ही में जोड़ी गई लाइब्रेरी, मौजूदा सेवा या लाइब्रेरी की जगह ले लेगी.
6. जोड़ें पर क्लिक करें.

लाइब्रेरी का इस्तेमाल करना

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

शामिल की गई लाइब्रेरी का रेफ़रंस दस्तावेज़ खोलने के लिए, यह तरीका अपनाएं:

स्क्रिप्ट एडिटर की बाईं ओर, लाइब्रेरी के नाम के बगल में, ज़्यादा > नए टैब में खोलें पर क्लिक करें.

लाइब्रेरी हटाना

स्क्रिप्ट एडिटर की बाईं ओर, लाइब्रेरी के नाम के बगल में, ज़्यादा > हटाएं > लाइब्रेरी हटाएं पर क्लिक करें.

अगर लेखक ने लाइब्रेरी मिटा दी है, तो भी आपको उसे शामिल की गई लाइब्रेरी की सूची से हटाना होगा.

लाइब्रेरी अपडेट करना

लाइब्रेरी का वर्शन बदला जा सकता है या उसका आइडेंटिफ़ायर अपडेट किया जा सकता है.

1. एडिटर की बाईं ओर, "लाइब्रेरी" में जाकर, लाइब्रेरी के नाम पर क्लिक करें.
2. बदलाव करने के बाद, सेव करें पर क्लिक करें.

लाइब्रेरी बनाना और शेयर करना

अपने स्क्रिप्ट प्रोजेक्ट को लाइब्रेरी के तौर पर इस्तेमाल और शेयर करने के लिए, यह तरीका अपनाएं.

1. अपनी स्क्रिप्ट का अलग-अलग वर्शन वाला डिप्लॉयमेंट बनाएं.
2. लाइब्रेरी के सभी संभावित उपयोगकर्ताओं के साथ, कम से कम व्यू-लेवल का ऐक्सेस शेयर करें.
3. उन उपयोगकर्ताओं को स्क्रिप्ट आईडी दें. यह आईडी, प्रोजेक्ट सेटिंग पेज पर मौजूद होता है.

सबसे सही तरीके

लाइब्रेरी लिखते समय इन दिशा-निर्देशों का पालन करें:

1. अपने प्रोजेक्ट के लिए कोई ऐसा नाम चुनें जो काम का हो. ऐसा इसलिए, क्योंकि जब आपकी लाइब्रेरी को दूसरे लोग शामिल करते हैं, तो इसका इस्तेमाल डिफ़ॉल्ट आइडेंटिफ़ायर के तौर पर किया जाता है.
2. अगर आपको अपनी स्क्रिप्ट के एक या एक से ज़्यादा तरीकों को लाइब्रेरी के उपयोगकर्ताओं को न दिखाना है और न ही उनका इस्तेमाल करने की अनुमति देनी है, तो उस तरीके के नाम के आखिर में अंडरस्कोर लगाएं. उदाहरण के लिए, myPrivateMethod_().
3. लाइब्रेरी के उपयोगकर्ताओं को सिर्फ़ गिनती की जा सकने वाली ग्लोबल प्रॉपर्टी दिखती हैं. इसमें फ़ंक्शन के एलान, var के साथ फ़ंक्शन के बाहर बनाए गए वैरिएबल, और ग्लोबल ऑब्जेक्ट पर साफ़ तौर पर सेट की गई प्रॉपर्टी शामिल हैं. उदाहरण के लिए, enumerable को false पर सेट करने पर, Object.defineProperty() एक ऐसा सिंबल बनाता है जिसका इस्तेमाल अपनी लाइब्रेरी में किया जा सकता है. हालांकि, आपके उपयोगकर्ता इस सिंबल को ऐक्सेस नहीं कर सकते.

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

   /**
    * Raises a number to the given power, and returns the result.
    *
    * @param {number} base the number we're raising to a power
    * @param {number} exp the exponent we're raising the base to
    * @return {number} the result of the exponential calculation
    */
   function power(base, exp) { ... }
   

रिसॉर्स का दायरा तय करना

लाइब्रेरी के साथ काम करते समय, दो तरह के संसाधन होते हैं: शेयर किए गए और शेयर नहीं किए गए. शेयर किए गए संसाधन का मतलब है कि लाइब्रेरी और शामिल की गई स्क्रिप्ट, दोनों के पास संसाधन के एक ही इंस्टेंस का पहले से ऐक्सेस होता है. इस डायग्राम में, उपयोगकर्ता प्रॉपर्टी के उदाहरण का इस्तेमाल करके, शेयर किए गए संसाधन को दिखाया गया है:

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

  function getLibraryProperty(key) {
    const scriptProperties = PropertiesService.getScriptProperties();
    return scriptProperties.getProperty(key);
  }

इस डायग्राम में, स्क्रिप्ट प्रॉपर्टी के उदाहरण का इस्तेमाल करके, शेयर नहीं किए गए संसाधन को दिखाया गया है:

इस टेबल में, शेयर किए गए और शेयर नहीं किए गए संसाधनों की सूची दी गई है:

संसाधन	शेयर किया गया*	शेयर नहीं किया गया**	नोट
लॉक करें			लाइब्रेरी में बनाने पर, एक ही इंस्टेंस सभी को दिखता है. इसमें स्क्रिप्ट भी शामिल हैं.
स्क्रिप्ट गुण			लाइब्रेरी में बनाने पर, एक ही इंस्टेंस सभी को दिखता है. इसमें स्क्रिप्ट भी शामिल हैं.
कैश			लाइब्रेरी में बनाने पर, एक ही इंस्टेंस सभी को दिखता है. इसमें स्क्रिप्ट भी शामिल हैं.
ट्रिगर			लाइब्रेरी में बनाए गए आसान ट्रिगर, शामिल की गई स्क्रिप्ट से ट्रिगर नहीं होते.
ScriptApp
UiApp
उपयोगकर्ता प्रॉपर्टी
लॉगर और प्रोग्राम चलाने की ट्रांसक्रिप्ट
साइटें, शीट, और अन्य कंटेनर			getActive() को कॉल करने पर, स्क्रिप्ट वाला कंटेनर दिखता है.
MailApp और GmailApp
* इसका मतलब है कि लाइब्रेरी में, सुविधा/संसाधन का अपना इंस्टेंस नहीं है. इसके बजाय, वह उस इंस्टेंस का इस्तेमाल कर रही है जिसे उसे ट्रिगर करने वाली स्क्रिप्ट ने बनाया है. ** इसका मतलब है कि लाइब्रेरी में रिसॉर्स/सुविधा का अपना इंस्टेंस होता है और लाइब्रेरी का इस्तेमाल करने वाली सभी स्क्रिप्ट, उसी इंस्टेंस को शेयर करती हैं और उसका ऐक्सेस रखती हैं.

किसी लाइब्रेरी की जांच करना

अपनी लाइब्रेरी की जांच करने के लिए, हेड डिप्लॉयमेंट का इस्तेमाल करें. जिन लोगों के पास स्क्रिप्ट का एडिटर-लेवल ऐक्सेस है वे हेड डिप्लॉयमेंट का इस्तेमाल कर सकते हैं.

आपको अब भी लाइब्रेरी का कम से कम एक वर्शन सेव करना होगा.

लाइब्रेरी को डीबग करना

किसी प्रोजेक्ट में डीबगर का इस्तेमाल करने पर, उसमें शामिल लाइब्रेरी के किसी फ़ंक्शन में स्टैप इन किया जा सकता है. कोड, डिबगर में सिर्फ़ देखने वाले मोड में और सही वर्शन में दिखता है.