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

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

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

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

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

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

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

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

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

function onOpen(e)

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

function onInstall(e)
बदलाव करें
स्प्रेडशीट सेल के कॉन्टेंट में बदलाव किया गया है.		 इवेंट ऑब्जेक्ट में बदलाव करने पर शीट अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है शीट

function onEdit(e)

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

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

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

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

आप बस एक फ़ंक्शन लागू करके ऐड-ऑन में एक आसान ट्रिगर जोड़ सकते हैं निम्न में से एक आरक्षित नाम के साथ:

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

पाबंदियां

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Code.gs

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

authorizationemail.html

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