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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

पाबंदियां

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

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

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

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

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

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

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

• फ़ॉर्म सबमिट होने पर ट्रिगर, Google फ़ॉर्म का जवाब सबमिट होने पर ट्रिगर होते हैं.

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

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

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

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

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

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

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

Code.gs

triggers/form/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.
  }
}

authorizationemail.html

triggers/form/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>

पाबंदियां

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

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

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