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

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

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

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

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

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

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

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

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

Editor ऐड-ऑन की स्थितियां

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

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

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

अनुमति देने के तरीके

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

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

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

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

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

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

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

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

Editor ऐड-ऑन इंस्टॉल हो गया हो

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

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

Editor ऐड-ऑन खुल जाता है

जब कोई दस्तावेज़, फ़ॉर्म, प्रज़ेंटेशन या स्प्रेडशीट खोली जाती है, तो यह Editor का हर वह ऐड-ऑन लोड करता है जिसे मौजूदा उपयोगकर्ता ने इंस्टॉल किया है या जिसे फ़ाइल में मिलकर काम करने वाले किसी व्यक्ति ने चालू किया है. साथ ही, यह ऐड-ऑन के हर 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();
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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