एडिटर ऐड-ऑन प्राधिकरण

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

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

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

एडिटर ऐड-ऑन की दो प्रॉपर्टी, खास तौर पर इन्हें शेयर करना और इस्तेमाल करना आसान बनाती हैं:

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

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

इंस्टॉल किया गया बनाम चालू किया गया

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

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

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

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

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

खास तौर पर, इंस्टॉल किया गया और चालू किया गया स्टेटस यह तय करता है कि onOpen(e) फ़ंक्शन किस ऑथराइज़ेशन मोड में चलता है. Apps Script, अनुमति मोड को authModeऐप्लिकेशन प्रॉपर्टी के इवेंट पैरामीटर, e के तौर पर पास करता है; e.authMode का मान, Apps Script ScriptApp.AuthMode enum में मौजूद कॉन्सटेंट के मुताबिक होता है.

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

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

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

पूरी लाइफ़साइकल

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

सॉफ़्टवेयर इंस्टॉल हो रहा है

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

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

खोलना

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

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

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

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

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();
}

दौड़

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