एडिटर ऐड-ऑन को अनुमति देना

Apps Script पर आधारित कई ऐप्लिकेशन के लिए अनुमति पाना आसान होता है. ऐसा इसलिए, क्योंकि जब कोई व्यक्ति स्क्रिप्ट प्रोजेक्ट का इस्तेमाल करने की कोशिश करता है, तब वह उन सभी अनुमतियों का अनुरोध करता है जो उसके पास नहीं हैं.

Editor ऐड-ऑन के लिए अनुमति देने का मॉडल, कई वजहों से ज़्यादा जटिल है:

• जब कोई उपयोगकर्ता कोई फ़ाइल बनाता है, तो उसके इंस्टॉल किए गए सभी ऐड-ऑन, एक्सटेंशन मेन्यू में दिखते हैं. भले ही, उपयोगकर्ता ने उन ऐड-ऑन को अब तक अनुमति न दी हो.

• ये ऐड-ऑन, Google Drive में मौजूद उन फ़ाइलों पर काम करते हैं जिन्हें सहयोगियों के साथ शेयर किया जा सकता है. जिन सहयोगियों ने Editor ऐड-ऑन इंस्टॉल नहीं किया है उन्हें यह उन दस्तावेज़ों में दिखता है जिनमें फ़ाइल बनाने वाले व्यक्ति ने इसका इस्तेमाल किया है.

• Editor add-ons, दस्तावेज़ खुलने पर अपने onOpen() फ़ंक्शन अपने-आप चलाते हैं.

उपयोगकर्ता के डेटा को सुरक्षित रखने के लिए, अनुमति देने के मोड लागू किए जाते हैं. इससे कुछ सेवाएं onOpen() के लिए उपलब्ध नहीं होती हैं. इस गाइड से आपको यह समझने में मदद मिल सकती है कि आपका कोड क्या कर सकता है और कब कर सकता है.

अनुमति देने का मॉडल

एडिटर ऐड-ऑन का अनुमति मोड, उसकी स्थिति पर निर्भर करता है. यह स्थिति इस बात पर निर्भर करती है कि ऐड-ऑन का इस्तेमाल कौन कर रहा है: ऐड-ऑन इंस्टॉल करने वाला उपयोगकर्ता या सहयोगी.

एडिटर ऐड-ऑन की स्थितियां

एक्सटेंशन मेन्यू में मौजूद एडिटर ऐड-ऑन इंस्टॉल किए गए हों, चालू किए गए हों या दोनों.

• किसी ऐड-ऑन को किसी उपयोगकर्ता के लिए तब इंस्टॉल किया जाता है, जब वह या उसका एडमिन उसे Google Workspace Marketplace से हासिल कर लेता है और उसे अपने Google डेटा को ऐक्सेस करने की अनुमति दे देता है.
• किसी दस्तावेज़, फ़ॉर्म, प्रज़ेंटेशन या स्प्रेडशीट में ऐड-ऑन तब चालू होता है, जब कोई व्यक्ति उसका इस्तेमाल करता है.
• जब लोग किसी फ़ाइल पर मिलकर काम करते हैं और उनमें से कोई एक व्यक्ति ऐड-ऑन का इस्तेमाल करता है, तो वह ऐड-ऑन सिर्फ़ उस व्यक्ति के लिए इंस्टॉल होता है. साथ ही, उस फ़ाइल के लिए चालू होता है.

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

	इंस्टॉल किया गया	चालू
इस पर लागू होता है	उपयोगकर्ता	दस्तावेज़, फ़ॉर्म, प्रज़ेंटेशन या स्प्रेडशीट
इसके कारण	स्टोर से ऐड-ऑन पाना	किसी दस्तावेज़, फ़ॉर्म, प्रज़ेंटेशन या स्प्रेडशीट का इस्तेमाल करते समय, स्टोर से कोई ऐड-ऑन पाना या किसी दस्तावेज़, फ़ॉर्म, प्रज़ेंटेशन या स्प्रेडशीट में पहले से इंस्टॉल किए गए ऐड-ऑन का इस्तेमाल करना
मेन्यू इन्हें दिखेगा	सिर्फ़ उस उपयोगकर्ता को, उसके खोले या बनाए गए सभी दस्तावेज़ों, फ़ॉर्म, प्रज़ेंटेशन या स्प्रेडशीट में	उस दस्तावेज़, फ़ॉर्म, प्रज़ेंटेशन या स्प्रेडशीट पर काम करने वाले सभी लोग
onOpen() के लिए पुष्टि करने का मोड	AuthMode.NONE (जब तक कि इसे चालू न किया गया हो. अगर ऐसा है, तो AuthMode.LIMITED)	AuthMode.LIMITED

पुष्टि करने के मोड

जब कोई उपयोगकर्ता किसी दस्तावेज़, फ़ॉर्म, प्रज़ेंटेशन या स्प्रेडशीट को खोलता है, तो एडिटर ऐड-ऑन का onOpen() फ़ंक्शन अपने-आप काम करता है. उपयोगकर्ताओं के डेटा को सुरक्षित रखने के लिए, Apps Script यह तय करता है कि onOpen() फ़ंक्शन क्या-क्या कर सकता है. एडिटर ऐड-ऑन की स्थिति से यह तय होता है कि onOpen() फ़ंक्शन किस अनुमति मोड में काम करेगा.

अगर फ़ाइल, फ़ॉर्म, प्रज़ेंटेशन या स्प्रेडशीट में Editor ऐड-ऑन चालू है, तो onOpen() AuthMode.LIMITED में चलता है. अगर ऐड-ऑन चालू नहीं है और सिर्फ़ इंस्टॉल किया गया है, तो onOpen(), AuthMode.NONE में चलता है.

AuthMode.NONE में, ऐड-ऑन कुछ सेवाओं को तब तक नहीं चला सकता, जब तक उपयोगकर्ता ऐड-ऑन से इंटरैक्ट नहीं करता. इसके लिए, उपयोगकर्ता को ऐड-ऑन पर क्लिक करना होगा या कस्टम फ़ंक्शन चलाने होंगे. अगर आपका ऐड-ऑन, onOpen(), onInstall() या ग्लोबल स्कोप में इन सेवाओं का इस्तेमाल करने की कोशिश करता है, तो अनुमतियां नहीं मिलेंगी और मेन्यू भरने जैसे अन्य कॉल बंद हो जाएंगे. सिर्फ़ सहायता का विकल्प उपलब्ध है.

प्रतिबंधित सेवा से जुड़े कॉल करने के लिए, आपको AuthMode.FULL ऑथराइज़ेशन मोड का इस्तेमाल करना होगा. उपयोगकर्ता के इंटरैक्शन वाले फ़ंक्शन, जैसे कि मेन्यू के किसी विकल्प पर क्लिक करना, सिर्फ़ इस मोड में काम करते हैं. AuthMode.FULL मोड में कोड चलाने के बाद, ऐड-ऑन उन सभी स्कोप का इस्तेमाल कर सकता है जिनके लिए उपयोगकर्ता ने अनुमति दी है.

ध्यान दें: सिर्फ़ पब्लिश किए गए Editor ऐड-ऑन, AuthMode.NONE में हो सकते हैं. पब्लिश नहीं किए गए Editor ऐड-ऑन, AuthMode.LIMITED में onOpen() के तौर पर काम करते हैं. हालांकि, एडिटर ऐड-ऑन को टेस्ट किया जा सकता है. इससे यह पुष्टि की जा सकती है कि डेवलपमेंट के दौरान ऐड-ऑन, अनुमति देने के दोनों मोड में सही तरीके से काम कर रहा है.

Apps Script, अनुमति देने के मोड को Apps Script के इवेंट पैरामीटर की authMode प्रॉपर्टी के तौर पर पास करता है, e; e.authMode की वैल्यू, Apps Script के ScriptApp.AuthMode enum में मौजूद किसी कॉन्स्टेंट से मेल खाती है.

अनुमति के मोड, Apps Script को लागू करने के सभी तरीकों पर लागू होते हैं. जैसे, स्क्रिप्ट एडिटर से, मेन्यू आइटम से या Apps Script google.script.run कॉल से स्क्रिप्ट चलाना. हालांकि, e.authMode प्रॉपर्टी की जांच सिर्फ़ तब की जा सकती है, जब स्क्रिप्ट ट्रिगर के तौर पर काम करती हो. जैसे, onOpen(), onEdit() या onInstall(). Google Sheets में कस्टम फ़ंक्शन, अनुमति देने के लिए अपने मोड AuthMode.CUSTOM_FUNCTION का इस्तेमाल करते हैं. यह LIMITED के जैसा ही होता है, लेकिन इसमें कुछ अलग पाबंदियां होती हैं. अन्य सभी मामलों में, स्क्रिप्ट AuthMode.FULL में चलती हैं. इसके बारे में यहां दी गई टेबल में बताया गया है.

	NONE	LIMITED	CUSTOM_FUNCTION	FULL
इस वजह से होता है	onOpen() (अगर उपयोगकर्ता ने कोई ऐड-ऑन इंस्टॉल किया है, लेकिन उसे दस्तावेज़, फ़ॉर्म, प्रज़ेंटेशन या स्प्रेडशीट में चालू नहीं किया है)	onOpen() (अन्य सभी समय) onEdit() (सिर्फ़ Sheets में)	कस्टम फ़ंक्शन	अन्य सभी समय पर, जैसे कि: इंस्टॉल किए जा सकने वाले ट्रिगर onInstall() google.script.run
उपयोगकर्ता के डेटा का ऐक्सेस	सिर्फ़ स्थान-भाषा	सिर्फ़ स्थान-भाषा	सिर्फ़ स्थान-भाषा	हां
दस्तावेज़, फ़ॉर्म, प्रज़ेंटेशन या स्प्रेडशीट का ऐक्सेस	नहीं	हां	हां — रीड-ओनली	हां
यूज़र इंटरफ़ेस का ऐक्सेस	मेन्यू आइटम जोड़ना	मेन्यू आइटम जोड़ना	नहीं	हां
Properties का ऐक्सेस	नहीं	हां	हां	हां
Jdbc, UrlFetch का ऐक्सेस	नहीं	नहीं	हां	हां
अन्य सेवाएं	Logger Utilities	ऐसी सेवाएं जो उपयोगकर्ता के डेटा को ऐक्सेस नहीं करती हैं	ऐसी सेवाएं जो उपयोगकर्ता के डेटा को ऐक्सेस नहीं करती हैं	सभी सेवाएं

एडिटर ऐड-ऑन के लिए अनुमति देने का लाइफ़साइकल

जब मौजूदा उपयोगकर्ता के लिए कोई ऐड-ऑन इंस्टॉल किया जाता है या मौजूदा फ़ाइल में चालू किया जाता है, तो उस फ़ाइल को खोलने पर, दस्तावेज़, फ़ॉर्म, प्रज़ेंटेशन या स्प्रेडशीट के लिए ऐड-ऑन लोड हो जाता है. ऐड-ऑन, एक्सटेंशन मेन्यू में दिखता है. साथ ही, सिंपल ट्रिगर onInstall(), onOpen(), और onEdit() के लिए काम करना शुरू कर देता है. अगर कोई उपयोगकर्ता एक्सटेंशन मेन्यू आइटम पर क्लिक करता है, तो यह चलता है.

एडिटर ऐड-ऑन इंस्टॉल किया गया हो

जब स्टोर से कोई Editor ऐड-ऑन इंस्टॉल किया जाता है, तो उसका onInstall() फ़ंक्शन AuthMode.FULL में काम करता है. इस अनुमति मोड में, ऐड-ऑन एक जटिल सेटअप रूटीन चला सकता है. आपको मेन्यू आइटम बनाने के लिए, onInstall() का इस्तेमाल करना चाहिए. ऐसा इसलिए, क्योंकि दस्तावेज़, फ़ॉर्म, प्रज़ेंटेशन या स्प्रेडशीट पहले से ही खुली है और onOpen() फ़ंक्शन नहीं चला है. यहां दिए गए उदाहरण में, onOpen() फ़ंक्शन से onOpen() फ़ंक्शन को कॉल करने का तरीका बताया गया है:onInstall()

function onInstall(e) {
  onOpen(e);
  // Perform additional setup as needed.
}

एडिटर ऐड-ऑन खुलता है

जब कोई दस्तावेज़, फ़ॉर्म, प्रज़ेंटेशन या स्प्रेडशीट खुलती है, तो यह हर उस एडिटर ऐड-ऑन को लोड करता है जिसे मौजूदा उपयोगकर्ता ने इंस्टॉल किया है या जिसे किसी सहयोगी ने फ़ाइल में चालू किया है. साथ ही, यह उन सभी के onOpen() फ़ंक्शन को कॉल करता है. onOpen() ऐड-ऑन के लिए ऑथराइज़ेशन मोड, इस बात पर निर्भर करता है कि ऐड-ऑन इंस्टॉल या चालू किया गया है या नहीं.

अगर ऐड-ऑन सिर्फ़ बुनियादी मेन्यू बनाता है, तो मोड से कोई फ़र्क़ नहीं पड़ता. यहां दिए गए सैंपल में, onOpen() फ़ंक्शन का बुनियादी इस्तेमाल दिखाया गया है:

function onOpen(e) {
  SpreadsheetApp.getUi().createAddonMenu() // Or DocumentApp.
      .addItem('Insert chart', 'insertChart')
      .addItem('Update charts', 'updateCharts')
      .addToUi();
}

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

यहां दिए गए सैंपल में, बेहतर onOpen() फ़ंक्शन दिखाया गया है. यह फ़ंक्शन, अनुमति वाले मोड के आधार पर अपनी कार्रवाई बदलता है:

function onOpen(e) {
  var menu = SpreadsheetApp.getUi().createAddonMenu(); // Or DocumentApp.
  if (e && e.authMode == ScriptApp.AuthMode.NONE) {
    // Add a normal menu item (works in all authorization modes).
    menu.addItem('Start workflow', 'startWorkflow');
  } else {
    // Add a menu item based on properties (doesn't work in AuthMode.NONE).
    var properties = PropertiesService.getDocumentProperties();
    var workflowStarted = properties.getProperty('workflowStarted');
    if (workflowStarted) {
      menu.addItem('Check workflow status', 'checkWorkflow');
    } else {
      menu.addItem('Start workflow', 'startWorkflow');
    }
  }
  menu.addToUi();
}

चेतावनी: onOpen() फ़ंक्शन के चलने पर, पूरी स्क्रिप्ट लोड हो जाती है. साथ ही, सभी ग्लोबल स्टेटमेंट, onOpen() के लिए इस्तेमाल किए गए ऑथराइज़ेशन मोड के तहत चलते हैं. अगर अनुमति देने का मोड, ग्लोबल स्टेटमेंट को अनुमति नहीं देता है, तो ग्लोबल स्टेटमेंट और onOpen(), दोनों नहीं चलेंगे. अगर पब्लिश किया गया ऐड-ऑन, अपने मेन्यू आइटम नहीं जोड़ पाता है, तो ब्राउज़र के JavaScript कंसोल की समीक्षा करें. इससे आपको पता चलेगा कि कोई गड़बड़ी हुई है या नहीं. इसके बाद, अपनी स्क्रिप्ट की जांच करें. देखें कि क्या onOpen() फ़ंक्शन या ग्लोबल वैरिएबल, ऐसी सेवाओं को कॉल कर रहे हैं जिनकी अनुमति AuthMode.NONE में नहीं है.

ध्यान दें कि AuthMode.LIMITED में काम करते समय, ऐड-ऑन साइडबार या डायलॉग बॉक्स नहीं खोल सकते. साइडबार और डायलॉग खोलने के लिए, मेन्यू आइटम का इस्तेमाल किया जा सकता है. ऐसा इसलिए, क्योंकि ये AuthMode.FULL में चलते हैं.

जब कोई उपयोगकर्ता Editor ऐड-ऑन चलाता है

जब कोई उपयोगकर्ता एक्सटेंशन मेन्यू आइटम पर क्लिक करता है, तो Apps Script पहले यह जांच करता है कि उपयोगकर्ता ने ऐड-ऑन इंस्टॉल किया है या नहीं. अगर उसने ऐड-ऑन इंस्टॉल नहीं किया है, तो Apps Script उसे ऐड-ऑन इंस्टॉल करने के लिए कहता है. अगर उपयोगकर्ता ने ऐड-ऑन को अनुमति दी है, तो स्क्रिप्ट उस फ़ंक्शन को चलाती है जो AuthMode.FULL में मेन्यू आइटम से मेल खाता है. अगर ऐड-ऑन पहले से चालू नहीं है, तो उसे दस्तावेज़, फ़ॉर्म, प्रज़ेंटेशन या स्प्रेडशीट में चालू कर दिया जाता है.

ऐड-ऑन मेन्यू रेंडर न होने की समस्या हल करना

अगर आपका कोड, ऑथराइज़ेशन मोड को सही तरीके से मैनेज नहीं करता है, तो हो सकता है कि आपका ऐड-ऑन मेन्यू रेंडर न हो. उदाहरण के लिए:

• ऐड-ऑन, Apps Script की ऐसी सेवा को चलाने की कोशिश करता है जिसे मौजूदा अनुमति मोड के साथ इस्तेमाल नहीं किया जा सकता.

• ऐड-ऑन, उपयोगकर्ता के साथ इंटरैक्ट करने से पहले ही सेवा कॉल को चलाने की कोशिश करता है.

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

1. अपने ऐड-ऑन के लिए Apps Script प्रोजेक्ट खोलें और onOpen() फ़ंक्शन ढूंढें.
2. onOpen() फ़ंक्शन में, Apps Script सेवाओं या उनसे जुड़े ऑब्जेक्ट के बारे में खोजें. जैसे, PropertiesService, SpreadsheetApp या GmailApp.
3. अगर किसी सेवा का इस्तेमाल यूज़र इंटरफ़ेस (यूआई) एलिमेंट बनाने के अलावा किसी और काम के लिए किया जाता है, तो उसे हटा दें या टिप्पणी ब्लॉक में रैप कर दें. सिर्फ़ इन तरीकों को चालू रखें: .getUi(), .createMenu(), .addItem(), और .addToUi(). साथ ही, फ़ंक्शन के बाहर मौजूद किसी भी सेवा को ढूंढें और हटाएं.
4. उन फ़ंक्शन का पता लगाएं जिनमें पिछले चरण में टिप्पणी की गई या हटाई गई कोड की लाइनें शामिल हो सकती हैं. खास तौर पर, उन फ़ंक्शन का पता लगाएं जो इन लाइनों से मिली जानकारी का इस्तेमाल करते हैं. इसके बाद, सेवा कॉल को उन फ़ंक्शन में ले जाएं जिनकी उन्हें ज़रूरत है. पिछले चरणों में किए गए बदलावों को शामिल करने के लिए, अपने कोडबेस को फिर से व्यवस्थित करें या उसे फिर से लिखें.

5. कोड सेव करें और टेस्ट डिप्लॉयमेंट बनाएं.

   टेस्ट डिप्लॉयमेंट बनाते समय, पक्का करें कि कॉन्फ़िगरेशन फ़ील्ड में, मौजूदा उपयोगकर्ता के लिए इंस्टॉल किया गया लिखा हो. साथ ही, कॉन्फ़िगरेशन बॉक्स के नीचे मौजूद टेक्स्ट में, AuthMode.None में टेस्ट करें लिखा हो

6. टेस्ट डिप्लॉयमेंट लॉन्च करें और एक्सटेंशन मेन्यू खोलें.

7. अगर मेन्यू के सभी आइटम दिख रहे हैं, तो समस्या ठीक हो गई है. अगर आपको सिर्फ़ सहायता मेन्यू दिखता है, तो पहले चरण पर वापस जाएं. ऐसा हो सकता है कि आपने सेवा से जुड़ा कोई कॉल मिस कर दिया हो.

मिलते-जुलते विषय

• वेब ऐप्लिकेशन
• ऐड-ऑन के टाइप
• एडिटर ऐड-ऑन की जांच करना