Google Drive API 小白指南 · AI Agent 踩坑筆記

☁️

基礎設施

Google Cloud Console

Google 的「後台管理中心」。你在這裡管理所有 Google 雲端服務：開啟 API、建立帳號、設定權限。

網址：console.cloud.google.com

你家的電箱總開關，所有電路都從這裡控制。

📁

組織單位

專案 Project

Cloud Console 裡的「容器」。所有 API、憑證、設定都屬於某個專案。你可以建多個專案，互不干擾。

像是不同的工程資料夾，分開管理。

公司裡的「部門」，財務部和工程部各自有自己的工具和權限。

🔌

功能開關

API（應用程式介面）

API 是讓外部程式「溝通」Google 服務的橋樑。

Google 的每個服務（Drive、Gmail、Calendar…）都有自己的 API。不開啟 = 程式無法存取。

插座。插座存在，但沒裝插座（開啟 API），電器就沒辦法用電。

🪪

身份識別

憑證 Credentials

讓 Google 知道「是誰」在呼叫 API 的身份證。分兩種：
• OAuth 客户端 ID（OAuth 2.0 Client ID）：代表「某個應用程式」，需要用戶登入授權
• 服务帐号（Service Account）：代表「機器人帳號」，自動化用，不需人工登入

門禁卡。沒有卡，警衛（Google）不讓你進去。

🛡️

用戶授權機制

OAuth 2.0

業界標準的「授權協議」。流程是：
1. 你的程式請求用戶登入
2. Google 顯示「這個應用要存取你的 Drive，同意嗎？」
3. 用戶點同意 → Google 發一張「通行令牌 Token」
4. 程式用 Token 存取 Drive，不需要知道你的密碼

飯店 Key Card：前台（Google）確認你的身份後，給你一張只能開你房間的卡。

📋

用戶看到的頁面

OAuth 同意屏幕
官方中文：OAuth 同意屏幕
英文：OAuth consent screen

用戶授權時看到的那個頁面：「XXX 應用要求存取你的 Google Drive，是否允許？」

你需要設定：應用名稱、聯絡信箱、要求哪些權限（Scopes）。

銀行的「授權確認簡訊」，告訴你是哪個 App 在請求操作，讓你決定是否批准。

開啟 Google Drive API

告訴 Google：「我這個專案要用 Drive 功能」。
沒有這步，後面所有憑證都沒用 —— 即使有 Token，Google 也會拒絕請求。

📍 Cloud Console → API 和服务 APIs & Services → 库 Library → 搜尋 Google Drive API → 启用 Enable

設定 OAuth 同意頁面

設定用戶授權時看到的畫面。必須填應用名稱和聯絡信箱。
External（外部）= 任何 Google 帳號都可以授權使用
Internal（內部）= 只限同一個 Google Workspace 的帳號

📍 API 和服务 APIs & Services → OAuth 同意屏幕 OAuth consent screen → 外部 External → 填寫資料 → 儲存並繼續

建立 OAuth Client ID（憑證）

建立一個「代表你的應用程式」的身份 ID。
類型選 Desktop app（桌面應用），因為 Claude Code 是在本機電腦上跑的。

📍 API 和服务 APIs & Services → 凭据 Credentials → ＋创建凭据 + CREATE CREDENTIALS → OAuth 客户端 ID OAuth client ID → 桌面应用 Desktop app

下載 credentials.json

建立後 Google 給你一個 JSON 檔案，裡面有 client_id 和 client_secret。
這就是你的應用程式「通行卡」，要妥善保管，不要放到公開的地方（GitHub 等）。

📍 彈窗點 → 下载 JSON DOWNLOAD JSON → 存到本機安全位置（如 D:/tmp/）

執行 OAuth 授權（一次性）

程式用 credentials.json 打開瀏覽器，引導你登入 Google。
你點「允許」後，Google 回傳一個 Token（存在本機），之後程式每次都用這個 Token，不需要再重複登入。

📍 終端機執行 auth 指令 → 瀏覽器登入 → 點允許 → Token 儲存完成

MCP Server 接入 Claude Code

把 Google Drive MCP Server 加進 Claude Code 設定，之後 Claude 就能直接操作你的 Google Drive：
建立分享連結、設定權限、搜尋文件、上傳下載⋯⋯

📍 ~/.claude/settings.json → mcpServers 區塊加入設定 → 重啟 Claude Code

方式	做法	問題
❌ 直接給密碼	把 Google 密碼告訴程式	程式可以做任何事（刪帳號、改密碼），安全風險極高
❌ API Key	生成一個 Key，程式用這個 Key	Google 個人帳號的 Drive 不支援純 API Key，必須有用戶授權
✅ OAuth 2.0	你授權 → Google 給 Token → 程式用 Token	Token 只有特定權限（如只能讀 Drive），你可以隨時撤銷，密碼永遠不會洩漏給程式

credentials.json 是 API Key 嗎？

不完全是。它是「OAuth Client 的身份資料」，包含 client_id 和 client_secret。有了它，程式才能「啟動授權流程」，但還需要用戶登入才能拿到真正的 Token（存取令牌）。

為什麼會出現「尚未完成 Google 驗證」的錯誤？

當 OAuth App 處於「測試模式」，只有被開發者加入白名單的 Gmail 才能授權。解決辦法：到 Consent Screen → Test users → 加入自己的 Gmail，或把 App 狀態改為「正式發佈（In production）」。

Token 會過期嗎？

Access Token 有效期約 1 小時，但同時會有一個 Refresh Token。程式會自動用 Refresh Token 換新的 Access Token，你通常不需要重新登入。

我需要付費給 Google 嗎？

Google Drive API 個人使用完全免費。Google Cloud Console 提供充足的免費配額，日常操作幾乎不會超出。

credentials.json 可以公開嗎？

不可以！裡面的 client_secret 一旦外洩，別人可以假冒你的應用程式進行 OAuth 授權。要放在本機安全路徑，不要上傳 GitHub。

⚠️ 為什麼這個文件很危險？

credentials.json 裡有兩個關鍵資料：
• client_id：公開的應用程式識別碼（外洩影響較小）
• client_secret：這個絕對不能外洩！別人拿到後可假冒你的應用，騙取用戶授權

你電腦裡有多個不同 AI 模型的 credentials.json，如果其中一個不小心上傳到 GitHub 或被惡意軟件掃到，後果很嚴重。

保管方式	做法	優點	缺點	適合誰
❌ 隨意放磁碟	直接存在 D:/tmp/ 或桌面	方便	容易誤上傳 GitHub、被惡意程式掃到	不建議任何人
🟡 本機隱藏文件夾	統一放 `C:/secrets/`，從不碰 Git	簡單、離線可用	電腦壞掉就沒了、無加密	個人小項目
🟡 環境變量	把內容存入系統環境變量，程式讀取	不是文件、不會被誤提交	重裝電腦要重設、明文存在系統裡	開發者常用
✅ GCP Secret Manager	把 JSON 內容上傳到 Google 雲端保險箱，程式用指令取出	加密儲存、有稽核日誌、版本管理、多台電腦共用	需要網路、需要 gcloud CLI、有學習成本	已用 GCP 的用戶 ✓
✅ 1Password / Bitwarden	把 JSON 內容存為「安全筆記」	加密、跨裝置同步、有 CLI 可自動取出	需要訂閱費用（1Password）	已有密碼管理器的用戶

SM1

把 credentials.json 上傳到 Secret Manager

只需一條指令，把 JSON 文件內容存入 Google 的加密保險箱。
之後本機的 credentials.json 可以刪掉或放到更安全的地方。

gcloud secrets create gdrive-credentials --project=YOUR_PROJECT
gcloud secrets versions add gdrive-credentials --data-file=credentials.json

SM2

程式需要時，即時取出並使用

程式執行前，先從 Secret Manager 取出 JSON 內容，寫成臨時文件，用完即刪。
這樣 credentials.json 永遠不會長期留在磁碟上。

# 取出並存成臨時文件
gcloud secrets versions access latest --secret=gdrive-credentials > /tmp/creds.json
# 用完後刪除
del /tmp/creds.json

SM3

管理多個 AI 模型的憑證

你有多個 AI 模型的 credentials.json，全部存進 Secret Manager，用名稱區分。
再也不需要擔心哪個文件放哪裡了。

gdrive-credentials ← Google Drive API
gmail-credentials ← Gmail API
openai-credentials ← OpenAI
anthropic-credentials ← Anthropic / Claude
gemini-credentials ← Google Gemini

📋 推薦做法：三步整理你的憑證

第一步 統一命名，不要全叫 credentials.json
改成有意義的名稱：

        gdrive_oauth_whole-cloth.json

        openai_key_nvda-project.json

        anthropic_key_personal.json

第二步 全部移到一個統一的隱藏文件夾

        C:\secrets\          ← 只有你知道這個路徑

          gdrive_oauth_whole-cloth.json

          openai_key_nvda.json

          …

這個文件夾永遠不要放進任何 Git 項目裡

第三步 重要的上傳到 GCP Secret Manager 備份
即使電腦壞掉、重裝系統，雲端還有一份加密備份，隨時可以取回。

情境	風險	後果
放在 D:/tmp/ 或桌面	🔴 高	被惡意程式掃到、誤上傳雲端同步
放在 Git 項目文件夾裡	🔴 極高	一旦 push 到 GitHub，全球都能看到
放在 C:/secrets/（不進 Git）	🟡 中	電腦被入侵可能洩漏，但日常安全
存在 GCP Secret Manager	🟢 低	Google 加密保管，有稽核日誌，可隨時撤銷
存在 1Password 安全筆記	🟢 低	加密同步，主密碼保護

credentials.json 是 API Key 嗎？

為什麼會出現「尚未完成 Google 驗證」的錯誤？

當 OAuth App 處於「測試模式」，只有被開發者加入白名單的 Gmail 才能授權。解決辦法：到 Consent Screen → 测试用户 Test users → 加入自己的 Gmail，或把 App 狀態改為「正式發佈（In production）」。

Token 會過期嗎？

Access Token 有效期約 1 小時，但同時會有一個 Refresh Token。程式會自動用 Refresh Token 換新的 Access Token，你通常不需要重新登入。

我需要付費給 Google 嗎？

Google Drive API 個人使用完全免費。GCP Secret Manager 每月 6 個 Secret 版本免費，日常使用幾乎不會超出。

credentials.json 可以公開嗎？

不可以！裡面的 client_secret 一旦外洩，別人可以假冒你的應用程式進行 OAuth 授權。要放在本機安全路徑，不要上傳 GitHub。

如果 client_secret 洩漏了怎麼辦？

立刻到 Cloud Console → 凭据（Credentials）→ 找到那個 OAuth Client ID → 點「重置密鑰」（Reset Secret）。舊的 client_secret 立即失效，生成新的，再重新下載 credentials.json。

🔑 Google Drive API 到底是什麼？