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

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

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

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

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

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

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

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

पाबंदियां

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

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

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

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

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

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

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

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

  ध्यान दें: फ़ॉर्म सबमिट करने वाले ट्रिगर के दो वर्शन होते हैं. एक Sheets के लिए होता है, जहां फ़ॉर्म के जवाब इकट्ठा किए जाते हैं. दूसरा Google Forms के लिए होता है. Sheets के फ़ॉर्म सबमिट करने वाले ट्रिगर फ़ंक्शन को पास किया गया इवेंट ऑब्जेक्ट ज़्यादा आसान होता है. साथ ही, यह जवाब की वैल्यू को आसान ऐरे में दिखाता है. फ़ॉर्म सबमिट करने वाले ट्रिगर फ़ंक्शन को पास किया गया इवेंट ऑब्जेक्ट ज़्यादा जानकारी देता है. यह जानकारी, 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 ट्रिगर की कोटा सीमाएं के दायरे में आते हैं.