आसान ट्रिगर

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

शुरू करना

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

  • 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 में कस्टम मेन्यू आइटम जोड़ने के लिए किया जाता है.

triggers/triggers.gs
/**
 * 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 में एडिटर ऐड-ऑन इंस्टॉल करता है, तो onInstall(e) ट्रिगर अपने-आप चल जाता है. जब कोई उपयोगकर्ता Google Workspace Marketplace की वेबसाइट से ऐड-ऑन इंस्टॉल करता है, तो ट्रिगर नहीं चलेगा. ध्यान दें कि onInstall(e) क्या कर सकता है, इस पर कुछ पाबंदियां हैं. अनुमति देने के बारे में ज़्यादा जानें. onInstall(e) का सबसे आम इस्तेमाल, पसंद के मुताबिक मेन्यू जोड़ने के लिए onOpen(e) को कॉल करना है. आखिरकार, जब कोई ऐड-ऑन इंस्टॉल किया जाता है, तो फ़ाइल पहले से ही खुली होती है. इसलिए, onOpen(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) फ़ंक्शन, सेल पर एक टिप्पणी सेट करता है, जिसमें सेल में पिछली बार किए गए बदलाव का रिकॉर्ड होता है.

triggers/triggers.gs
/**
 * 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());
}

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 में, इंस्टॉल किए जा सकने वाले ट्रिगर काम करते हैं.

इवेंट आसान ट्रिगर इंस्टॉल किए जा सकने वाले ट्रिगर
खोलें
Sheets
Slides
फ़ॉर्म*
Docs

function onOpen(e)
Sheets
Forms*
Docs
बदलाव करें
Sheets

function onEdit(e)
Sheets
चुने गए आइटम में बदलाव
Sheets

function onSelectionChange(e)
इंस्टॉल करें
Sheets
Slides
Forms
Docs

function onInstall(e)
बदलें
Sheets
फ़ॉर्म सबमिट
शीट
फ़ॉर्म
समय के हिसाब से (घड़ी)
Sheets
Slides
फ़ॉर्म
Docs
स्टैंडअलोन
पाएं
स्टैंडअलोन

function doGet(e)
पोस्ट करें
स्टैंडअलोन

function doPost(e)

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