Google OAuth 全家桶授權指南

前言：為什麼需要 Google OAuth

什麼是 OAuth？

如果你跟我一樣，想讓自己的程式自動上傳 YouTube 影片、讀取 Gmail 信件、管理 Google Calendar、操作 Google Drive 裡的檔案，你就需要 OAuth 2.0 授權。

為什麼需要它？

Google 不允許程式直接用你的帳號密碼登入（這太危險了）。取而代之的是一套標準流程：

1. 你的程式向 Google 說：「我想存取這個用戶的 YouTube 和 Gmail」
2. Google 跳出一個授權頁面，問你：「你同意讓這個程式存取嗎？」
3. 你點「同意」後，Google 發給程式一個 Token（通行證）
4. 程式拿著這個 Token 就可以代替你操作 Google 服務

最終目標

完成這份指南後，你將擁有一組 Token 可以存取 22 個 Google API Scope，包括：YouTube、Drive、Gmail、Calendar、Sheets、Docs、Slides、Photos、Tasks、Contacts。一次授權，全部搞定。

準備工作：GCP 項目設置

Step 1：建立 GCP 專案

1. 前往 Google Cloud Console
2. 點擊頂部的專案選擇器，選擇 新增專案 (New Project)
3. 輸入專案名稱，例如 nvda-strategy（用你自己的名稱即可）
4. 點擊 建立 (Create)

Step 2：啟用需要的 API

在左側選單進入 API 和服務 (APIs & Services) → 程式庫 (Library)，搜尋並逐一啟用以下 API：

Step 3：建立 OAuth 同意畫面

1. 進入 API 和服務 → OAuth 同意畫面 (OAuth consent screen)
2. 選擇 外部 (External) 類型（即使你只給自己用，也要選 External）
3. 填寫應用程式名稱（注意：不能包含 Google 產品名稱，詳見 Part 3）
4. 填寫支援電子郵件、開發者聯絡資訊
5. 在 Scopes 頁面加入你需要的權限（稍後 Part 4 會列出完整清單）

Step 4：建立 OAuth Client ID

1. 進入 API 和服務 → 憑證 (Credentials)
2. 點擊 建立憑證 (Create Credentials) → OAuth 用戶端 ID (OAuth Client ID)
3. 應用程式類型選擇 桌面應用程式 (Desktop app)
4. 點擊 建立
5. 下載 JSON 檔案，儲存為 client_secret.json

OAuth 同意畫面設置（重要坑點）

這一章記錄了我踩過的最大的坑。如果你不知道這些，可能會浪費好幾天在找問題。

坑點 1：Testing Mode vs Production Mode

操作方法：在 OAuth 同意畫面頁面，找到 發布狀態 (Publishing status)，點擊 推送至正式版 (Push to Production)。

坑點 2：應用程式名稱不能包含 Google 產品名

你可能會很自然地把應用取名為「YouTube Uploader」或「Gmail Manager」。千萬別這樣做。

Google 會在品牌驗證時拒絕包含其產品名稱的應用名。這是他們的品牌保護政策。

執行授權流程

準備工作做完了，現在來實際執行授權，拿到那張「萬能房卡」（Token）。

安裝必要的 Python 套件

# 安裝 Google Auth 相關套件
pip install google-auth google-auth-oauthlib google-auth-httplib2
pip install google-api-python-clientbash

完整的 22 個 Scope

以下是我一次性授權的所有 Scope。你可以根據自己的需求刪減，但建議全部加上 — 反正授權一次就好。

SCOPES = [
    # YouTube
    "https://www.googleapis.com/auth/youtube",
    "https://www.googleapis.com/auth/youtube.upload",
    "https://www.googleapis.com/auth/youtube.readonly",
    "https://www.googleapis.com/auth/youtube.force-ssl",
    # Gmail
    "https://www.googleapis.com/auth/gmail.modify",
    "https://www.googleapis.com/auth/gmail.send",
    "https://www.googleapis.com/auth/gmail.readonly",
    # Drive
    "https://www.googleapis.com/auth/drive",
    "https://www.googleapis.com/auth/drive.file",
    # Calendar
    "https://www.googleapis.com/auth/calendar",
    "https://www.googleapis.com/auth/calendar.events",
    # Sheets, Docs, Slides
    "https://www.googleapis.com/auth/spreadsheets",
    "https://www.googleapis.com/auth/documents",
    "https://www.googleapis.com/auth/presentations",
    # Photos
    "https://www.googleapis.com/auth/photoslibrary",
    "https://www.googleapis.com/auth/photoslibrary.readonly",
    "https://www.googleapis.com/auth/photoslibrary.appendonly",
    # Tasks
    "https://www.googleapis.com/auth/tasks",
    # Contacts (People API)
    "https://www.googleapis.com/auth/contacts.readonly",
    "https://www.googleapis.com/auth/contacts",
    # Gmail SMTP (for sending via SMTP)
    "https://mail.google.com/",
    # Profile
    "https://www.googleapis.com/auth/userinfo.email",
]python

授權腳本

import json
from google_auth_oauthlib.flow import InstalledAppFlow

CLIENT_SECRET_FILE = "client_secret.json"
TOKEN_OUTPUT_FILE  = "token.json"

# SCOPES 就是上面那個完整列表
SCOPES = [...]  # 貼上上面的 22 個 scope

def main():
    # 建立授權流程
    flow = InstalledAppFlow.from_client_secrets_file(
        CLIENT_SECRET_FILE,
        scopes=SCOPES
    )

    # 啟動本地伺服器，開啟瀏覽器讓你登入授權
    creds = flow.run_local_server(port=0)

    # 將 Token 保存為 JSON
    token_data = {
        "token": creds.token,
        "refresh_token": creds.refresh_token,
        "token_uri": creds.token_uri,
        "client_id": creds.client_id,
        "client_secret": creds.client_secret,
        "scopes": creds.scopes,
    }
    with open(TOKEN_OUTPUT_FILE, "w") as f:
        json.dump(token_data, f, indent=2)

    print(f"Token saved to {TOKEN_OUTPUT_FILE}")
    print(f"Scopes granted: {len(creds.scopes)}")

if __name__ == "__main__":
    main()python

執行授權

1. 確保 client_secret.json 在同一目錄下
2. 執行腳本：python authorize.py
3. 瀏覽器會自動彈出 Google 登入頁面
4. 登入你的 Google 帳號
5. 你會看到「此應用未驗證」警告，點 進階 (Advanced) → 前往 TT Personal Tools（不安全）
6. 勾選所有權限，點 繼續 (Continue)
7. 授權成功！token.json 已生成

（可選）將 Token 存入 GCP Secret Manager

如果你有多台電腦需要使用同一個 Token，建議存入 GCP Secret Manager，詳見 Part 8。

from google.cloud import secretmanager

def store_token_to_secret_manager(project_id, secret_id, token_json_str):
    client = secretmanager.SecretManagerServiceClient()
    parent = f"projects/{project_id}/secrets/{secret_id}"

    response = client.add_secret_version(
        request={
            "parent": parent,
            "payload": {"data": token_json_str.encode("UTF-8")},
        }
    )
    print(f"Stored token version: {response.name}")python

測試所有 API 連接

授權完成後，來驗證每個 API 是不是都能正常工作。以下是我的實際測試結果：

結果：17 / 18 項通過，唯一失敗的是 Google Photos API。這不是你的問題，是 Google 的特殊限制。繼續往下看。

Google Photos API 的特殊限制

這是所有 Google API 中最特殊的一個，行為跟其他 API 完全不同。

問題：即使授權成功，也會 403

你已經在 OAuth 授權時勾選了 Photos Library 的所有權限，Token 裡也包含了 Photos 的 scope，但當你實際呼叫 Photos API 時，會收到：

HTTP 403 Forbidden
{
  "error": {
    "code": 403,
    "message": "Request had insufficient authentication scopes.",
    "status": "PERMISSION_DENIED"
  }
}json

原因：Photos API 要求品牌驗證

Google Photos API 有一條特殊規則：未通過品牌驗證的應用，即使 Token 中包含 Photos scope，也不被允許存取。

這跟其他所有 Google API 都不同 — YouTube、Drive、Gmail、Calendar 等，未驗證的應用都可以正常使用（只是授權時會有「此應用未驗證」的警告）。

品牌驗證需要什麼？

• 一個有隱私權政策的網頁
• 經過 Google Search Console 驗證的網域
• 一段應用程式的示範影片
• 詳細的 scope 使用說明

如果你不需要 Photos API

如果你需要 Photos API

繼續看 Part 7：品牌驗證流程。

品牌驗證流程（如果你需要 Photos API）

這個流程比較繁瑣，但只需要做一次。以下是完整的步驟和我踩過的每一個坑。

Step 1：建立隱私權政策網頁

Google 要求你的應用有一個公開的隱私權政策頁面。最簡單的方式是部署到 Cloudflare Pages。

1. 建立一個簡單的 HTML 隱私權政策頁面（網上有很多模板）
2. 部署到 Cloudflare Pages（免費方案就夠了）
3. 確保可以從公開網路存取，例如 https://privacy.yourdomain.com

Step 2：在 Google Search Console 驗證網域

1. 前往 Google Search Console
2. 新增資源，選擇 網址前置字元 (URL prefix) 類型
3. 輸入你的網域（例如 https://yourdomain.com）
4. 選擇 HTML 標記 (HTML tag) 驗證方式
5. 複製 Google 給你的 <meta> 標籤，加到你網站的 <head> 中
6. 重新部署網站，然後回到 Search Console 點擊 驗證 (Verify)

<!-- 加在你首頁的 <head> 中 -->
<meta name="google-site-verification"
      content="你的驗證碼" />html

Step 3：填寫 OAuth 同意畫面品牌資訊

1. 回到 GCP Console → API 和服務 → OAuth 同意畫面
2. 填寫 應用程式名稱（記住不能包含 Google 產品名）
3. 填寫 應用程式首頁 URL
4. 填寫 隱私權政策連結 URL
5. 填寫 授權網域 (Authorized domains)

Step 4：提交驗證申請

1. 在同意畫面頁面，點擊 提交驗證 (Submit for verification)
2. 填寫每個 scope 的使用說明（用英文）
3. 上傳應用程式的示範影片（錄製你的程式如何使用這些 API）
4. 提交，等待 Google 審核

等待審核期間

踩坑總結

多台電腦共享 Token

如果你跟我一樣有桌機和筆電，想兩台電腦都能呼叫 Google API，怎麼辦？答案是用 GCP Secret Manager 來集中存放 Token。

架構

  ┌──────────────┐          ┌───────────────────┐
  │   Desktop    │ ───────▶ │                   │
  │  (主要授權)   │ ◀─────── │   GCP Secret      │
  └──────────────┘  讀/寫    │   Manager         │
                             │                   │
  ┌──────────────┐          │  token.json       │
  │   Laptop     │ ───────▶ │  (最新版本)        │
  │  (次要讀取)   │ ◀─────── │                   │
  └──────────────┘  讀取     └───────────────────┘diagram

讀取 Token

from google.cloud import secretmanager
import json

def get_token_from_secret_manager(project_id, secret_id):
    client = secretmanager.SecretManagerServiceClient()
    name = f"projects/{project_id}/secrets/{secret_id}/versions/latest"

    response = client.access_secret_version(request={"name": name})
    token_data = json.loads(response.payload.data.decode("UTF-8"))

    return token_datapython

自動更新流程

1. 程式啟動時，從 GCP Secret Manager 讀取最新的 token.json
2. 使用 Token 呼叫 Google API
3. 如果 Access Token 過期，用 Refresh Token 自動更新
4. 更新後，把新的 Token 寫回 GCP Secret Manager
5. 其他電腦下次啟動時，就會拿到最新的 Token

from google.oauth2.credentials import Credentials
from google.auth.transport.requests import Request

def load_and_refresh_token(project_id, secret_id):
    # 1. 從 Secret Manager 讀取
    token_data = get_token_from_secret_manager(project_id, secret_id)

    # 2. 建立 Credentials 物件
    creds = Credentials(
        token=token_data["token"],
        refresh_token=token_data["refresh_token"],
        token_uri=token_data["token_uri"],
        client_id=token_data["client_id"],
        client_secret=token_data["client_secret"],
    )

    # 3. 自動刷新過期的 Token
    if creds.expired:
        creds.refresh(Request())
        # 4. 寫回 Secret Manager
        new_token = json.dumps({
            "token": creds.token,
            "refresh_token": creds.refresh_token,
            "token_uri": creds.token_uri,
            "client_id": creds.client_id,
            "client_secret": creds.client_secret,
        })
        store_token_to_secret_manager(project_id, secret_id, new_token)

    return credspython

FAQ 常見問題