如何將 Google Sheets 連接到你的應用程式
要把 Google Sheets 連接到你的應用程式，請在 Google Cloud 專案中啟用 Google Sheets API，建立一個服務帳戶，把試算表分享給服務帳戶的電郵地址，並把它的金鑰儲存為伺服器端祕密值。之後，你的伺服器就可以使用 spreadsheets.values.get 讀取資料列，並使用 spreadsheets.values.append 新增資料列。如果用戶需要連接他們自己的試算表，就應改用 OAuth；如果試算表完全公開，只讀取的話使用簡單的 API 金鑰便足夠。
本指南涵蓋哪種方法適合、需要用到的呼叫、配額與注意事項，以及給 AI 應用程式生成工具的提示。Google 的細節以 2026 年 9 月 Google 開發者文件為準。
為什麼要連接試算表
常見原因包括：
- **保留團隊的工作流程。**員工繼續在 Sheets 中編輯價目表或時間表，應用程式則負責顯示。
- **在人們本來就會查看的地方收集資料。**新註冊、訂單或表單回覆都會以資料列的形式出現。
- **報表。**把應用程式的資料匯出到試算表，供慣用試算表的人使用。
- **過渡階段。**先從試算表開始，之後再遷移到真正的資料庫。請參閱如何把試算表變成應用程式。
選擇應用程式向 Google 登入的方式
Google 的憑證指南介紹了三種類型：
| 憑證 | 可存取的內容 | 最適合 |
|---|---|---|
| API 金鑰 | 只限公開可用的資料，例如設定為「任何持有連結的人」可查看的檔案 | 讀取公開試算表 |
| 服務帳戶 | 由你的應用程式擁有的資料，或特別分享給服務帳戶電郵的檔案 | 你的應用程式讀寫你自己的試算表 |
| OAuth 用戶端 ID | 用戶同意後，其自己檔案的存取權 | 讓每位用戶連接他們自己的試算表 |
對大多數應用程式來說，服務帳戶是正確的選擇：只有一組由你擁有的憑證，而且只能存取你明確分享給它的試算表。
使用服務帳戶的逐步指南
- 建立或選擇一個 Google Cloud 專案，並啟用 Google Sheets API。
- 建立服務帳戶及其金鑰。金鑰是一個 JSON 檔案，請像對待密碼一樣小心保管。
- 分享試算表給服務帳戶的電郵地址：唯讀選檢視者，寫入則選編輯者。Google 的指南說明這要透過一般的分享畫面完成。
- 把金鑰儲存為祕密值，放在伺服器上，例如
GOOGLE_SERVICE_ACCOUNT_JSON，另外把試算表 ID（試算表網址中的一長串字元）儲存為SHEET_ID。 - 從伺服器呼叫 API，使用 Google 為你所用語言提供的用戶端程式庫。
- 快取讀取結果：如果許多訪客都會看到相同的資料，就可以避免超出配額。
你會用到的呼叫
以下來自 Google 有關讀寫數值的指南：
| 方法 | 作用 |
|---|---|
spreadsheets.values.get | 讀取一個範圍，例如 Leads!A1:E |
spreadsheets.values.batchGet | 在一次要求中讀取多個範圍 |
spreadsheets.values.update | 寫入指定的範圍 |
spreadsheets.values.append | 在表格現有資料之後新增資料列 |
範圍使用 A1 記法。Google 提醒，沒有工作表名稱的範圍（例如 A1:B2）會套用到第一個工作表，因此最好明確寫出分頁名稱，以免有人重新排列分頁時出現意外。
RAW 與 USER_ENTERED
寫入時需要 valueInputOption：
- RAW 會原樣儲存你傳送的內容，作為文字。
=1+2會被儲存為文字=1+2。 - USER_ENTERED 會把輸入視為在 Sheets 中手動輸入的內容：日期會變成日期，
=1+2會變成公式。
如果你寫入的是用戶在應用程式中輸入的文字，請使用 RAW。使用 USER_ENTERED 的話，有人可以提交一個公式，並在同事打開試算表時執行。
配額與錯誤
截至 2026 年 9 月，Google 的 Sheets API 限制頁面列出：
| 限制 | 讀取要求 | 寫入要求 |
|---|---|---|
| 每個專案每分鐘 | 300 | 300 |
| 每位用戶每個專案每分鐘 | 60 | 60 |
只要維持在每分鐘配額之內，就沒有每日上限。超出的話會返回 429: Too many requests，Google 建議使用截斷式指數退避：每次失敗後等待更長的時間，並加入隨機延遲，直至達到上限。單一要求如果超過 180 秒，就會逾時。
實際上，請不要每次載入頁面都呼叫 API。把試算表資料快取一分鐘或更久，用 batchGet 合併讀取，並在可能的情況下合併寫入。
方案與取捨
| 方法 | 優點 | 缺點 |
|---|---|---|
| 以試算表作為即時資料來源 | 員工使用熟悉的工具；無需建立管理畫面 | 配額限制、沒有逐列權限，而且把欄位重新命名就很容易令應用程式出錯 |
| 把試算表同步到資料庫 | 讀取快速可靠；即使 Sheets 停止服務，應用程式仍可運作 | 需要同步工作，並訂立以哪一邊為準的規則 |
| 以資料庫為先，匯出到試算表 | 應用程式擁有資料；試算表只作報表 | 在試算表中的編輯不會回寫 |
| 中間加入自動化工具 | 簡單流程無需寫程式 | 多一項訂閱；較難除錯 |
對於用戶眾多或資料敏感的應用程式，資料庫才是較好的真實來源。請參閱什麼是資料庫。
給 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」分頁新增一列（日期、姓名、電郵、訊息）。如果 Google 返回 429，就以指數退避重試；如果仍然失敗，就把潛在客戶保留在資料庫中，稍後再重試。
常見錯誤
- **忘記把試算表分享給服務帳戶的電郵。**即使金鑰正確，API 仍會返回權限錯誤。
- **金鑰放在前端或儲存庫中。**JSON 金鑰可存取所有分享給它的試算表。請參閱如何保護 API 金鑰。
- 對用戶輸入使用 USER_ENTERED，這會容許公式注入。
- 每次請求都呼叫 API，結果在第一次流量高峰時就超出每分鐘配額。
- **依賴欄位位置。**有人插入一欄後，應用程式就會讀取到錯誤的資料。應讀取標題列並以名稱對應，或鎖定標題。
- 把試算表分享得比需要的範圍更廣。「任何持有連結的人」等於公開。
- **把試算表當作多用戶資料庫。**同時寫入及權限缺失，會導致資料遺失或外洩。
檢查清單
- 已啟用 Sheets API，並已建立服務帳戶
- 試算表已以所需的最低權限分享給服務帳戶電郵
- 金鑰及試算表 ID 已儲存為伺服器端祕密值
- 所有呼叫都從伺服器發出
- 範圍中使用了分頁名稱
- 用戶提供的文字使用 RAW
- 讀取已快取；429 已以退避處理
- Sheets 不可用時，應用程式仍可優雅地降級運作
- 已決定哪一邊是真正的來源
Mythex 中的 Google Sheets
Mythex 有兩種使用 Sheets 的方式。連接器會把你的 Google 帳戶連接到 Mythex，讓 agent 在你建構時使用，例如讀取試算表來建立儀表板。文件說明該憑證會保留在 Mythex 的連接服務中，不會進入你的程式碼（請參閱連接器，並核准 Google 要求的每一項權限）。至於已發布的應用程式要自行讀寫試算表，最可靠的方法就是本指南所述的做法：把服務帳戶金鑰儲存為專案祕密值，並由伺服器呼叫 Sheets API，請參閱整合任何 API。如果你已超出試算表的負荷，可要求 agent 把資料遷移到專案資料庫，並在其上建立儀表板。
常見問題
我的應用程式如何讀取私人的 Google 試算表？
常見做法是使用 Google Cloud 服務帳戶：啟用 Sheets API，建立服務帳戶及其金鑰，然後把試算表以檢視者或編輯者身分分享給服務帳戶的電郵地址。你的伺服器會使用以祕密值儲存的金鑰來呼叫 Sheets API。
我可以用 Google API 金鑰存取試算表嗎？
只適用於公開資料。Google 的憑證指南指出，API 金鑰只用於匿名存取公開可用的資料，例如任何持有連結的人都可查看的檔案。私人試算表則需要服務帳戶或 OAuth。
Google Sheets API 有什麼限制？
截至 2026 年 9 月，Google 列明每個專案每分鐘可進行 300 次讀取及 300 次寫入要求，並且每位用戶每個專案每分鐘可進行 60 次讀取及 60 次寫入，沒有每日上限。超出限制會返回 429 錯誤；Google 建議採用截斷式指數退避。
我應該把 Google Sheets 當作應用程式的資料庫嗎？
對於小型、流量低，而且人們也會直接在試算表中編輯資料的應用程式，它是可行的。但如果用戶眾多、寫入頻繁、記錄之間有關聯，或每位用戶的權限各有不同，真正的資料庫會更可靠。你仍然可以把資料匯出到試算表。