如何把 Google 試算表連接到你的應用程式

要把 Google 試算表連接到你的應用程式，請先在 Google Cloud 專案中啟用 Google Sheets API，建立一個服務帳戶，把試算表分享給該服務帳戶的 Email 位址，並把它的金鑰儲存為伺服器端的祕密。接著，你的伺服器就能用 spreadsheets.values.get 讀取資料列，並用 spreadsheets.values.append 新增資料列。如果使用者需要連接他們自己的試算表，請改用 OAuth；如果試算表完全公開，只讀取的話，簡單的 API 金鑰就夠了。

本指南涵蓋各種方法適合的情境、需要用到的呼叫、配額與常見陷阱，以及給 AI 應用程式建構工具的提示詞。Google 的相關細節取自 Google 截至 2026 年 9 月的開發者文件。

為什麼要連接試算表

常見的原因包括：

• **保留團隊的工作流程。**員工繼續在試算表中編輯價目表或班表，應用程式則負責顯示。
• **在大家本來就會看的地方收集資料。**新註冊的會員、訂單或表單回覆都會以資料列的形式出現。
• **報表。**把應用程式的資料匯出到試算表，供習慣使用試算表的人查看。
• **作為過渡。**先從試算表開始，之後再遷移到正式的資料庫。請參考如何把試算表變成應用程式。

選擇應用程式向 Google 登入的方式

Google 的憑證指南描述了三種類型：

對大多數應用程式來說，服務帳戶是正確的選擇：只需要一組由你擁有的憑證，而且只能存取你明確分享給它的試算表。

使用服務帳戶的逐步說明

1. 建立或選擇一個 Google Cloud 專案，並啟用 Google Sheets API。
2. 建立服務帳戶，並為它建立金鑰。金鑰是一個 JSON 檔案，請把它當成密碼一樣保管。
3. 把試算表分享給服務帳戶的 Email 位址：唯讀就給檢視者，需要寫入就給編輯者。Google 的指南說明這是透過一般的分享畫面完成。
4. 在伺服器上把金鑰儲存為祕密，例如 GOOGLE_SERVICE_ACCOUNT_JSON，並把試算表 ID（試算表網址中那一長串字元）儲存為 SHEET_ID。
5. 從伺服器呼叫 API，使用 Google 為你的程式語言提供的用戶端程式庫。
6. 快取讀取結果：如果很多訪客看到的是同樣的資料，就不會超過配額。

你會用到的呼叫

以下內容取自 Google 關於讀寫數值的指南：

範圍使用 A1 表示法。Google 提醒，沒有工作表名稱的範圍（例如 A1:B2）會套用到第一個工作表，因此請明確寫出分頁名稱，以免有人重新排列分頁時造成意外。

RAW 與 USER_ENTERED

寫入時需要指定 valueInputOption：

• RAW 會把你送出的內容原封不動地以文字儲存。=1+2 會被儲存為文字 =1+2。
• USER_ENTERED 會把輸入視同在試算表中手動輸入：日期會變成日期，=1+2 會變成公式。

如果你寫入的是使用者在應用程式中輸入的文字，請使用 RAW。使用 USER_ENTERED 的話，有人可能提交一個公式，等到同事打開試算表時才執行。

配額與錯誤

截至 2026 年 9 月，Google 的 Sheets API 限制頁面列出：

只要你維持在每分鐘的配額之內，就沒有每日上限。超過時會回傳 429：Too many requests，Google 建議使用截斷式指數退避：每次失敗後等待更久，並加入隨機延遲，直到達到上限為止。單一請求若超過 180 秒會逾時。

實務上：不要在每次頁面瀏覽時都呼叫 API。把試算表資料快取一分鐘以上，用 batchGet 合併讀取，並在可能的地方合併寫入。

方案與取捨

對於有大量使用者或敏感資料的情況，資料庫才是比較好的資料來源。請參考什麼是資料庫。

給 AI 建構工具的提示詞

讀取試算表：

在選單頁面顯示我們 Google 試算表中「Menu」分頁的內容。從伺服器使用 Google Sheets API，搭配服務帳戶，其 JSON 金鑰放在祕密 GOOGLE_SERVICE_ACCOUNT_JSON 中，試算表 ID 放在 SHEET_ID。讀取範圍 Menu!A2:D（名稱、描述、價格、分類）。把結果快取 5 分鐘。如果 API 失敗，顯示最後一次快取的版本。絕不把金鑰傳送到瀏覽器。

寫入資料列：

當有人提交聯絡表單時，把它存進我們的資料庫，同時使用 spreadsheets.values.append 並以 valueInputOption RAW，在「Leads」分頁新增一列（日期、姓名、Email、留言）。如果 Google 回傳 429，就以指數退避重試；如果仍然失敗，就把潛在客戶保留在資料庫中，之後再重試。

常見錯誤

• **忘記把試算表分享給服務帳戶的 Email。**即使金鑰沒問題，API 仍會回傳權限錯誤。
• **把金鑰放在前端或程式碼儲存庫中。**JSON 金鑰可以存取所有分享給它的試算表。請參考如何妥善保管 API 金鑰。
• 對使用者輸入使用 USER_ENTERED，這會允許公式注入。
• 每次請求都呼叫 API，結果在第一波流量高峰就超過每分鐘配額。
• **依賴欄位位置。**有人插入一欄後，應用程式就會讀到錯誤的資料。請讀取標題列並依名稱對應，或鎖定標題列。
• **分享範圍比需要的還廣。**設定「知道連結的任何人」就等於公開。
• **把試算表當成多人使用的資料庫。**同時寫入與權限缺失，會造成資料遺失或外洩。

檢查清單

• 已啟用 Sheets API，並已建立服務帳戶
• 試算表已以所需的最低角色分享給服務帳戶 Email
• 金鑰與試算表 ID 已儲存為伺服器端的祕密
• 所有呼叫都從伺服器發出
• 範圍中使用了分頁名稱
• 使用者提供的文字使用 RAW
• 讀取已快取；429 以退避機制處理
• Sheets 無法使用時，應用程式能優雅降級
• 已決定以哪一方為真正的資料來源

Mythex 中的 Google 試算表

Mythex 有兩種不同的方式來使用試算表。連接器會把你的 Google 帳戶連結到 Mythex，讓代理程式在你建構時可以使用，例如讀取試算表來建立儀表板；文件說明，憑證留在 Mythex 的連線服務中，不會進入你的程式碼（請參考連接器，並核准 Google 要求的每一項權限）。若要讓已發布的應用程式自行讀寫試算表，最可靠的方式是本指南中的做法：把服務帳戶金鑰以專案祕密的形式儲存，並由伺服器呼叫 Sheets API，參考整合任何 API。如果你的資料已經超出試算表能承載的範圍，可以請代理程式把資料移到專案的資料庫中，並在其上建立儀表板。

常見問題