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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

पाबंदियां

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

/**
 * 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.
  }
}

<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 ट्रिगर की कोटा सीमाएं लागू होती हैं.