บริการ HTML: สื่อสารกับฟังก์ชันของเซิร์ฟเวอร์

google.script.run เป็น JavaScript API ฝั่งไคลเอ็นต์แบบแอซิงโครนัสที่อนุญาตให้หน้าบริการ HTML เรียกใช้ฟังก์ชัน Apps Script ฝั่งเซิร์ฟเวอร์ ตัวอย่างต่อไปนี้แสดงฟังก์ชันพื้นฐานที่สุดของ google.script.run ซึ่งก็คือการเรียกฟังก์ชันบนเซิร์ฟเวอร์จาก JavaScript ฝั่งไคลเอ็นต์

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>

หากคุณติดตั้งใช้งานสคริปต์นี้เป็นเว็บแอปและไปที่ URL ของเว็บแอปดังกล่าว คุณจะไม่เห็นอะไรเลย แต่หากดูบันทึก คุณจะเห็นว่ามีเรียกใช้ฟังก์ชันเซิร์ฟเวอร์ doSomething()

การเรียกใช้ฟังก์ชันฝั่งเซิร์ฟเวอร์จากฝั่งไคลเอ็นต์เป็นแบบไม่พร้อมกัน กล่าวคือหลังจากที่เบราว์เซอร์ส่งคําขอให้เซิร์ฟเวอร์เรียกใช้ฟังก์ชัน doSomething() เบราว์เซอร์จะไปยังโค้ดบรรทัดถัดไปทันทีโดยไม่ต้องรอการตอบกลับ ซึ่งหมายความว่าการเรียกใช้ฟังก์ชันเซิร์ฟเวอร์อาจไม่ทํางานตามลําดับที่คุณคาดไว้ หากคุณเรียกใช้ฟังก์ชัน 2 รายการพร้อมกัน คุณจะไม่ทราบเลยว่าฟังก์ชันใดจะทำงานก่อน ผลลัพธ์จึงอาจแตกต่างกันไปทุกครั้งที่คุณโหลดหน้าเว็บ ในกรณีนี้ ตัวแฮนเดิลสําเร็จและตัวแฮนเดิลที่ผิดพลาดจะช่วยควบคุมการไหลของโค้ด

google.script.run API อนุญาตให้เรียกใช้ฟังก์ชันเซิร์ฟเวอร์พร้อมกันได้ 10 รายการ หากคุณโทรครั้งที่ 11 ขณะที่การโทร 10 ครั้งแรกยังดำเนินอยู่ ฟังก์ชันเซิร์ฟเวอร์จะล่าช้าจนกว่าจะมีจุดใดจุดหนึ่งใน 10 จุดว่าง ในทางปฏิบัติ คุณแทบจะไม่ต้องใช้ข้อจํากัดนี้เลย เนื่องจากเบราว์เซอร์ส่วนใหญ่จํากัดจํานวนคําขอพร้อมกันไปยังเซิร์ฟเวอร์เดียวกันไว้ที่น้อยกว่า 10 รายการอยู่แล้ว เช่น ใน Firefox ขีดจํากัดคือ 6 เบราว์เซอร์ส่วนใหญ่จะเลื่อนเวลาคำขอเซิร์ฟเวอร์ที่เกินมาจนกว่าคำขอที่มีอยู่รายการใดรายการหนึ่งจะเสร็จสมบูรณ์

พารามิเตอร์และค่าที่แสดงผล

คุณสามารถเรียกใช้ฟังก์ชันเซิร์ฟเวอร์ที่มีพารามิเตอร์จากไคลเอ็นต์ได้ ในทํานองเดียวกัน ฟังก์ชันเซิร์ฟเวอร์สามารถแสดงผลค่าไปยังไคลเอ็นต์เป็นพารามิเตอร์ที่ส่งไปยังตัวแฮนเดิลสําเร็จ

พารามิเตอร์และค่าที่แสดงผลที่ถูกต้องคือพรอมิเตีฟของ JavaScript เช่น Number, Boolean, String หรือ null รวมถึงออบเจ็กต์และอาร์เรย์ JavaScript ที่ประกอบไปด้วยพรอมิเตีฟ ออบเจ็กต์ และอาร์เรย์ องค์ประกอบ form ภายในหน้าเว็บใช้เป็นพารามิเตอร์ได้เช่นกัน แต่ต้องเป็นพารามิเตอร์เดียวของฟังก์ชัน และใช้เป็นค่าส่งคืนไม่ได้ คำขอจะดำเนินการไม่สำเร็จหากคุณพยายามส่ง Date, Function, องค์ประกอบ DOM นอกเหนือจาก form หรือประเภทอื่นๆ ที่ไม่ได้รับอนุญาต รวมถึงประเภทที่ไม่ได้รับอนุญาตภายในออบเจ็กต์หรืออาร์เรย์ ออบเจ็กต์ที่สร้างการอ้างอิงแบบวนซ้ำก็จะไม่สำเร็จเช่นกัน และฟิลด์ที่ไม่มีการกําหนดภายในอาร์เรย์จะกลายเป็นnull

โปรดทราบว่าออบเจ็กต์ที่ส่งไปยังเซิร์ฟเวอร์จะกลายเป็นสำเนาของออบเจ็กต์เดิม หากฟังก์ชันเซิร์ฟเวอร์ได้รับออบเจ็กต์และเปลี่ยนพร็อพเพอร์ตี้ พร็อพเพอร์ตี้ในไคลเอ็นต์จะไม่ได้รับผลกระทบ

แฮนเดิลสําเร็จ

เนื่องจากโค้ดฝั่งไคลเอ็นต์จะไปยังบรรทัดถัดไปโดยไม่ต้องรอการเรียกใช้เซิร์ฟเวอร์ให้เสร็จสมบูรณ์ withSuccessHandler(function) จึงให้คุณระบุฟังก์ชันการเรียกกลับฝั่งไคลเอ็นต์ให้ทำงานเมื่อเซิร์ฟเวอร์ตอบกลับ หากฟังก์ชันเซิร์ฟเวอร์แสดงผลค่า API จะส่งค่านั้นไปยังฟังก์ชันใหม่เป็นพารามิเตอร์

ตัวอย่างต่อไปนี้แสดงการแจ้งเตือนของเบราว์เซอร์เมื่อเซิร์ฟเวอร์ตอบกลับ โปรดทราบว่าตัวอย่างโค้ดนี้ต้องมีการให้สิทธิ์เนื่องจากฟังก์ชันฝั่งเซิร์ฟเวอร์จะเข้าถึงบัญชี Gmail ของคุณ วิธีที่ง่ายที่สุดในการให้สิทธิ์สคริปต์คือการเรียกใช้ฟังก์ชัน getUnreadEmails() ด้วยตนเองจากเครื่องมือแก้ไขสคริปต์ 1 ครั้งก่อนโหลดหน้าเว็บ หรือเมื่อทำให้เว็บแอปใช้งานได้ คุณสามารถเลือกที่จะเรียกใช้เว็บแอปในฐานะ "ผู้ใช้ที่เข้าถึงเว็บแอป" ซึ่งในกรณีนี้ระบบจะแจ้งให้คุณให้สิทธิ์เมื่อโหลดแอป

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) เพื่อระบุออบเจ็กต์ที่จะส่งไปยังตัวแฮนเดิลเป็นพารามิเตอร์ที่ 2 "ออบเจ็กต์ผู้ใช้" นี้ (อย่าสับสนกับคลาส 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 ไดรฟ์ แล้วพิมพ์ URL ของไฟล์ในหน้าฝั่งไคลเอ็นต์ ในตัวแฮนเดิล onsubmit คีย์เวิร์ด this จะอ้างอิงถึงแบบฟอร์มนั้นๆ โปรดทราบว่าเมื่อโหลดแบบฟอร์มทั้งหมดในหน้าเว็บ preventFormSubmit จะปิดใช้การดำเนินการส่งเริ่มต้น ซึ่งจะป้องกันไม่ให้หน้าเว็บเปลี่ยนเส้นทางไปยัง URL ที่ไม่ถูกต้องในกรณีที่มีข้อยกเว้น

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() ร่วมกันได้ทุกรูปแบบและลำดับ นอกจากนี้ คุณยังเรียกใช้ฟังก์ชันการแก้ไขใดก็ได้ในโปรแกรมรันสคริปต์ที่มีการตั้งค่าค่าไว้แล้ว ค่าใหม่จะลบล้างค่าก่อนหน้า

ตัวอย่างนี้จะตั้งค่าตัวแฮนเดิลข้อผิดพลาดทั่วไปสําหรับการเรียกเซิร์ฟเวอร์ทั้ง 3 รายการ แต่มีตัวแฮนเดิลความสําเร็จแยกกัน 2 รายการ ดังนี้

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 เอกสาร, ชีต หรือฟอร์มได้โดยเรียกใช้เมธอด google.script.host setWidth(width) หรือ setHeight(height) ในโค้ดฝั่งไคลเอ็นต์ (หากต้องการตั้งค่าขนาดเริ่มต้นของกล่องโต้ตอบ ให้ใช้HtmlOutputวิธี setWidth(width) และ setHeight(height)) โปรดทราบว่ากล่องโต้ตอบจะไม่จัดกึ่งกลางใหม่ในหน้าต่างหลักเมื่อปรับขนาด และคุณไม่สามารถปรับขนาดแถบด้านข้างได้

การปิดกล่องโต้ตอบและแถบด้านข้างใน Google Workspace

หากใช้บริการ HTML เพื่อแสดงกล่องโต้ตอบหรือแถบด้านข้างใน Google เอกสาร ชีต หรือฟอร์ม คุณจะปิดอินเทอร์เฟซด้วยการเรียกใช้ window.close() ไม่ได้ แต่คุณต้องโทรไปที่ google.script.host.close() แทน โปรดดูตัวอย่างที่ส่วนการแสดง HTML เป็น Google Workspace อินเทอร์เฟซผู้ใช้

การย้ายโฟกัสของเบราว์เซอร์ใน Google Workspace

หากต้องการเปลี่ยนโฟกัสในเบราว์เซอร์ของผู้ใช้จากกล่องโต้ตอบหรือแถบด้านข้างกลับไปที่เครื่องมือแก้ไข Google เอกสาร, ชีต หรือฟอร์ม ให้เรียกใช้เมธอด google.script.host.editor.focus() วิธีนี้มีประโยชน์อย่างยิ่งเมื่อใช้ร่วมกับวิธีบริการเอกสาร Document.setCursor(position) และ Document.setSelection(range)