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

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

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

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

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

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

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

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

इवेंट इवेंट ऑब्जेक्ट आसान ट्रिगर इंस्टॉल किए जा सकने वाले ट्रिगर
खोलें
एक एडिटर फ़ाइल खुल जाती है.
Docs onOpen इवेंट ऑब्जेक्ट
Forms onOpen इवेंट ऑब्जेक्ट
खुले इवेंट ऑब्जेक्ट पर Sheets
Slides onOpen इवेंट ऑब्जेक्ट
Docs
Forms*
Sheets
Slides

function onOpen(e)

दस्तावेज़
फ़ॉर्म
शीट
इंस्टॉल करें
ऐड-ऑन इंस्टॉल हो गया है.
onइंस्टॉल इवेंट ऑब्जेक्ट Docs
Forms
Sheets
Slides

function onInstall(e)

बदलाव करें
स्प्रेडशीट सेल का कॉन्टेंट बदला गया है.
इवेंट ऑब्जेक्ट में बदलाव करने पर शीट शीट

function onEdit(e)

शीट
बदलें
शीट के कॉन्टेंट में बदलाव किया गया है या उसे फ़ॉर्मैट किया गया है.
'Sheets में बदलें' इवेंट ऑब्जेक्ट शीट
फ़ॉर्म सबमिट करना
Google फ़ॉर्म सबमिट कर दिया गया है.
'फ़ॉर्म' फ़ॉर्म-सबमिट इवेंट ऑब्जेक्ट
'Sheets' फ़ॉर्म-सबमिट इवेंट ऑब्जेक्ट
फ़ॉर्म
शीट
समय के हिसाब से (घड़ी)
ट्रिगर, तय किए गए समय या इंटरवल पर चालू होता है.
समय के हिसाब से इवेंट ऑब्जेक्ट Docs
Forms
Sheets
Slides

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

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

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

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

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

पाबंदियां

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

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

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

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

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

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

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

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

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

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

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

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

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

Code.gs

ट्रिगर/form/Code.gs
/**
 * 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.
  }
}

ऑथराइज़ेशनemail.html

ट्रिगर/form/ऑथराइज़ेशनईमेल.html
<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 ट्रिगर के हिसाब से कोटा की सीमाओं पर निर्भर करते हैं.