इस पेज का अनुवाद Cloud Translation API से किया गया है.

एचटीएमएल सेवा: सर्वर के फ़ंक्शन के साथ संपर्क करना

google.script.run एक एसिंक्रोनस है क्लाइंट-साइड JavaScript API, जो एचटीएमएल-सेवा पेजों को सर्वर-साइड को कॉल करने की अनुमति देता है Apps Script फ़ंक्शन. यहां दिए गए उदाहरण में, सबसे बुनियादी फ़ंक्शन के बारे में बताया गया है google.script.run — का सर्वर पर फ़ंक्शन कॉल करना का इस्तेमाल किया जाता है.

Code.gs

function doGet() {
  return HtmlService.createHtmlOutputFromFile('Index');
}

function doSomething() {
  Logger.log('I was called!');
}

Index.html

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
    <script>
      google.script.run.doSomething();
    </script>
  </head>
</html>

अगर इस स्क्रिप्ट को वेब ऐप्लिकेशन के तौर पर डिप्लॉय किया जाता है और इसके यूआरएल पर जाया जाता है, तो आपको कुछ भी करते हुए, लेकिन लॉग देखने पर आपको दिखेगा कि सर्वर फ़ंक्शन doSomething() पर कॉल किया गया.

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

google.script.run एपीआई, सर्वर फ़ंक्शन को एक साथ 10 कॉल करने की अनुमति देता है. अगर आपने जब 10 चल रहा हो, तब आप 11वां कॉल करते हैं, तो सर्वर फ़ंक्शन 10 स्पॉट में से एक को मुक्त किए जाने तक देरी होगी. आपको शायद ही कभी इस प्रतिबंध के बारे में सोचने पर विचार करते हैं, विशेषकर जब कि ज़्यादातर ब्राउज़र पहले से ही एक ही सर्वर को 10 से कम संख्या पर एक साथ अनुरोधों की संख्या. उदाहरण के लिए, Firefox में यह सीमा छह है. ज़्यादातर ब्राउज़र इसी तरह से ज़्यादा देरी से देरी करते हैं सर्वर के अनुरोध तब तक करते हैं, जब तक मौजूदा अनुरोधों में से किसी एक के पूरा नहीं हो जाता.

पैरामीटर और रिटर्न वैल्यू

क्लाइंट के पैरामीटर के साथ सर्वर फ़ंक्शन को कॉल किया जा सकता है. इसी तरह, सर्वर फ़ंक्शन, क्लाइंट को सक्सेस हैंडलर.

कानूनी पैरामीटर और रिटर्न वैल्यू, Number जैसे JavaScript प्रिमिटिव हैं, Boolean, String या null के साथ-साथ, ऐसे JavaScript ऑब्जेक्ट और अरे प्रिमिटिव, ऑब्जेक्ट, और सरणियों से बने होते हैं. पेज में मौजूद form एलिमेंट पैरामीटर के रूप में भी कानूनी है, लेकिन यह फ़ंक्शन का एकमात्र पैरामीटर होना चाहिए और यह रिटर्न वैल्यू के रूप में कानूनी नहीं है. अनुरोध विफल हो सकता है, यदि आप form या दूसरी तरह के पाबंदी वाले टाइप के अलावा Date, Function, DOM एलिमेंट, इसमें ऑब्जेक्ट या अरे में पाबंदी वाले टाइप शामिल हैं. ऑब्जेक्ट जो बनाते हैं सर्कुलर रेफ़रंस भी काम नहीं करेंगे और अरे के अंदर तय नहीं किए गए फ़ील्ड बन जाएंगे null.

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

सक्सेस हैंडलर

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

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

Code.gs

function doGet() {
  return HtmlService.createHtmlOutputFromFile('Index');
}

function getUnreadEmails() {
  return GmailApp.getInboxUnreadCount();
}

Index.html

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
    <script>
      function onSuccess(numUnread) {
        var div = document.getElementById('output');
        div.innerHTML = 'You have ' + numUnread
            + ' unread messages in your Gmail inbox.';
      }

      google.script.run.withSuccessHandler(onSuccess)
          .getUnreadEmails();
    </script>
  </head>
  <body>
    <div id="output"></div>
  </body>
</html>

फ़ेलियर हैंडलर

अगर सर्वर जवाब नहीं दे पाता है या गड़बड़ी की जानकारी देता है, तो withFailureHandler(function) आपको इसकी मदद से सक्सेस हैंडलर के बजाय फ़ेलियर हैंडलर सेट करने देता है, Error ऑब्जेक्ट (अगर कोई है) को तर्क के तौर पर दिया गया हो.

अगर आप गड़बड़ी हैंडलर की जानकारी नहीं देते हैं, तो डिफ़ॉल्ट रूप से, गड़बड़ी को JavaScript कंसोल. इसे बदलने के लिए, withFailureHandler(null) पर कॉल करें या सप्लाई करें फ़ेलियर हैंडलर जो कुछ नहीं करता.

फ़ेलियर हैंडलर का सिंटैक्स करीब-करीब सक्सेस हैंडलर के जैसा है, जैसा कि उदाहरण के तौर पर दिखाया गया है.

Code.gs

function doGet() {
  return HtmlService.createHtmlOutputFromFile('Index');
}

function getUnreadEmails() {
  // 'got' instead of 'get' will throw an error.
  return GmailApp.gotInboxUnreadCount();
}

Index.html

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
    <script>
      function onFailure(error) {
        var div = document.getElementById('output');
        div.innerHTML = "ERROR: " + error.message;
      }

      google.script.run.withFailureHandler(onFailure)
          .getUnreadEmails();
    </script>
  </head>
  <body>
    <div id="output"></div>
  </body>
</html>

उपयोगकर्ता ऑब्जेक्ट

आप कॉल करके सर्वर withUserObject(object) का इस्तेमाल करें, जिसे हैंडलर को दूसरे पैरामीटर के रूप में पास किया जाएगा. यह “उपयोगकर्ता ऑब्जेक्ट” — यह User क्लास — इससे आपको के संदर्भ में है, जब क्लाइंट ने सर्वर से संपर्क किया. क्योंकि यूज़र ऑब्जेक्ट सर्वर को भेजा जाता है, तो इनमें लगभग सभी चीज़ें शामिल हो सकती हैं, जिनमें फ़ंक्शन, DOM शामिल हैं एलिमेंट, और इसी तरह की अन्य वैल्यू, पैरामीटर और रिटर्न वैल्यू पर लगी पाबंदियों के बिना का इस्तेमाल किया जा सकता है. हालांकि, उपयोगकर्ता ऑब्जेक्ट ऐसे नहीं हो सकते हैं जो new ऑपरेटर.

इस उदाहरण में, दोनों में से किसी भी बटन पर क्लिक करने से वह बटन मान को सर्वर से बदलें, जबकि अन्य बटन में कोई परिवर्तन न हो, भले ही वे एक सक्सेस हैंडलर शेयर किया जाता है. onclick हैंडलर के अंदर, कीवर्ड this button का ही संदर्भ देता है.

Code.gs

function doGet() {
  return HtmlService.createHtmlOutputFromFile('Index');
}

function getEmail() {
  return Session.getActiveUser().getEmail();
}

Index.html

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
    <script>
      function updateButton(email, button) {
        button.value = 'Clicked by ' + email;
      }
    </script>
  </head>
  <body>
    <input type="button" value="Not Clicked"
      onclick="google.script.run
          .withSuccessHandler(updateButton)
          .withUserObject(this)
          .getEmail()" />
    <input type="button" value="Not Clicked"
      onclick="google.script.run
          .withSuccessHandler(updateButton)
          .withUserObject(this)
          .getEmail()" />
  </body>
</html>

फ़ॉर्म

अगर सर्वर फ़ंक्शन को form एलिमेंट के साथ पैरामीटर के तौर पर कॉल किया जाता है, तो फ़ॉर्म एक ऑब्जेक्ट बन जाता है, जिसमें फ़ील्ड के नाम को कुंजियों के तौर पर और फ़ील्ड की वैल्यू को वैल्यू के तौर पर शामिल किया जाता है. कॉन्टेंट बनाने फ़ाइल-इनपुट की सामग्री को छोड़कर, सभी वैल्यू, स्ट्रिंग में बदली जाती हैं फ़ील्ड, जो Blob ऑब्जेक्ट बन जाते हैं.

यह उदाहरण, फिर से लोड किए बिना एक फ़ॉर्म को प्रोसेस करता है, जिसमें फ़ाइल-इनपुट फ़ील्ड भी शामिल है पेज; यह फ़ाइल को Google डिस्क पर अपलोड करता है और फिर फ़ाइल को क्लाइंट-साइड पेज पर रखना चाहिए. onsubmit हैंडलर के अंदर, कीवर्ड this फ़ॉर्म से ही मेल खाता है. ध्यान दें कि पेज में सभी फ़ॉर्म लोड होने पर सबमिट करने की डिफ़ॉल्ट कार्रवाई preventFormSubmit के ज़रिए बंद की गई है. इससे ऐसा होने पर, पेज को ग़लत यूआरएल पर रीडायरेक्ट करने से रोका जा सकता है.

Code.gs

function doGet() {
  return HtmlService.createHtmlOutputFromFile('Index');
}

function processForm(formObject) {
  var formBlob = formObject.myFile;
  var driveFile = DriveApp.createFile(formBlob);
  return driveFile.getUrl();
}

Index.html

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
    <script>
      // Prevent forms from submitting.
      function preventFormSubmit() {
        var forms = document.querySelectorAll('form');
        for (var i = 0; i < forms.length; i++) {
          forms[i].addEventListener('submit', function(event) {
            event.preventDefault();
          });
        }
      }
      window.addEventListener('load', preventFormSubmit);

      function handleFormSubmit(formObject) {
        google.script.run.withSuccessHandler(updateUrl).processForm(formObject);
      }
      function updateUrl(url) {
        var div = document.getElementById('output');
        div.innerHTML = '<a href="' + url + '">Got it!</a>';
      }
    </script>
  </head>
  <body>
    <form id="myForm" onsubmit="handleFormSubmit(this)">
      <input name="myFile" type="file" />
      <input type="submit" value="Submit" />
    </form>
    <div id="output"></div>
 </body>
</html>

स्क्रिप्ट रनर

google.script.run को "स्क्रिप्ट रनर" के लिए बिल्डर बनाने में मदद मिलती है. अगर आपको स्क्रिप्ट रनर में सक्सेस हैंडलर, फ़ेलियर हैंडलर या उपयोगकर्ता ऑब्जेक्ट जोड़ने का तरीका मौजूदा रनर को नहीं बदल रहे हैं; इसकी जगह, आपको एक नया स्क्रिप्ट रनर वापस मिलता है नए व्यवहार के साथ.

कोई भी कॉम्बिनेशन और withSuccessHandler() के किसी भी क्रम का इस्तेमाल किया जा सकता है, withFailureHandler() और withUserObject(). आप किसी भी समय किसी ऐसे स्क्रिप्ट रनर पर फ़ंक्शन में बदलाव करना जिसमें पहले से ही एक वैल्यू सेट हो. नया वैल्यू, पिछली वैल्यू को बदल देती है.

यह उदाहरण सभी तीन सर्वर कॉल के लिए एक सामान्य फ़ेलियर हैंडलर सेट करता है, लेकिन दो अलग-अलग सक्सेस हैंडलर:

var myRunner = google.script.run.withFailureHandler(onFailure);
var myRunner1 = myRunner.withSuccessHandler(onSuccess);
var myRunner2 = myRunner.withSuccessHandler(onDifferentSuccess);

myRunner1.doSomething();
myRunner1.doSomethingElse();
myRunner2.doSomething();

निजी फ़ंक्शन

जिन सर्वर फ़ंक्शन के नाम के आखिर में अंडरस्कोर होता है उन्हें निजी माना जाता है. इन फ़ंक्शन को google.script से कॉल नहीं किया जा सकता और इनके नाम कभी नहीं डाले जाते क्लाइंट को भेजा गया. इसलिए, इनका इस्तेमाल लागू करने की जानकारी को छिपाने के लिए किया जा सकता है. उन्हें सर्वर पर गोपनीय रखना होता है. google.script को भी नहीं दिखेगा लाइब्रेरी में मौजूद फ़ंक्शन और ऐसे फ़ंक्शन जो का एलान स्क्रिप्ट के टॉप लेवल पर किया जाता है.

इस उदाहरण में, getBankBalance() फ़ंक्शन क्लाइंट में उपलब्ध है कोड; अगर कोई उपयोगकर्ता आपके सोर्स कोड की जांच करता है, तो वह उसका नाम तब भी खोज सकता है, जब उसे कॉल मत करो. हालांकि, deepSecret_() और obj.objectMethod() फ़ंक्शन पूरी तरह से नहीं दिखते से संपर्क करने के लिए प्रोत्साहित करें.

Code.gs

function doGet() {
  return HtmlService.createHtmlOutputFromFile('Index');
}

function getBankBalance() {
  var email = Session.getActiveUser().getEmail()
  return deepSecret_(email);
}

function deepSecret_(email) {
 // Do some secret calculations
 return email + ' has $1,000,000 in the bank.';
}

var obj = {
  objectMethod: function() {
    // More secret calculations
  }
};

Index.html

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
    <script>
      function onSuccess(balance) {
        var div = document.getElementById('output');
        div.innerHTML = balance;
      }

      google.script.run.withSuccessHandler(onSuccess)
          .getBankBalance();
    </script>
  </head>
  <body>
    <div id="output">No result yet...</div>
  </body>
</html>

ऐप्लिकेशन में डायलॉग का Google Workspace साइज़ बदला जा रहा है

Google Docs, Sheets या Sheets में कस्टम डायलॉग बॉक्स फ़ॉर्म का साइज़ बदलने के लिए, google.script.host तरीके setWidth(width) या setHeight(height) में क्लाइंट-साइड कोड डालें. (किसी डायलॉग का शुरुआती साइज़ सेट करने के लिए, HtmlOutput का इस्तेमाल करें तरीका setWidth(width) और setHeight(height).) ध्यान दें कि साइज़ का साइज़ बदलने पर डायलॉग, पैरंट विंडो में फिर से सेंटर में नहीं होते. ऐसा करने पर साइडबार का साइज़ नहीं बदला जा सकता.

डायलॉग और साइडबार को Google Workspaceमें बंद किया जा रहा है

यदि आप Google Docs, Sheets या Sheets में डायलॉग बॉक्स या साइडबार फ़ॉर्म के लिए, आप window.close() को कॉल करके इंटरफ़ेस बंद नहीं कर सकते. इसके बजाय, आप कॉल करना ज़रूरी है google.script.host.close(). उदाहरण के लिए, एचटीएमएल को Google Workspace यूज़र इंटरफ़ेस के तौर पर दिखाना.

ब्राउज़र के फ़ोकस को Google Workspaceमें ले जाया जा रहा है

उपयोगकर्ता के ब्राउज़र में फ़ोकस को डायलॉग या साइडबार से वापस Google Docs, Sheets या Forms एडिटर का इस्तेमाल करके, google.script.host.editor.focus(). यह तरीका खास तौर पर इन दोनों के लिए मददगार है दस्तावेज़ सेवा के तरीके Document.setCursor(position) और Document.setSelection(range).