आसान ट्रिगर

जब कोई खास इवेंट, जैसे कि कोई दस्तावेज़ खोलना होता है, तो ट्रिगर की मदद से 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) तब तक अपने-आप नहीं चलता, जब तक फ़ाइल को फिर से खोला नहीं जाता.

triggers/triggers.gs
/**
 * 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) फ़ंक्शन सेल के बैकग्राउंड को लाल पर सेट कर देता है.

triggers/triggers.gs
/**
 * 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) ट्रिगर अपने-आप चलता है. doPost(e) तब चलता है, जब कोई प्रोग्राम किसी वेब ऐप्लिकेशन को एचटीटीपी POST अनुरोध भेजता है. इन ट्रिगर को वेब ऐप्लिकेशन, एचटीएमएल सेवा, और कॉन्टेंट सेवा की गाइड में ज़्यादा दिखाया जाता है. ध्यान दें कि doGet(e) और doPost(e) पर ऊपर बताई गई पाबंदियां लागू नहीं होती हैं.

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

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

इवेंट आसान ट्रिगर इंस्टॉल किए जा सकने वाले ट्रिगर
खुला है
Sheets
Slides
Forms*
Docs

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

function onEdit(e)
शीट
चुने गए बदलाव
शीट

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

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

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

function doPost(e)

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