एडिटर ऐड-ऑन के लिए ट्रिगर

Apps Script ट्रिगर की मदद से, तय किया गया स्क्रिप्ट फ़ंक्शन (ट्रिगर फ़ंक्शन) ट्रिगर होता है. इससे, किसी खास इवेंट के होने पर उसे एक्ज़ीक्यूट किया जा सकता है. सिर्फ़ कुछ इवेंट से ट्रिगर चालू हो सकते हैं. Google Workspace के हर ऐप्लिकेशन में, अलग-अलग तरह के इवेंट काम करते हैं.

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

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

यह पेज एडिटर ऐड-ऑन प्रोजेक्ट में ट्रिगर का इस्तेमाल करने के बारे में दिशा-निर्देश देता है.

एडिटर ऐड-ऑन के ट्रिगर टाइप

Apps Script प्रोजेक्ट में उपलब्ध ज़्यादातर जेनरिक ट्रिगर का इस्तेमाल, एडिटर ऐड-ऑन में किया जा सकता है. इनमें, आसान ट्रिगर और इंस्टॉल करने लायक ज़्यादातर ट्रिगर शामिल हैं. उपलब्ध ट्रिगर टाइप का सटीक सेट इस बात पर निर्भर करता है कि ऐप्लिकेशन को बढ़ाया जा रहा है या नहीं.

ध्यान दें: Google Workspace ऐड-ऑन, फ़िलहाल सामान्य और इंस्टॉल किए जा सकने वाले ट्रिगर का इस्तेमाल नहीं कर सकता. यह एडिटर एडिटर के ऐड-ऑन से अलग है. इसके बजाय, वे खास तौर पर Google Workspace ऐड-ऑन के लिए डिज़ाइन किए गए ट्रिगर का इस्तेमाल करते हैं. ज़्यादा जानकारी के लिए, Google Workspace ऐड-ऑन के ट्रिगर देखें.

नीचे दी गई टेबल में, आसान और इंस्टॉल किए जा सकने वाले ऐसे ट्रिगर दिए गए हैं जिन्हें एडिटर ऐड-ऑन इस्तेमाल कर सकते हैं. साथ ही, उनसे जुड़े इवेंट ऑब्जेक्ट के लिंक भी देता है:

इवेंट	इवेंट ऑब्जेक्ट	आसान ट्रिगर	इंस्टॉल किए जा सकने वाले ट्रिगर
खोलें संपादक फ़ाइल खुल गई है.	Docs onOpen इवेंट ऑब्जेक्ट Openइवेंट ऑब्जेक्ट वाले फ़ॉर्म Sheets onOpen इवेंट ऑब्जेक्ट Slides onOpen इवेंट ऑब्जेक्ट	Docs Forms* Sheets Slides function onOpen(e)	दस्तावेज़ फ़ॉर्म* शीट
इंस्टॉल करें ऐड-ऑन इंस्टॉल हो गया है.	onInstall इवेंट ऑब्जेक्ट	दस्तावेज़ फ़ॉर्म Sheets स्लाइड function onInstall(e)
बदलाव करें स्प्रेडशीट सेल का कॉन्टेंट बदल दिया गया है.	Sheets में ऑब्जेक्ट में बदलाव करने की सुविधा	शीट function onEdit(e)	शीट
बदलें शीट की सामग्री में बदलाव किया गया है या उसे फ़ॉर्मैट किया गया है.	Sheets onChange इवेंट ऑब्जेक्ट		शीट
फ़ॉर्म सबमिट Google फ़ॉर्म सबमिट किया गया है.	फ़ॉर्म फ़ॉर्म-सबमिट इवेंट ऑब्जेक्ट Sheets फ़ॉर्म सबमिट इवेंट ऑब्जेक्ट		फ़ॉर्म Sheets
समय के हिसाब से (घड़ी) ट्रिगर किसी खास समय या अंतराल पर सक्रिय होता है.	समय के मुताबिक इवेंट ऑब्जेक्ट		Docs Forms Sheets Slides

* Google फ़ॉर्म के लिए खुला इवेंट तब नहीं होता, जब कोई उपयोगकर्ता जवाब देने के लिए फ़ॉर्म खोलता है, बल्कि तब होता है, जब कोई संपादक फ़ॉर्म में बदलाव करने के लिए उसे खोलता है.

ऐड-ऑन में सरल ट्रिगर

आसान ट्रिगर, रिज़र्व किए गए फ़ंक्शन के नाम का इस्तेमाल करते हैं. साथ ही, ऐसी सेवाओं का इस्तेमाल नहीं कर सकते जिनके लिए अनुमति लेने की ज़रूरत होती है और जो इस्तेमाल के लिए अपने-आप चालू हो जाती हैं. कुछ मामलों में, सामान्य ट्रिगर इवेंट को इंस्टॉल किए जा सकने वाले ट्रिगर से मैनेज किया जा सकता है.

इनमें से किसी एक रिज़र्व किए गए नाम वाले फ़ंक्शन को लागू करके, आप किसी ऐड-ऑन में एक आसान ट्रिगर जोड़ सकते हैं:

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

पाबंदियां

ऐड-ऑन में मौजूद सामान्य ट्रिगर पर भी ऐसी पाबंदियां लागू होती हैं जो अन्य तरह के ऐप्लिकेशन स्क्रिप्ट प्रोजेक्ट में, आसान ट्रिगर को लागू करती हैं. ऐड-ऑन डिज़ाइन करते समय, इन पाबंदियों का ध्यान रखें:

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

ऐड-ऑन में इंस्टॉल किए जा सकने वाले ट्रिगर

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

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

ऐड-ऑन, इंस्टॉल किए जा सकने वाले इन ट्रिगर का इस्तेमाल कर सकता है:

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

• फ़ॉर्म-सबमिट में इंस्टॉल किए जा सकने वाले ट्रिगर तब काम करते हैं, जब 'Google फ़ॉर्म' का जवाब सबमिट किया जाता है.

  ध्यान दें: फ़ॉर्म सबमिट ट्रिगर के दो वर्शन होते हैं, एक शीट के लिए (जहां फ़ॉर्म के जवाबों को इकट्ठा किया जाता है) और एक Google Forms के लिए. Sheets फ़ॉर्म सबमिट ट्रिगर फ़ंक्शन को दिया गया इवेंट ऑब्जेक्ट आसान है और रिस्पॉन्स वैल्यू को आसान श्रेणियों में दिखाता है. फ़ॉर्म फ़ॉर्म-सबमिट ट्रिगर फ़ंक्शन में पास किया गया इवेंट ऑब्जेक्ट FormResponse ऑब्जेक्ट में ज़्यादा जानकारी देता है.

• टाइम-ड्रिवन ट्रिगर (जिन्हें घड़ी ट्रिगर भी कहा जाता है) किसी खास समय पर या बार-बार समय-समय पर सक्रिय होते हैं.

इंस्टॉल करने लायक ट्रिगर को अनुमति देना

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

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

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

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

Code.gs

ट्रिगर/फ़ॉर्म/Code.gs

GitHub पर देखें

/**
 * Responds to a form when submitted.
 * @param {event} e The Form submit event.
 */
function respondToFormSubmit(e) {
  const addonTitle = 'My Add-on Title';
  const props = PropertiesService.getDocumentProperties();
  const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);

  // Check if the actions of the trigger requires authorization that has not
  // been granted yet; if so, warn the user via email. This check is required
  // when using triggers with add-ons to maintain functional triggers.
  if (authInfo.getAuthorizationStatus() ===
    ScriptApp.AuthorizationStatus.REQUIRED) {
    // Re-authorization is required. In this case, the user needs to be alerted
    // that they need to re-authorize; the normal trigger action is not
    // conducted, since it requires authorization first. Send at most one
    // "Authorization Required" email per day to avoid spamming users.
    const lastAuthEmailDate = props.getProperty('lastAuthEmailDate');
    const today = new Date().toDateString();
    if (lastAuthEmailDate !== today) {
      if (MailApp.getRemainingDailyQuota() > 0) {
        const html = HtmlService.createTemplateFromFile('AuthorizationEmail');
        html.url = authInfo.getAuthorizationUrl();
        html.addonTitle = addonTitle;
        const message = html.evaluate();
        MailApp.sendEmail(Session.getEffectiveUser().getEmail(),
            'Authorization Required',
            message.getContent(), {
              name: addonTitle,
              htmlBody: message.getContent()
            }
        );
      }
      props.setProperty('lastAuthEmailDate', today);
    }
  } else {
    // Authorization has been granted, so continue to respond to the trigger.
    // Main trigger logic here.
  }
}

Authorityemail.html

ट्रिगर/फ़ॉर्म/AuthorizationEmail.html

GitHub पर देखें

<p>The Google Sheets add-on <i><?= addonTitle ?></i> is set to run automatically
    whenever a form is submitted. The add-on was recently updated and it needs you
    to re-authorize it to run on your behalf.</p>

<p>The add-on's automatic functions are temporarily disabled until you
    re-authorize it. To do so, open Google Sheets and run the add-on from the
    Add-ons menu. Alternatively, you can click this link to authorize it:</p>

<p><a href="<?= url ?>">Re-authorize the add-on.</a></p>

<p>This notification email will be sent to you at most once per day until the
    add-on is re-authorized.</p>

पाबंदियां

ऐड-ऑन में इंस्टॉल किए जा सकने वाले ट्रिगर उन पाबंदियों पर निर्भर होते हैं, जो दूसरे तरह के ऐप्लिकेशन स्क्रिप्ट प्रोजेक्ट में इंस्टॉल करने लायक ट्रिगर को नियंत्रित करते हैं.

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

• हर ऐड-ऑन के पास हर दस्तावेज़ और हर उपयोगकर्ता के हिसाब से हर तरह का सिर्फ़ एक ट्रिगर हो सकता है. उदाहरण के लिए, किसी स्प्रेडशीट में, दिए गए उपयोगकर्ता के पास सिर्फ़ एक बदलाव ट्रिगर हो सकता है. हालांकि, उपयोगकर्ता के पास फ़ॉर्म सबमिट करने या उसी स्प्रेडशीट में समय के हिसाब से ट्रिगर करने वाला ट्रिगर भी हो सकता है. जिस उपयोगकर्ता के पास एक ही स्प्रेडशीट का ऐक्सेस है तो उसके पास ट्रिगर का अपना अलग सेट हो सकता है.
• ऐड-ऑन सिर्फ़ उस फ़ाइल के लिए ट्रिगर बना सकते हैं जिसमें ऐड-ऑन का इस्तेमाल किया जाता है. इसका मतलब है कि Google दस्तावेज़ A में इस्तेमाल किए जाने वाले ऐड-ऑन से, Google दस्तावेज़ B खोले जाने पर ट्रिगर ट्रिगर नहीं किया जा सकता.
• समय के आधार पर ट्रिगर हर घंटे में एक से ज़्यादा बार नहीं चल सकते.
• जब इंस्टॉल किए जा सकने वाले किसी ट्रिगर की मदद से कोड चलाया जाता है, तो ऐड-ऑन, उपयोगकर्ता को अपने-आप एक ईमेल नहीं भेजते. यह डेवलपर पर निर्भर करता है कि वह गड़बड़ी के मामलों को अच्छे से जांचे और उन्हें हैंडल करे.
• ऐड-ऑन ट्रिगर इनमें से किसी भी स्थिति में सक्रिय होना बंद कर देते हैं:
  • अगर उपयोगकर्ता ऐड-ऑन को अनइंस्टॉल करता है,
  • अगर किसी दस्तावेज़ में ऐड-ऑन बंद है, तो ट्रिगर फिर से काम करने लगता है या
  • अगर डेवलपर ऐड-ऑन को अनपब्लिश करता है या किसी ऐड-ऑन स्टोर में कोई अमान्य वर्शन सबमिट करता है, तो यह काम नहीं करता.
• ऐड-ऑन ट्रिगर फ़ंक्शन तब तक काम करते हैं, जब तक कि वे ऐसे कोड तक नहीं पहुंच जाते जो बिना मंज़ूरी वाली सेवा का इस्तेमाल नहीं करता है. यह सिर्फ़ तब लागू होता है, जब ऐड-ऑन प्रकाशित होता है. जब स्क्रिप्ट के किसी भी हिस्से को अनुमति की ज़रूरत पड़ती है, तो सामान्य Apps Script प्रोजेक्ट या पब्लिश नहीं किए गए ऐड-ऑन पर वही ट्रिगर बिल्कुल काम नहीं करता.
• इंस्टॉल किए जा सकने वाले ट्रिगर, Apps Script ट्रिगर कोटा की सीमा पर निर्भर करते हैं.