Google Apps Script: 從零開始掌握 google.script.run 函數 – 完整教學與實用範例

By徐培鈞
LinkedIn

更新日期： 2023 年 9 月 6 日

google.script.run 函數，允許我們在客戶端腳本（例如 HTML 中的 JavaScript）調用伺服器端的 Apps Script 函數。

這為前、後端之間的互動和數據交流，提供了強大的支援。

無論是建立一個動態的網頁，還是處理後端的數據分析，這個函數都發揮著關鍵作用。

本文會向初學者介紹 google.script.run 函數的基本概念、使用方法、實際應用，以及常見問題的解答。

無論你是剛接觸 Google Apps Script 的新手，還是有一些基本經驗，並希望深入了解的開發者，本文都會為你提供有用的指引。

那麼，讓我們不要再等待，馬上開始這個學習之旅吧！

什麼是 google.script.run？

google.script.run 是 Google Apps Script 中的一個特殊函數，它允許客戶端的 JavaScript 代碼，調用伺服器端的 Apps Script 函數。

這功能提供了一個橋樑，連接了前端（如網頁上的按鈕、輸入框等）與後端（如資料庫操作、API 請求等）的功能。

基本概念

兩端互動:

在 web 開發中，「客戶端」是指用戶的瀏覽器，而「伺服器端」則是托管應用程式的伺服器。google.script.run 允許這兩者之間的順暢交流。

非同步執行:

使用 google.script.run 調用的函數是非同步的。這意味著它不會立即返回結果，而是在執行完成後，通過回調函數返回結果。這使得界面在等待伺服器響應時不會被阻塞。

安全性:

Google Apps Script 已經內建了許多安全措施，以保護你的代碼和數據。使用 google.script.run 可以讓你在不暴露敏感信息的前提下，與伺服器端的 Apps Script 進行交互。

使用場景

google.script.run 常用於以下幾種場景：

動態填充網頁內容：

例如，根據用戶輸入的內容，從 Google 試算表中取得數據並展示在網頁上。

表單提交處理：

例如，將用戶通過網頁表單提交的資料，儲存到 Google 雲端硬碟或其他數據庫中。

與外部 API 交互：

例如，從客戶端觸發一個伺服器端的函數，該函數再與外部服務進行交互。

google.script.run 是 Google Apps Script 的核心特性之一，為前端和後端的互動提供了簡單且強大的解決方案。

通過理解和掌握這一函數，你可以為你的 Apps Script 項目開闢更多的可能性，讓它們變得更為動態和互動。

如何使用 google.script.run？

以下是如何使用它的步驟和範例：

1. 定義伺服器端的函數

首先，你需要在 Apps Script 中，定義一個或多個你想要在客戶端調用的函數。

// 伺服器端代碼
function myServerFunction(name) {
  return `Hello, ${name}!`;
}

2. 在客戶端調用伺服器端函數

接下來，你可以使用 google.script.run 在客戶端的 JavaScript 中調用上述函數。

<!-- 客戶端代碼 -->
<button onclick="callServerFunction()">Say Hello</button>

<script>
function callServerFunction() {
  google.script.run.withSuccessHandler(onSuccess).myServerFunction('Alice');
}

function onSuccess(response) {
  alert(response); // 彈出 "Hello, Alice!"
}
</script>

在這個例子中，執行順序是為：

  1. google.script.run 開始配置一個請求，以便從客戶端（也就是瀏覽器）調用伺服器端（Google Apps Script）的函數。
  2. .withSuccessHandler(onSuccess) 指定了一個成功處理程序，即當伺服器端函數成功執行並返回結果時，應該調用哪個函數。在這個例子中，它是 onSuccess 函數。
  3. .myServerFunction(‘Alice’) 最終指定了哪個伺服器端函數需要被調用，以及需要傳遞哪些參數。

總體來說，當這一行碼執行時，會先發出一個請求到伺服器端，調用 myServerFunction 並傳入 ‘Alice’ 作為參數。

伺服器端函數執行完畢後，其返回值（在這個例子中是 “Hello, Alice!”）會作為參數傳遞給 onSuccess 函數。

這個順序是由 google.script.run 的設計確定的。

這是一種非同步操作，你不能預先確定伺服器端函數何時完成執行。

但一旦它完成，成功處理程序（在這個例子中是 onSuccess）就會被調用。

這種模式是非常典型的在 JavaScript 和其他非同步編碼環境中。

3. 處理錯誤

你還可以使用 withFailureHandler() 定義一個當伺服器端函數執行失敗時，會被調用的回調函數。

function callServerFunction() {
  google.script.run
    .withSuccessHandler(onSuccess)
    .withFailureHandler(onFailure)
    .myServerFunction('Alice');
}

function onFailure(error) {
  alert('Something went wrong: ' + error.message);
}

在上面的代碼中，google.script.run 的執行順序如下：

  1. 初始化：google.script.run 開始設置一個從客戶端到伺服器端的請求。
  2. 設置成功處理程序：.withSuccessHandler(onSuccess) 指定了，如果伺服器端函數成功執行，那麼應該調用哪個函數（在這個例子中是 onSuccess）。
  3. 設置失敗處理程序：.withFailureHandler(onFailure) 指定了，如果伺服器端函數執行時發生了錯誤或異常，那麼應該調用哪個函數（在這個例子中是 onFailure）。
  4. 調用伺服器端函數：.myServerFunction(‘Alice’) 這是實際的伺服器端函數調用。這個函數會被傳入一個參數 ‘Alice’ 並在伺服器端執行。

這裡要注意的是：withSuccessHandler 和 withFailureHandler 只是設置了回調函數，這些回調函數在 myServerFunction 完成後才會被調用。

如果 myServerFunction 成功執行，則調用 onSuccess；如果出錯，則調用 onFailure。

這意味著當 callServerFunction 被調用時，真正首先執行的是 myServerFunction(‘Alice’)，然後根據伺服器端函數的結果，會觸發 onSuccess 或 onFailure。

google.script.run 的實際應用實例。

實例 1：表單提交和數據驗證

假設你有一個表單，用戶可以填寫一些資料並提交。

使用 google.script.run，你可以將數據傳送到伺服器進行處理和驗證。

<!-- 客戶端代碼 -->
<form id="myForm">
    <!-- 用戶名輸入欄位 -->
    <input type="text" name="username" required>
    <!-- 提交按鈕 -->
    <button type="button" onclick="submitForm()">Submit</button>
</form>

<script>
    // 提交表單函數
    function submitForm() {
        // 取得表單元素
        let form = document.getElementById('myForm');
        // 呼叫 `google.script.run()` 函數來處理表單
        google.script.run.withSuccessHandler(onSuccess).processForm(form);
    }

    // 成功處理函數
    function onSuccess(response) {
        // 顯示回應訊息
        alert(response.message);
    }
</script>
// 伺服器端代碼
function processForm(form) {
  // 檢查是否有用戶名
  if (form.username) {
    // 驗證和處理數據
    // 返回成功訊息
    return { message: 'Success!' };
  } else {
    // 返回錯誤訊息
    return { message: 'Please enter a username.' };
  }
}

實例 2：動態更新網頁內容

你可以使用 google.script.run 來動態更新網頁內容，根據伺服器端的數據或邏輯。

基本的代碼邏輯如下：

// 伺服器端代碼
function fetchContent() {
  // 從數據庫或其他來源獲取內容
  return 'Updated content goes here!';
}
<!-- 客戶端代碼 -->
<button onclick="updateContent()">Update Content</button>
<div id="content"></div>

<script>
    function updateContent() {
        google.script.run.withSuccessHandler(showContent).fetchContent();
    }

    function showContent(newContent) {
        document.getElementById('content').innerHTML = newContent;
    }
</script>

你可以使用 google.script.run 從客戶端網頁與 Google 試算表互動，例如讀取數據或插入新行。

我們以試算表（Google Spread Sheet）作為資料庫，實際的例子如下：

// 伺服器端代碼
function getSheetData() {
  // 取得當前活動的試算表和工作表
  let sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();

  // 取得指定範圍的值
  return sheet.getRange('A1:B10').getValues();
}

<!-- 客戶端代碼 -->
<!-- 建立了一個按鈕。當這個按鈕被點擊時，會執行loadData這個JavaScript函數。-->
<button onclick="loadData()">Load Data</button>

<!-- 建立了一個div元素，它的ID為"data"。此div將用於顯示從伺服器端獲取的資料。 -->
<div id="data"></div>

<script>
    // 載入數據按鈕
    function loadData() {
        // 呼叫 `google.script.run()` 函數來取得試算表數據
        google.script.run.withSuccessHandler(displayData).getSheetData();
    }

    // 顯示數據函數
    function displayData(data) {
        // 選擇了之前在 HTML 中定義的 div 元素。
        let div = document.getElementById('data');

        // 這行代碼處理從伺服器端獲取的資料，並將其格式化為字符串，然後將其插入到div中。
        // 具體來說，它先將每一行資料用逗號連接起來，然後用<br>將每一行分隔開。
        div.innerHTML = data.map(row => row.join(', ')).join('<br>');
    }
</script>

延伸閱讀：

與 google.script.run 相關的進階技巧

一旦掌握了 google.script.run 的基本用法，你可能會想要瞭解一些更進階的技巧，以更靈活和有效地使用這個功能。以下是一些進階技巧的詳細解釋：

1. 設定超時

在某些情況下，你可能想要設定一個超時，以便在指定的時間內完成伺服器端的操作。你可以使用客戶端的 setTimeout 函數來達到這個目的。

<script>
    // 客戶端代碼

    // 設定一個超時計時器，它將在5秒後觸發。這時，計時器開始計時。
    let timeoutID = setTimeout(function () {
        // 如果 serverFunction 超過5秒還沒有回應，那麼由於計時器已達到，所以將彈出 Request timed out! 的提示框：
        alert('Request timed out!');
    }, 5000);

    // 調用 Google Apps Script 的 serverFunction。
    // 如果 serverFunction 在5秒內成功完成，那麼成功處理器將被觸發：
    google.script.run
        .withSuccessHandler(function () {
            // 此行會取消之前設定的5秒計時器，阻止彈出提示框
            clearTimeout(timeoutID);
            // 調用 onSuccess 函數，注意這部分代碼片段中沒有提供此函數的具體實現
            onSuccess();
        })
        .serverFunction();
</script>

補充：定時器的ID

當你在JavaScript中使用setTimeout或setInterval函數設定一個定時器時，該函數會返回一個唯一的數字作為識別符（通常稱為定時器ID）。這個ID可以被用來參考、修改或取消該定時器。

這是一個基本的例子來說明如何使用這個ID：

// 設定一個將在5秒後執行的定時器
let timerId = setTimeout(function() {
    console.log("This message will be delayed by 5 seconds.");
}, 5000);

console.log("Timer ID:", timerId); // 你會看到一個數字，例如：1、2、3等，這取決於之前已經設定了多少定時器

// 如果你在定時器執行之前決定取消它：
clearTimeout(timerId);

在這個例子中，timerId 是 setTimeout 返回的定時器ID。然後，你可以使用 clearTimeout 和該 ID來取消定時器，確保回調函數不會被執行。

注意：每次調用 setTimeout 或 setInterval 都會返回一個新的、唯一的ID（通常是一個遞增的數字）。這確保了你可以單獨控制每個定時器，而不會影響其他定時器。

2. 同時處理多個請求

你可以同時發送多個 google.script.run 請求，並通過各自的成功和失敗處理器來處理每個請求。

<script>
    // 客戶端代碼
    google.script.run.withSuccessHandler(onSuccess1).function1();
    google.script.run.withSuccessHandler(onSuccess2).function2();
</script>

3. 在服務器端使用 Session 信息

有時你可能需要根據用戶的 Session 信息來進行操作。

你可以在伺服器端使用 Session.getActiveUser() 函數，它允許你獲取當前的使用者（通常是 Google 帳戶的電子郵件地址）。

// 伺服器端代碼
function getUserInfo() {
  var user = Session.getActiveUser();
  return user.getEmail();
}

在你的客戶端 HTML/JavaScript 中：

google.script.run.withSuccessHandler(function(email) {
  console.log("The active user is: " + email);
}).getActiveUserEmail();

這樣，當使用者與你的應用互動時，你就可以知道誰是當前的使用者，並可能根據他們的身份進行一些特定的操作或調整。

結語

掌握了這些進階技巧，你將能夠更加靈活和有效地使用 google.script.run，解決更複雜的問題。

從錯誤處理到設定超時，這些技巧提供了更深入的控制和自定義能力，有助於提升你的開發效率和代碼品質。

Similar Posts

初學者指南：深入了解 Python 靜態方法

By徐培鈞

在學習 Python 的物件導向程式設計（Object-Oriented Programming, OOP）時，靜態方法（Static Methods） 是一個重要的概念。

靜態方法允許我們在類別中，定義與類別和實體都無關的方法，從而組織相關的功能，而不需要創建實體或訪問類別屬性。

透過了解靜態方法，我們可以更靈活地設計類別，提升程式的結構性和可讀性。

本文將為新手詳細介紹 Python 中的靜態方法，解釋其作用、如何定義和使用，以及與實體方法和類別方法的區別。

初學者指南：深入了解 Python 實體變數

By徐培鈞

在學習 Python 的過程中，物件導向程式設計（Object-Oriented Programming, OOP） 是一個關鍵概念。

OOP 允許我們透過 類別（Class） 來創建 實體（Instance），從而更有效地組織和管理程式碼。

在物件導向中，實體變數（Instance Variables） 是理解類別和實體之間關係的重要元素。

本文將為新手詳細介紹 Python 中的實體變數，解釋其作用、如何使用，以及與類別變數的區別。

Python 函數預設參數陷阱詳解：新手指南

By徐培鈞

在 Python 中，函數預設參數 提供了一種方便的方式來設定函數引數的默認值。

然而，對於新手來說，這裡潛藏著一個常見的陷阱，特別是當預設參數是 可變物件（如列表、字典等） 時。

這個陷阱可能導致函數的行為與預期不符，產生難以察覺的錯誤。

本文將深入解析這個陷阱的成因、示例，並提供避免問題的方法，幫助新手更好地掌握 Python 函數的使用。

深入理解 Python 中的模組（Module）與套件（Package）

By徐培鈞

在學習 Python 的過程中，你可能會發現程式碼越寫越多，檔案也越來越複雜。

為了更好地組織程式碼，增強重用性和可維護性，Python 提供了 模組（Module） 和 套件（Package） 的概念。

它們是 Python 程式設計中關鍵的組織單位，有助於你編寫出結構清晰、易於維護的程式。

本文將為新手詳細介紹 Python 中的模組與套件，幫助你掌握如何有效地管理和使用它們。

新手指南：CSS @media 屬性簡介與應用

By徐培鈞

在現代網頁設計中，響應式設計已經成為必不可少的一部分。

隨著不同設備（如手機、平板電腦和桌面電腦）尺寸的多樣化，確保網站在不同螢幕上都有良好的顯示效果變得至關重要。

CSS 中的 @media 屬性，提供了一種強大的方式，來針對不同的設備和螢幕尺寸，設計和應用樣式。

這篇文章將介紹 @media 是什麼，以及如何使用它來創建響應式網站。