एडिटर ऐड-ऑन का अधिकार

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Apps Script, अनुमति देने वाले मोड को Apps Script इवेंट पैरामीटर, e की authMode प्रॉपर्टी के तौर पर पास करती है. 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() को सुनना शुरू करता है. अगर कोई उपयोगकर्ता एक्सटेंशन मेन्यू आइटम पर क्लिक करता है, तो वह चलता है.

एडिटर ऐड-ऑन इंस्टॉल है

जब स्टोर से कोई एडिटर ऐड-ऑन इंस्टॉल किया जाता है, तो उसका 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();
}

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

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

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

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

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

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

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

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

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

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

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

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