आसान ट्रिगर

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

Google Workspace ऐड-ऑन प्रोजेक्ट में ट्रिगर इस्तेमाल करने के तरीके के बारे में जानने के लिए, Google Workspace ऐड-ऑन के लिए ट्रिगर लेख पढ़ें.

शुरू करना

सिंपल ट्रिगर का इस्तेमाल करने के लिए, ऐसा फ़ंक्शन बनाएं जो रिज़र्व किए गए इन फ़ंक्शन के नामों में से किसी एक का इस्तेमाल करता हो:

• onOpen(e) तब चलता है, जब कोई उपयोगकर्ता ऐसी स्प्रेडशीट, दस्तावेज़, प्रज़ेंटेशन या फ़ॉर्म खोलता है जिसमें बदलाव करने की अनुमति उसके पास है.
• onInstall(e) तब चलता है, जब कोई उपयोगकर्ता Google Docs, Sheets, Slides या Forms में जाकर, एडिटर ऐड-ऑन इंस्टॉल करता है.
• onEdit(e) तब चलता है, जब कोई उपयोगकर्ता स्प्रेडशीट में किसी वैल्यू को बदलता है.
• onSelectionChange(e) तब चलता है, जब कोई उपयोगकर्ता स्प्रेडशीट में किसी सेल को चुनता है.
• doGet(e) तब चलता है, जब कोई उपयोगकर्ता वेब ऐप्लिकेशन पर जाता है या कोई प्रोग्राम, वेब ऐप्लिकेशन को एचटीटीपी GET अनुरोध भेजता है.
• doPost(e) तब चलता है, जब कोई प्रोग्राम किसी वेब ऐप्लिकेशन को एचटीटीपी POST अनुरोध भेजता है.

ऊपर दिए गए फ़ंक्शन के नामों में मौजूद e पैरामीटर, एक इवेंट ऑब्जेक्ट है. इसे फ़ंक्शन में पास किया जाता है. इस ऑब्जेक्ट में उस कॉन्टेक्स्ट के बारे में जानकारी होती है जिसकी वजह से ट्रिगर फ़ायर हुआ. हालांकि, इसका इस्तेमाल करना ज़रूरी नहीं है.

पाबंदियां

सिंपल ट्रिगर अपने-आप चालू हो जाते हैं. इसके लिए, उपयोगकर्ता से अनुमति नहीं मांगी जाती. इसलिए, इन पर कई पाबंदियां लागू होती हैं:

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

ये पाबंदियां, doGet(e) या doPost(e) पर लागू नहीं होती हैं.

onOpen(e)

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

/**
 * The event handler triggered when opening the spreadsheet.
 * @param {Event} e The onOpen event.
 * @see https://developers.google.com/apps-script/guides/triggers#onopene
 */
function onOpen(e) {
  // Add a custom menu to the spreadsheet.
  SpreadsheetApp.getUi() // Or DocumentApp, SlidesApp, or FormApp.
    .createMenu("Custom Menu")
    .addItem("First item", "menuItem1")
    .addToUi();
}

onInstall(e)

जब कोई उपयोगकर्ता Google Docs, Sheets, Slides या Forms में जाकर, Editor add-on इंस्टॉल करता है, तो onInstall(e) ट्रिगर अपने-आप चालू हो जाता है. जब कोई उपयोगकर्ता Google Workspace Marketplace की वेबसाइट से ऐड-ऑन इंस्टॉल करता है, तब यह ट्रिगर काम नहीं करता. onInstall(e) का सबसे ज़्यादा इस्तेमाल, onOpen(e) को कॉल करने के लिए किया जाता है, ताकि कस्टम मेन्यू जोड़े जा सकें. ऐड-ऑन इंस्टॉल होने के बाद, फ़ाइल पहले से ही खुली होती है. इसलिए, जब तक फ़ाइल को फिर से नहीं खोला जाता, तब तक onOpen(e) अपने-आप नहीं चलता. ध्यान दें कि onInstall(e) के पास कुछ सीमित अधिकार होते हैं. अनुमति के बारे में ज़्यादा जानें.

/**
 * The event handler triggered when installing the add-on.
 * @param {Event} e The onInstall event.
 * @see https://developers.google.com/apps-script/guides/triggers#oninstalle
 */
function onInstall(e) {
  onOpen(e);
}

onEdit(e)

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

/**
 * The event handler triggered when editing the spreadsheet.
 * @param {Event} e The onEdit event.
 * @see https://developers.google.com/apps-script/guides/triggers#onedite
 */
function onEdit(e) {
  // Set a comment on the edited cell to indicate when it was changed.
  const range = e.range;
  range.setNote(`Last modified: ${new Date()}`);
}

onEdit() ट्रिगर, सिर्फ़ दो ट्रिगर इवेंट को कतार में लगाता है.

onSelectionChange(e)

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

अगर कुछ ही समय में सिलेक्शन एक से ज़्यादा सेल के बीच में बदलता है, तो लेटेन्सी कम करने के लिए, सिलेक्शन में बदलाव से जुड़े कुछ इवेंट स्किप किए जा सकते हैं. उदाहरण के लिए, अगर दो सेकंड के अंदर कई बार आइटम चुने जाते हैं, तो सिर्फ़ पहली और आखिरी बार आइटम चुने जाने पर onSelectionChange(e) ट्रिगर होता है.

इस उदाहरण में, अगर कोई खाली सेल चुनी जाती है, तो onSelectionChange(e) फ़ंक्शन, सेल के बैकग्राउंड को लाल रंग में सेट कर देता है.

/**
 * The event handler triggered when the selection changes in the spreadsheet.
 * @param {Event} e The onSelectionChange event.
 * @see https://developers.google.com/apps-script/guides/triggers#onselectionchangee
 */
function onSelectionChange(e) {
  // Set background to red if a single empty cell is selected.
  const range = e.range;
  if (
    range.getNumRows() === 1 &&
    range.getNumColumns() === 1 &&
    range.getCell(1, 1).getValue() === ""
  ) {
    range.setBackground("red");
  }
}

doGet(e) और doPost(e)

जब कोई उपयोगकर्ता किसी वेब ऐप्लिकेशन पर जाता है या कोई प्रोग्राम किसी वेब ऐप्लिकेशन को एचटीटीपी GET अनुरोध भेजता है, तो doGet(e) ट्रिगर अपने-आप चालू हो जाता है. जब कोई प्रोग्राम किसी वेब ऐप्लिकेशन को एचटीटीपी POST अनुरोध भेजता है, तब doPost(e) ट्रिगर चालू होता है. इन ट्रिगर के बारे में ज़्यादा जानकारी, वेब ऐप्लिकेशन, एचटीएमएल सेवा, और कॉन्टेंट सेवा से जुड़ी गाइड में दी गई है. ध्यान दें कि doGet(e) और doPost(e) पर, ऊपर दी गई पाबंदियां लागू नहीं होती हैं.

उपलब्ध ट्रिगर टाइप

अगर सामान्य ट्रिगर पर लगी पाबंदियों की वजह से, आपकी ज़रूरतें पूरी नहीं हो पा रही हैं, तो इंस्टॉल किए जा सकने वाले ट्रिगर का इस्तेमाल किया जा सकता है. यहां दी गई टेबल में, इस बारे में खास जानकारी दी गई है कि हर इवेंट टाइप के लिए, किस तरह के ट्रिगर उपलब्ध हैं. उदाहरण के लिए, Google Sheets, Slides, Forms, और Docs, सभी में सामान्य ओपन ट्रिगर काम करते हैं. हालांकि, सिर्फ़ Sheets, Docs, और Forms में इंस्टॉल किए जा सकने वाले ओपन ट्रिगर काम करते हैं.

इवेंट	सामान्य ट्रिगर	इंस्टॉल किए जा सकने वाले ट्रिगर
खोलें	function onOpen(e)
बदलाव करें	function onEdit(e)
चुने गए आइटम में बदलाव	function onSelectionChange(e)
इंस्टॉल करें	function onInstall(e)
बदलें
फ़ॉर्म सबमिट करना
समय के हिसाब से (घड़ी)
पाएं	function doGet(e)
पोस्ट करें	function doPost(e)

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