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

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

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

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

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

• एडिटर ऐड-ऑन, दस्तावेज़ खुलने पर अपने onOpen फ़ंक्शन अपने-आप चलाते हैं.

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

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

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

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

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

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

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

अनुमति देने के मोड

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

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

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

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

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

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 में चलती हैं. इसके बारे में यहां दी गई टेबल में बताया गया है.

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

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

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

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

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

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

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