Google Sheets
概覽
Google Sheets 整合會在每次 API 呼叫時自動向您 Google Drive 的試算表追加一列。每個月會自動建立新的試算表檔案,新增欄位時表頭也會自動擴充。
無須撰寫程式碼,就能把銷售、訂單、諮詢等資料集中到一個試算表中查看,這是最便捷的方式。試算表儲存在您自己的 Drive 中,可以照常使用 Google Sheets 的共用、篩選、圖表與樞紐分析表功能。
僅限所有者使用。協作者看不到 Google Sheets 卡片。
進入路徑
- 頂部選單 APIs → 點擊目標端點名稱進入端點詳情
- 在頁面中的 Google Sheets 卡片開始
Free 方案也可使用,放心試用。
Drive 中會建立什麼
啟用整合後,系統會在您 Google 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
- 資料夾名稱: 端點名稱(特殊字元會自動整理)
- 檔案名稱:
{環境}_{端點}_{YYYY-MM}(按 UTC 月份) - 新月份開始時,下一次呼叫時會自動建立新檔案
權限範圍
3Min API 僅向 Google 申請 drive.file 一個權限。該權限只能存取 3Min API 自己建立的檔案,範圍非常有限。您 Drive 中的其他資料(其他試算表、文件、共用資料夾)都無法存取,請放心。
試算表欄位結構
每張試算表的第一列(表頭)由兩類欄位組成。
Meta 欄位(關於請求的系統資訊)
| 欄位 | 含義 |
|---|---|
record_id |
標識單次呼叫的唯一 ID(與 3Min API 日誌、封存關聯) |
created_at |
呼叫到達的時間(UTC) |
config_version |
呼叫時使用的端點結構版本 |
operation |
create / read / update / delete |
status |
處理結果 |
collaboration_key |
使用了哪個協作金鑰 |
Payload 欄位(請求中攜帶的業務資料)
Payload 中的每個欄位都會以 payload_ 前綴新增為單獨的欄位。例如: payload_email、payload_amount、payload_address_city。前綴讓 Payload 資料與 Meta 欄位清楚分離。
新欄位到達時,試算表右側會自動新增欄位。已有列的新欄位保持空白。
整合方法
步驟 1 — 從 Google Sheets 卡片開始整合
在端點詳情頁的 Google Sheets 卡片中點擊 `開始整合` 按鈕。
步驟 2 — Google 同意頁面
進入 Google 頁面後,確認 3Min API 申請的權限只有 drive.file 一個,然後點擊同意。視帳戶而定,可能會出現按權限分別勾選的核取方塊,這種情況下需要 保持所有核取方塊都勾選 再同意,否則試算表記錄無法正常運行。
步驟 3 — 整合完成,確認首列記錄
整合完成後,卡片會顯示 已連線 標籤和試算表檔案名稱。
`開啟試算表`— 在新分頁中開啟 Drive 中的試算表檔案`傳送測試列`— 向試算表記錄一列範例,確認是否正常運作。無須開發工具或程式碼即可立即查看結果,是最快的驗證方式`中斷連線`— 停止該端點的自動記錄(Drive 中的現有檔案保留)
之後每次該端點收到 API 呼叫,都會自動追加到試算表的最後一列。
值得了解的事項
處理速度
- 試算表記錄會 依序處理。API 呼叫本身會立即回應,但列通常在 幾秒內 出現在試算表中。
- 呼叫突然集中時會進入佇列依序處理,可能會比平時晚一些反映到試算表中。
- 出現暫時性配額超出(429)或臨時故障時,3Min API 會 自動重試約 5 分鐘。重試期間試算表中的列順序可能與呼叫順序略有差異;若需要嚴格的順序,請按
created_at欄位排序檢視。
失敗時資料依然安全
自動重試後試算表記錄最終仍然失敗時, 只有試算表裡的這一列缺失,原始資料會完整保留在日誌和封存中。試算表記錄失敗會透過您在系統通知中註冊的 Discord / Slack / Telegram 管道傳送通知(不會傳送電子郵件)。
需要重新授權的情況
以下情況下試算表記錄會停止,並傳送 重新授權通知(google_reauth_required)。
- 您在 Google 帳戶設定中解除了
3Min API應用程式的連線 - Google 讓 token 過期(例如長期未使用)
- 權限勾選被取消,導致
drive.file缺失
收到通知後,請在 外部整合 設定中重新連線。重新連線後會繼續使用現有的試算表檔案。
不同環境獨立運作
沙箱環境和正式環境的 Google Sheets 整合 完全獨立。同一個端點也可以按環境分頁分別啟用或解除整合,試算表檔案也按環境分別建立。
部署到正式環境後,沙箱的 Google Sheets 整合不會自動跟隨。 請在正式環境分頁的 Google Sheets 卡片中再次點擊 `開始整合`。
中斷整合
有兩種方式。
單一端點中斷
在端點詳情的 Google Sheets 卡片中點擊 `中斷連線`。僅停止該端點的試算表自動記錄,其他端點的 Google Sheets 整合不受影響。
全部中斷(直接中斷 Google 帳戶連線)
頂部選單 設定 → 外部整合 → Google Drive & Sheets → 頁面底部 危險操作 中的 `中斷所有連線`。所有端點的 Google Sheets 整合會一次性停止,3Min API 的 OAuth 認證也會被撤銷。再次使用需要從頭開始連線。
中斷後的資料
兩種方式都會 保留 Drive 中既有的試算表檔案。如不需要,請直接在 Drive 中刪除。下次重新整合時會自動建立新檔案,舊檔案不會自動刪除。
常見疑問
部署到正式環境後試算表中沒有記錄
沙箱的 Google Sheets 整合不會自動遷移到正式環境。請在端點詳情中切換到 正式環境分頁,然後在 Google Sheets 卡片中單獨點擊
`開始整合`。系統會在已有的沙箱試算表之外另外建立production_*檔案。整合後卻找不到試算表檔案
請先查看 Drive 最上層的
3Min API資料夾。當月的試算表檔案要等第一次呼叫到達後才會建立。可透過`傳送測試列`立即建立。如果仍然看不到,請在外部整合設定中確認是否顯示權限不足的提示(黃色標籤)。表頭突然多出新欄位
端點新增欄位時,試算表表頭會自動擴充(已有列的新欄位保持空白),這是預期行為。請不要手動刪除或重新排列表頭,否則下一列寫入時欄位對應可能錯位。
可以移動或重新命名試算表檔案嗎?
可以,很安全。3Min API 透過檔案 ID 進行追蹤,即使把檔案移到其他資料夾或重新命名,也會繼續向同一個檔案追加列。但如果移到資源回收筒或永久刪除,下一次呼叫時會自動建立新檔案,被刪除的檔案無法復原。
整個
3Min API資料夾都被刪了下一次呼叫到達時,會自動建立新資料夾和新試算表。但已刪除的舊試算表無法復原,因此建議提前從封存下載需要保留的資料。
試算表記錄失敗的通知太頻繁
試算表記錄失敗通知是在 端點詳情 > 通知 中註冊 Discord/Slack/Telegram 頻道後收到的訊息。如果該通知比平時更頻繁,請確認以下情況。
3Min API 會一直自動重試,必要時也會向 Google 申請提高配額來擴大處理量。如果通知仍然頻繁,意味著呼叫量超過了 Google 設定的試算表寫入上限(通常約為每使用者每分鐘 60 次)。該上限由 Google 政策決定,而非 3Min API,因此無法按個別使用者進一步放寬。
其實這是 業務發展勢頭良好的好信號。Google Sheets 適合輕量記錄和快速視覺化,但本身並不是為每分鐘數十次以上持續流量而設計的。是時候考慮下一步了。