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