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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ज़रूरी शर्तें

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

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

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

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

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

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

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

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

  ध्यान दें: फ़ॉर्म सबमिट ट्रिगर के दो वर्शन होते हैं, एक Sheets के लिए (जहां फ़ॉर्म जवाब इकट्ठा किए जाते हैं) और एक 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.
  }
}

अनुमति वाला ईमेल.html

ट्रिगर/फ़ॉर्म/ऑथराइज़ेशनईमेल.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 Docs B खोले जाने पर, मॉनिटर पर ट्रिगर नहीं बना सकता.
• समय के आधार पर ट्रिगर हर घंटे में एक से ज़्यादा बार नहीं चल सकते.
• जब इंस्टॉल किए जा सकने वाले किसी ट्रिगर की मदद से कोड चलाया जाता है, तो ऐड-ऑन अपने-आप उपयोगकर्ता को ईमेल नहीं भेजते. यह डेवलपर पर निर्भर करता है कि वह गड़बड़ी के मामलों की जांच करे और उन्हें हैंडल करे.
• ऐड-ऑन ट्रिगर इनमें से किसी भी स्थिति में सक्रिय होना बंद हो जाते हैं:
  • अगर उपयोगकर्ता ने ऐड-ऑन को अनइंस्टॉल किया है.
  • अगर किसी दस्तावेज़ में ऐड-ऑन बंद है, तो ट्रिगर फिर से चालू हो जाता है या
  • अगर डेवलपर ऐड-ऑन को अनपब्लिश कर देता है या ऐड-ऑन स्टोर में, टूटी हुई वर्शन सबमिट करता है.
• ऐड-ऑन ट्रिगर फ़ंक्शन तब तक काम करते हैं, जब तक कि वे ऐसे कोड तक नहीं पहुंच जाते जो बिना अनुमति वाली सेवा का इस्तेमाल करता है. यह बात तभी लागू होती है, जब ऐड-ऑन प्रकाशित होता है; सामान्य Apps स्क्रिप्ट प्रोजेक्ट में वही ट्रिगर या स्क्रिप्ट के किसी हिस्से के लिए अनुमति की ज़रूरत होने पर अनपब्लिश ऐड-ऑन डॉन#
• इंस्टॉल किए जा सकने वाले ट्रिगर, Apps Script ट्रिगर कोटा की सीमाओं पर निर्भर होते हैं.