Google Apps Script 試算表 Web App CRUD：用 google.script.run 寫出可驗證資料操作

Q: 為什麼更新資料不直接保存列號？

列號會因排序、插入或刪除而改變。範例替每筆資料建立 UUID，更新與刪除時先以 id 找到當前列，再操作那一列，對簡單工具比較不容易誤寫其他資料。

2026-08-04

工具推薦

/

/

/

/

如果只是要做一個讓團隊查詢和維護資料的小工具，不一定要先架資料庫與獨立後端。Google Apps Script Web App 可以用 doGet() 提供 HTML 介面，再透過 google.script.run 呼叫伺服器端函式，把資料寫進 Google Sheets。

這篇用一個 Items 工作表示範 CRUD：新增、讀取、更新、刪除都在 Apps Script 後端完成，瀏覽器只負責表單與畫面。這個做法適合內部工具或低流量原型；若要讓外部程式直接用 HTTP 傳 JSON，文末再補上 doPost(e) 的入口。

先選對 Web App 的資料流#

Google 官方文件規定，Web App 至少要有 doGet(e) 或 doPost(e)，而且必須回傳 HtmlOutput 或 TextOutput。瀏覽器開啟網址會觸發 doGet，程式送出 HTTP POST 則會觸發 doPost。這是入口點，不等於每個 CRUD 操作都必須自己解析 HTTP。

使用情境	建議入口	CRUD 呼叫方式
自己控制的 HTML 頁面	`doGet()`	`google.script.run` 非同步呼叫伺服器函式
外部前端、Webhook 或腳本	`doPost(e)`	`e.postData.contents` 解析 JSON
只想讓使用者直接查看資料	`doGet(e)`	讀取 query string 或回傳 HTML

如果你還沒處理過 Web App 的存取者與執行身分，先看 Google Apps Script Web App 的 execute as 與 access 權限邊界。本文的程式碼解決的是資料操作，不會替你決定誰有權限使用資料。

建立試算表與 Apps Script#

先建立一份 Google 試算表，新增名為 Items 的工作表。第一列預留四個欄位：id、name、status、updatedAt。接著從 Extensions → Apps Script 開啟繫結腳本，建立 Code.gs。

下面的後端程式會在工作表為空時補上標題列，並將輸入限制在必要欄位。id 使用 Apps Script 產生的 UUID，因此更新或刪除時不需要依賴列號；這也避免使用者在試算表排序後，前端仍拿舊列號操作資料。

1
const SHEET_NAME = 'Items';
2
const HEADERS = ['id', 'name', 'status', 'updatedAt'];
3

4
function doGet() {
5
  return HtmlService.createHtmlOutputFromFile('Index')
6
    .setTitle('Items 管理');
7
}
8

9
function getSheet_() {
10
  const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName(SHEET_NAME);
11
  if (!sheet) {
12
    throw new Error(`找不到工作表：${SHEET_NAME}`);
13
  }
14

15
  if (sheet.getLastRow() === 0) {
16
    sheet.getRange(1, 1, 1, HEADERS.length).setValues([HEADERS]);
17
  }
18

19
  return sheet;
20
}
21

22
function normalizeItem_(input) {
23
  const name = String(input?.name ?? '').trim();
24
  const status = String(input?.status ?? 'todo').trim();
25

26
  if (!name || name.length > 120) {
27
    throw new Error('名稱必須是 1 到 120 個字元');
28
  }
29

30
  if (!['todo', 'doing', 'done'].includes(status)) {
31
    throw new Error('status 只能是 todo、doing 或 done');
32
  }
33

34
  return { name, status };
35
}
36

37
function listItems() {
38
  const sheet = getSheet_();
39
  const lastRow = sheet.getLastRow();
40
  if (lastRow < 2) return [];
41

42
  return sheet
43
    .getRange(2, 1, lastRow - 1, HEADERS.length)
44
    .getValues()
45
    .filter((row) => row[0])
46
    .map(([id, name, status, updatedAt]) => ({
47
      id: String(id),
48
      name: String(name),
49
      status: String(status),
50
      updatedAt: updatedAt instanceof Date ? updatedAt.toISOString() : String(updatedAt),
51
    }));
52
}
53

54
function createItem(input) {
55
  const item = normalizeItem_(input);
56
  const sheet = getSheet_();
57
  const now = new Date();
58
  const row = [Utilities.getUuid(), item.name, item.status, now];
59

60
  sheet.appendRow(row);
61
  return { id: row[0], name: row[1], status: row[2], updatedAt: now.toISOString() };
62
}
63

64
function findRowById_(id) {
65
  const target = String(id ?? '').trim();
66
  if (!target) throw new Error('缺少 item id');
67

68
  const sheet = getSheet_();
69
  const dataRows = Math.max(sheet.getLastRow() - 1, 0);
70
  if (dataRows === 0) throw new Error('找不到指定資料');
71

72
  const values = sheet.getRange(2, 1, dataRows, 1).getValues();
73
  const index = values.findIndex(([value]) => String(value) === target);
74
  if (index === -1) throw new Error('找不到指定資料');
75

76
  return { sheet, rowNumber: index + 2 };
77
}
78

79
function updateItem(input) {
80
  const item = normalizeItem_(input);
81
  const { sheet, rowNumber } = findRowById_(input?.id);
82
  const now = new Date();
83
  sheet.getRange(rowNumber, 2, 1, 3).setValues([[item.name, item.status, now]]);
84

85
  return {
86
    id: String(input.id),
87
    name: item.name,
88
    status: item.status,
89
    updatedAt: now.toISOString(),
90
  };
91
}
92

93
function deleteItem(id) {
94
  const { sheet, rowNumber } = findRowById_(id);
95
  sheet.deleteRow(rowNumber);
96
  return { id: String(id), deleted: true };
97
}

Sheet.appendRow() 會把陣列追加到目前資料區的最後一列；讀取與更新則使用 getRange() 取得明確範圍。這兩個方法的授權範圍與行為，請以 Google Apps Script Sheet 類別文件為準。

用 `google.script.run` 接上 HTML#

新增 Index.html。google.script.run 是非同步 API，所以每個操作都要提供成功與失敗處理；不要在呼叫後立刻假設資料已經寫入。Google 官方也提醒，同時送出的伺服器函式呼叫不保證執行順序，因此這個範例每次操作完成後才重新載入清單。

1
<!doctype html>
2
<html lang="zh-Hant">
3
  <head>
4
    <base target="_top">
5
    <meta charset="utf-8">
6
    <title>Items 管理</title>
7
  </head>
8
  <body>
9
    <main>
10
      <h1>Items</h1>
11
      <form id="item-form">
12
        <input id="item-id" type="hidden">
13
        <label>
14
          名稱
15
          <input id="item-name" maxlength="120" required>
16
        </label>
17
        <label>
18
          狀態
19
          <select id="item-status">
20
            <option value="todo">待處理</option>
21
            <option value="doing">進行中</option>
22
            <option value="done">完成</option>
23
          </select>
24
        </label>
25
        <button type="submit">儲存</button>
26
        <button id="cancel-edit" type="button" hidden>取消編輯</button>
27
      </form>
28
      <p id="message" role="status"></p>
29
      <ul id="item-list"></ul>
30
    </main>
31

32
    <script>
33
      const form = document.querySelector('#item-form');
34
      const idInput = document.querySelector('#item-id');
35
      const nameInput = document.querySelector('#item-name');
36
      const statusInput = document.querySelector('#item-status');
37
      const list = document.querySelector('#item-list');
38
      const message = document.querySelector('#message');
39
      const cancelButton = document.querySelector('#cancel-edit');
40

41
      function callServer(method, value) {
42
        return new Promise((resolve, reject) => {
43
          const runner = google.script.run
44
            .withSuccessHandler(resolve)
45
            .withFailureHandler((error) => reject(new Error(error.message || error)));
46
          runner[method](value);
47
        });
48
      }
49

50
      function render(items) {
51
        list.replaceChildren();
52
        for (const item of items) {
53
          const row = document.createElement('li');
54
          row.textContent = `${item.name}（${item.status}）`;
55

56
          const edit = document.createElement('button');
57
          edit.type = 'button';
58
          edit.textContent = '編輯';
59
          edit.addEventListener('click', () => {
60
            idInput.value = item.id;
61
            nameInput.value = item.name;
62
            statusInput.value = item.status;
63
            cancelButton.hidden = false;
64
          });
65

66
          const remove = document.createElement('button');
67
          remove.type = 'button';
68
          remove.textContent = '刪除';
69
          remove.addEventListener('click', async () => {
70
            if (!window.confirm(`確定刪除「${item.name}」？`)) return;
71
            await callServer('deleteItem', item.id);
72
            await loadItems();
73
          });
74

75
          row.append(' ', edit, ' ', remove);
76
          list.append(row);
77
        }
78
      }
79

80
      async function loadItems() {
81
        try {
82
          render(await callServer('listItems'));
83
          message.textContent = '';
84
        } catch (error) {
85
          message.textContent = `讀取失敗：${error.message}`;
86
        }
87
      }
88

89
      form.addEventListener('submit', async (event) => {
90
        event.preventDefault();
91
        const item = { id: idInput.value, name: nameInput.value, status: statusInput.value };
92

93
        try {
94
          await callServer(idInput.value ? 'updateItem' : 'createItem', item);
95
          form.reset();
96
          idInput.value = '';
97
          cancelButton.hidden = true;
98
          message.textContent = '已儲存';
99
          await loadItems();
100
        } catch (error) {
101
          message.textContent = `儲存失敗：${error.message}`;
102
        }
103
      });
104

105
      cancelButton.addEventListener('click', () => {
106
        form.reset();
107
        idInput.value = '';
108
        cancelButton.hidden = true;
109
      });
110

111
      loadItems();
112
    </script>
113
  </body>
114
</html>

這裡沒有直接把使用者輸入拼成 HTML，而是用 textContent 放入清單，避免把輸入當成標記解讀。若要加入格式化或預覽，先定義允許的欄位與轉義規則，不要直接把資料塞入 innerHTML。

多人寫入時，補上鎖與重複提交檢查#

範例為了保持清楚，createItem() 直接 appendRow()。若多位使用者可能同時儲存，應在新增、更新、刪除的關鍵區段使用 Lock Service 控制競爭，並讓前端在送出期間停用儲存按鈕。這能降低雙擊造成重複資料的機會，但不會替你建立完整交易系統。

此外，刪除前仍應由後端重新確認 id 存在；不能只因按鈕是從合法清單產生，就把前端送來的 ID 視為可信。

何時改用 `doPost(e)`#

如果呼叫端不是這個 HTML 頁面，而是外部前端或 webhook，可以用 doPost(e) 接收 JSON。這個版本只示範把請求導向同一組後端函式，實際部署仍要配合 Web App 的 access 與 execute as 設定。

1
function doPost(e) {
2
  try {
3
    const body = JSON.parse(e?.postData?.contents || '{}');
4
    const action = String(body.action || '');
5
    let result;
6

7
    if (action === 'create') result = createItem(body.item);
8
    else if (action === 'update') result = updateItem(body.item);
9
    else if (action === 'delete') result = deleteItem(body.id);
10
    else throw new Error('不支援的 action');
11

12
    return ContentService
13
      .createTextOutput(JSON.stringify({ ok: true, result }))
14
      .setMimeType(ContentService.MimeType.JSON);
15
  } catch (error) {
16
    return ContentService
17
      .createTextOutput(JSON.stringify({ ok: false, error: error.message }))
18
      .setMimeType(ContentService.MimeType.JSON);
19
  }
20
}

不要把這段程式誤解成「只要有 URL 就能安全公開資料庫」。外部 HTTP 呼叫需要另外處理驗證、重放、權限、速率限制與錯誤紀錄；若只是內部畫面，google.script.run 通常更容易收斂權限範圍。既有的 Google Apps Script WebApp 商品管理實戰則偏向表單與雙介面設計，本文則把資料層的 CRUD 邊界拆開。