8.3 KiB
8.3 KiB
Google Drive API 設定指南
本指南說明如何設定 Google Drive API，讓系統能夠自動從 Google Drive 下載、匯入並刪除當日業績 Excel 檔案。
功能說明
系統會：
- 每 30 分鐘自動檢查 Google Drive 指定資料夾
- 自動下載 Excel 檔案到本地
- 自動匯入資料到資料庫
- 自動刪除 Google Drive 上的原始檔案
- 追蹤進度並提供網頁介面查看匯入狀態
步驟 1：建立 Google Cloud 專案
1.1 前往 Google Cloud Console
1.2 建立新專案
- 點擊上方的專案選擇器
- 點擊「新增專案」
- 輸入專案名稱（例如：
momo-auto-import） - 點擊「建立」
步驟 2：啟用 Google Drive API
2.1 啟用 API
- 在 Google Cloud Console 中，前往「API 和服務」→「程式庫」
- 搜尋「Google Drive API」
- 點擊「Google Drive API」
- 點擊「啟用」
步驟 3：建立 OAuth 2.0 憑證
3.1 建立 OAuth 同意畫面
- 前往「API 和服務」→「OAuth 同意畫面」
- 選擇「外部」（如果只有自己使用，選擇「內部」需要 Google Workspace）
- 點擊「建立」
- 填寫必要資訊：
- 應用程式名稱：
Momo Pro System - 使用者支援電子郵件：您的 Gmail 地址
- 開發人員聯絡資訊：您的 Gmail 地址
- 應用程式名稱：
- 點擊「儲存並繼續」
- 範圍（Scopes）：點擊「新增或移除範圍」
- 搜尋並勾選：
https://www.googleapis.com/auth/drive（完整 Drive 存取權限） - 點擊「更新」
- 搜尋並勾選：
- 點擊「儲存並繼續」
- 測試使用者：新增您的 Gmail 地址
- 點擊「儲存並繼續」
3.2 建立 OAuth 2.0 用戶端 ID
- 前往「API 和服務」→「憑證」
- 點擊「建立憑證」→「OAuth 用戶端 ID」
- 應用程式類型選擇：桌面應用程式
- 名稱輸入：
Momo Desktop Client - 點擊「建立」
- 會顯示「用戶端 ID」和「用戶端密鑰」
- 點擊「下載 JSON」
3.3 放置憑證檔案
- 將下載的 JSON 檔案重新命名為：
google_credentials.json - 放置到專案的
config/目錄中：/Users/ogt/momo_pro_system/config/google_credentials.json
步驟 4：首次認證
4.1 執行認證流程
首次使用時需要進行認證：
cd /Users/ogt/momo_pro_system
# 執行認證腳本
python3 -c "
from services.google_drive_service import drive_service
drive_service.authenticate()
"
4.2 完成授權
- 瀏覽器會自動開啟 Google 授權頁面
- 選擇您的 Google 帳號
- 系統會顯示：「Google 尚未驗證此應用程式」
- 點擊「繼續」（因為這是您自己的應用程式）
- 點擊「允許」授予 Google Drive 存取權限
- 看到「授權流程已完成」即表示成功
4.3 Token 檔案
授權完成後，系統會自動建立 config/google_token.pickle，此檔案包含您的存取權杖，下次使用時不需重新授權。
安全提示：此檔案包含敏感資訊，請勿分享或上傳到公開儲存庫。
步驟 5：設定 Google Drive 資料夾
5.1 在 Google Drive 建立資料夾結構
建議的資料夾結構：
我的雲端硬碟/
└── 業績報表/
└── 當日業績/
└── 即時業績_當日_20260113.xlsx
5.2 在系統中配置路徑
- 開啟瀏覽器，前往：http://localhost/auto_import
- 在「匯入配置」區域設定：
- Google Drive 資料夾路徑：
業績報表/當日業績 - 檔案名稱模式：
即時業績_當日（選填，用於過濾檔案）
- Google Drive 資料夾路徑：
- 點擊「儲存配置」
- 點擊「測試連接」確認連接正常
- 點擊「列出檔案」查看該資料夾中的檔案
步驟 6：測試自動匯入
6.1 上傳測試檔案
- 將當日業績 Excel 檔案上傳到 Google Drive 的指定資料夾
- 檔案名稱範例：
即時業績_當日_20260113.xlsx
6.2 手動測試
- 在自動匯入頁面點擊「立即匯入」
- 觀察「匯入任務歷史」區域，應該會看到新的任務記錄
- 任務狀態會從「等待中」→「下載中」→「匯入中」→「已完成」
- 完成後，Google Drive 上的檔案會被自動刪除
6.3 驗證匯入結果
# 查詢匯入的資料
python3 -c "
from services.import_service import import_service
jobs = import_service.get_recent_jobs(limit=1)
for job in jobs:
print(f'任務 ID: {job[\"id\"]}')
print(f'狀態: {job[\"status\"]}')
print(f'檔案: {job[\"drive_file_name\"]}')
print(f'成功: {job[\"success_rows\"]} 筆')
"
步驟 7：自動排程
系統已自動設定每 30 分鐘檢查一次 Google Drive：
- 排程任務會在背景自動執行
- 無需手動觸發
- 可在「匯入任務歷史」查看執行記錄
- 每次檢查到新檔案就會自動匯入
常見問題
Q1: 認證失敗，顯示「找不到認證檔案」
A: 確認 config/google_credentials.json 檔案存在且路徑正確。
Q2: 授權時顯示「應用程式未經驗證」
A: 這是正常的，因為這是您自己的應用程式。點擊「繼續」即可。
Q3: 找不到 Google Drive 資料夾
A: 確認：
- 資料夾路徑正確（區分大小寫）
- 資料夾確實存在於「我的雲端硬碟」中
- 使用的 Google 帳號有該資料夾的存取權限
Q4: 檔案沒有被自動刪除
A: 確認：
- 匯入任務狀態為「已完成」（不是「失敗」）
- 檢查日誌檔案：
logs/system.log
Q5: 如何重新授權？
A: 刪除 config/google_token.pickle 檔案，然後重新執行步驟 4。
Q6: 可以使用 Service Account 嗎？
A: 可以，但需要修改程式碼。Service Account 適合在伺服器上無人值守運行，但需要手動分享 Drive 資料夾給 Service Account 的電子郵件地址。
安全建議
-
不要分享憑證檔案
google_credentials.jsongoogle_token.pickle- 這些檔案已加入
.gitignore
-
定期檢查授權
- 前往 Google 帳戶安全性
- 檢查「Momo Pro System」的授權狀態
-
限制 API 存取範圍
- 目前使用完整 Drive 存取權限
- 如需更嚴格控制，可修改為
drive.filescope（僅存取應用程式建立的檔案）
-
備份重要資料
- 在刪除 Google Drive 檔案前，系統會先匯入到本地資料庫
- 建議定期備份資料庫
進階設定
修改檢查頻率
編輯 app.py，找到：
schedule.every(30).minutes.do(run_auto_import_task)
修改為您想要的頻率：
- 每 15 分鐘：
schedule.every(15).minutes.do(...) - 每小時：
schedule.every(1).hours.do(...) - 每天早上 8 點：
schedule.every().day.at("08:00").do(...)
保留 Google Drive 檔案
如果不想自動刪除 Google Drive 檔案，修改 services/import_service.py 中的 auto_import_from_drive 方法，註解掉刪除部分：
# if drive_service.delete_file(file_id):
# logger.info(f"已刪除 Google Drive 檔案: {file_name}")
監控和日誌
查看即時日誌
tail -f logs/system.log | grep AutoImport
查看匯入統計
前往網頁介面：http://localhost/auto_import
查詢排程統計
cat data/scheduler_stats.json | grep auto_import_task
故障排除
檢查服務狀態
python3 -c "
from services.google_drive_service import drive_service
from services.import_service import import_service
# 測試 Google Drive 連接
if drive_service.authenticate():
print('✅ Google Drive 連接正常')
else:
print('❌ Google Drive 連接失敗')
# 查詢最近的任務
jobs = import_service.get_recent_jobs(limit=5)
print(f'\\n📋 最近 {len(jobs)} 個任務:')
for job in jobs:
print(f' - 任務 {job[\"id\"]}: {job[\"status\"]} ({job[\"progress_percent\"]}%)')
"
參考資料
完成！ 🎉
您的 Google Drive 自動匯入功能已設定完成，系統會每 30 分鐘自動檢查並匯入新的業績檔案。