把 API 資料自動寫入 Google Sheets 的最短路徑

大家好,我是負責 3Min API 開發的 yeonghyeon。

這篇文章的起點是運營者們反覆提出的同一個請求:"訂單進來後,直接一行一行地堆進 Google 試算表就好了。"這樣的請求出現過不止一兩次。把額外的自動化工具串起來其實早就有方案,但多接一個工具本身就是負擔。所以我們 把 Google Drive 與試算表整合直接做進了 3Min API。 Google 帳號連接一次就完成了,之後每次 API 呼叫都會自動在你自己的試算表裡新增一行。

這篇文章是寫給第一次接觸這項功能的朋友的導覽。我們會依序梳理 為什麼需要這項功能、不在中間夾自動化工具的方式有什麼不同、以及 今天 5 分鐘內能做到哪一步。不需要任何前置知識。

"就讓資料堆進試算表裡"這個請求背後真正的問題

想把資料匯集到試算表裡的理由幾乎都一樣。一眼看清營收、親手做篩選和排序、原樣交給會計或行銷同事。試算表最貼合這種用途,也沒必要再搬到別處。換句話說,試算表本身就是終點 — 中間所有步驟都是多餘。

但是要把"透過 API 收到的資料"和"我自己的試算表"連起來,實際上沒那麼容易。常見路徑是這樣的:

1. 先用 3Min API 之類的服務收資料,
2. 再註冊 Zapier、Make、n8n 之類的自動化工具,
3. 用 Webhook 把資料流向那個工具,
4. 那個工具再往 Google Sheets 追加一行。

順利的時候沒問題。但從營運角度看會帶來三種負擔。

• 工具成本 — 每個自動化工具都有月度訂閱費,呼叫量增多還得升級到更貴的方案。
• 學習成本 — 要連節點、做觸發器、再設一次認證。僅僅是"追加一行訂單"而已,步驟卻多到誇張。
• 遺失風險 — 自動化工具維護中或超過呼叫上限時,這段時間進來的資料可能會被悄悄丟棄。試算表裡少了一行,也無從查到丟的是哪一筆。

最後這一條尤其關鍵。在生意裡丟資料不是普通的不便,而是 帳本上多了一個洞。把生意建立在"自動化工具一直健康"這個假設上是站不住的。

所以我們選了直接的答案 — 把試算表整合放進產品裡

解決方向很直白:不讓別的工具卡在 3Min API 和 Google Drive 之間。Google 帳號連接一次,在同意頁授權一個權限即可。之後每次 API 呼叫都會自動在你自己 Drive 裡的試算表中新增一行。不需要自動化工具,不需要額外訂閱,不需要觸發器設定。

外部呼叫 → 先在 3Min API 中安全保存 → 自動寫入 Google Sheets。中間沒有自動化工具。

這樣做之後會有什麼變化:

• 一個工具搞定。 所有設定都在 3Min API 內部完成。
• 資料始終先安全保存。 試算表寫入新行之前,呼叫本身就已經記錄到 3Min API 的日誌和封存。試算表寫入只是錦上添花,不是命脈。
• 失敗也不丟原始資料。 一時超過配額時會自動重試。即便重試到底也沒成功,也只是試算表少一行,資料本身不會消失。
• 權限盡量收窄。 向 Google 請求的權限只有 drive.file 一項。3Min API 只能存取自己建立的試算表,你 Drive 裡的其他資料一律碰不到。

一句話總結:如果試算表就是終點,通向它的路徑越短越好。

連接後 Drive 裡會出現什麼

實際連接後 Drive 裡會形成什麼樣的結構,直接看一眼最快。Drive 頂層會自動產生一個名為 3Min API 的資料夾,內部依下面的方式整理:

3Min API/
├── user-signup/                              ← 依端點劃分的資料夾
│   ├── sandbox_user-signup_2026-04           ← 依月份的試算表 (沙箱)
│   ├── sandbox_user-signup_2026-05
│   └── production_user-signup_2026-05        ← 依月份的試算表 (正式)
└── order-create/
    └── production_order-create_2026-05

規則很簡單:每個端點一個資料夾,資料夾下依環境(沙箱/正式)和月份各一張試算表。新月份開始時,首次呼叫會自動新建試算表,所以也不必擔心一張試算表過載。把試算表搬到別的資料夾或者改名也安全。3Min API 透過檔案 ID 追蹤試算表,即使位置和名稱變了,也會繼續往同一個檔案裡加入新行。

每張試算表的第一行,也就是表頭,由兩類欄位組成:

• 後設資料欄位 — record_id、created_at、config_version、operation、status、collaboration_key。系統自動填入。用來追蹤每一行對應的是哪一次呼叫。
• 承載資料欄位 — 你定義的欄位(電子郵件、金額、地址……)會帶著 payload_ 前綴,一個欄位一欄展開。前綴是有意為之,避免業務資料與後設資料混在一起。

之後給端點加新欄位時,表頭會自動向右擴展。舊行裡新欄的位置保持空白,從下一次呼叫開始才會被填入值。只要不在試算表裡直接刪表頭或調換順序,對應關係會一直自然維持。

沙箱和正式環境彼此獨立

3Min API 的所有端點都把 沙箱(開發/測試用)和 正式環境(實際服務用)完全分開。Google Sheets 整合同樣遵循這一分離。同一個端點,可以依環境分頁分別開關整合,試算表檔案也依環境分別產生。

因此你會經常遇到一項保護措施。即使沙箱裡把試算表整合都連好了,把端點部署到正式環境之後,正式環境的試算表整合不會自動跟上。需要在正式環境分頁的 Google Sheets 卡片上再次點選 開始整合,正式記錄才會啟動。我們故意多問一遍。把測試資料和真實營收資料混在同一張試算表裡,會是相當棘手的事故。

5 分鐘體驗 — 一直到第一次試算表記錄

說理論不如直接看一次效果來得快。依下面的順序進行就行。一行程式碼也不必寫,工具也只需要 3Min API 一個。

1. 註冊帳號並建立第一個端點

註冊後,系統會自動引導一個簡短的 入門流程,帶你建立第一個端點。Free 方案也能用 Google Sheets 整合。請依你正在營運的業務,先做一個端點試試。什麼都行。一開始建議選 訂單接收、諮詢登記、預約申請 這種"一件事一行"的簡單形態。兩三個欄位就足夠。完整步驟整理在 端點建立手冊 裡。

如果想先把"端點是什麼"這件事再放慢一點理解,推薦先讀 API 是什麼? 寫給非開發者的入門指南。只要把握"在固定地址、按固定形態收發訊息的窗口"這種感覺,後面的內容自然能跟上。

2. 在 Google Sheets 卡片上開始整合

打開端點詳情頁,會看到一張 Google Sheets 卡片。點選卡片裡的 開始整合 按鈕,會跳轉到 Google 的同意頁。

同意頁上 3Min API 請求的權限只有 drive.file 一項。這是只能存取自己建立的試算表的窄權限。如果 Google 一併顯示了多個權限的勾選框,請 保持全部勾選 後再同意,否則試算表記錄無法正常運作。

3. 用測試發送做確認

整合完成後,卡片上會顯示 已連接 標示和試算表檔名。這時點一次 測試發送 按鈕。一行範例資料就會寫入試算表,你可以親眼看到一次實際呼叫是怎樣落進試算表的。不必任何開發工具,這是看到結果最快的方法。

從現在起,這個端點每收到一次 API 呼叫,試算表末尾就會自動追加一行。到這裡就全部完成。

需要知道的幾件事

Google Sheets 本身有寫入配額

試算表寫入受 Google 依使用者設定的寫入配額限制,而不是 3Min API 設定的配額。通常是每分鐘約 60 次,同一個 Google 帳號下連接的所有端點共用這份配額。整個試算表自動記錄功能都是在這個配額上運行的。

日常流量下基本感受不到這個上限。但隨著時間推移,如果呼叫量穩步成長、開始頻繁觸及上限,這其實是 生意勢頭不錯的好信號。由於 Google 政策很難依使用者單獨放寬配額,這時建議把試算表作為彙總/儀表板用途,原始資料透過 日誌 與 封存 按日或按週下載保存,或者 開始考慮引入自有資料庫。即使走到這一步,3Min API 仍可作為入口閘道使用,搬遷負擔很小。

可以透過系統通知掌握狀態

為了在試算表寫入失敗或需要重新認證時立即察覺,可以為每個端點登記 Discord/Slack/Telegram 通知頻道。在 端點詳情 的系統通知設定裡把頻道連接好,試算表寫入失敗 與 需要 Google 重新認證 這兩類事件就會直接推送到該頻道。這是不必每次打開儀表板也能確認試算表是否在正常填入的最輕量方法。

這段時間裡 3Min API 自動處理了什麼

會觸發通知的事件其實並不常發生。這中間的空隙,3Min API 用下面三種方式補上了:

• 自動重試 — 一時的配額超出(429)或臨時故障會在大約 5 分鐘內自動重試,把多數情況吸收掉。我們也在持續向 Google 申請提高配額,以擴大處理量。
• 原始資料始終安全 — 即使自動重試到最後仍然失敗,也只是試算表裡少一行,原始呼叫本身仍保存在 日誌 與 封存 中。試算表寫入失敗不等於資料遺失。
• 按呼叫順序逐行處理 — 試算表記錄按呼叫順序逐行處理,通常 幾秒內 就會出現在試算表裡。在呼叫集中時段,行可能比平時晚一點反映,排序也可能與呼叫順序略有出入。需要嚴格的順序時,請按 created_at 欄位排序檢視。

今天能做的一件事

不必一上來就組裝宏大的自動化方案。我們建議的,只有這一件事。

建立一個端點 → 開啟 Google Sheets 整合 → 測試發送一次。

走到這一步,你的 Drive 裡就會出現一條自動堆疊業務資料的小型管線。在它之上,可以再加新欄位、把 API 金鑰交給合作夥伴、用營收欄畫圖表。比起一次設計好所有自動化,我們更建議先 用最短的路徑,看一次"一行資料落進試算表" 這一幕。

更詳細的設定和異常處理整理在 Google Sheets 整合手冊 裡。如果想多了解一下我們為什麼做這件事,我們為什麼做了 3Min API 寫下了背後的故事。