Google Gmail API 與 Calendar API 申請教學

你只需要一個 Google 帳號(一般 Gmail 帳號即可)。整個流程不需要綁定信用卡:Gmail API 與 Calendar API 都有免費配額,個人開發綽綽有餘。

開啟 https://console.cloud.google.com/projectcreate(或在控制台上方的專案選單點「新增專案」)。

1. 在「專案名稱」輸入好記的名稱,例如 api-course-demo(名稱下方會自動產生專案 ID,之後無法更改)。
2. 個人帳號「父項資源」保持「無組織」即可。
3. 按 建立。約 10 秒後右上角鈴鐺會出現「建立專案:api-course-demo ✔」的通知。
4. 在通知中點「選取專案」,或用上方專案下拉選單切換到新專案。之後所有步驟都要確認左上角顯示的是這個專案。

左上選單 ☰ → API 和服務 → 程式庫,搜尋「Gmail」;或直接開啟 https://console.cloud.google.com/apis/library/gmail.googleapis.com。

按下 啟用 後會轉圈約 5~10 秒,完成後自動跳到「API/服務詳細資料」頁,狀態顯示 已啟用。頁面上方會提示「您可能需要建立憑證,才能從自己的應用程式呼叫這個 API」——憑證我們在步驟 5 建立。

同樣方式,在程式庫搜尋「Calendar」,選擇 Google Calendar API;或直接開啟 https://console.cloud.google.com/apis/library/calendar-json.googleapis.com。

按 啟用,狀態變成「已啟用」即完成。到此專案已可使用兩個 API,接著處理授權。

左側選單 API 和服務 → OAuth 同意畫面,會進入「Google Auth Platform」。新專案會顯示「尚未設定 Google 驗證平台」,按 開始。

設定精靈共 4 個步驟(實測畫面依序如下):

1. 應用程式資訊:「應用程式名稱」輸入例如 API Course Demo(這是使用者在授權畫面看到的名稱);「使用者支援電子郵件」下拉選你自己的 Gmail。按「下一步」。
2. 目標對象:選 外部。個人 Gmail 帳號沒有 Workspace 組織,只能選外部;應用程式會先以「測試模式」推出,只有測試使用者清單中的人可以用。按「下一步」。
3. 聯絡資訊:輸入你的電子郵件(Google 專案異動通知用)。按「下一步」。
4. 完成:勾選「我同意《Google API 服務:使用者資料政策》」→ 按「繼續」→ 按 建立。畫面底部出現「OAuth 設定建立完成!」。

Google Auth Platform 左側選單 → 用戶端 → 建立用戶端(或 API 和服務 → 憑證 → 建立憑證 → OAuth 用戶端 ID)。

按 建立 後跳出「OAuth 用戶端已建立」視窗:

Google Auth Platform → 資料存取權 → 新增或移除範圍。右側會滑出「更新所選範圍」面板,列出已啟用 API 的所有範圍(這就是為什麼要先做步驟 2、3)。

1. 在「篩選條件」輸入 gmail.send 按 Enter,勾選 Gmail API 的 .../auth/gmail.send(以您的名義傳送電子郵件)。
2. 清除篩選,再輸入 calendar.events,勾選 Google Calendar API 的 .../auth/calendar.events(查看及編輯所有日曆上的活動)。
3. 捲到面板底部按 更新,回到頁面後再按 Save。

應用程式處於「測試中」狀態時,只有測試使用者清單裡的帳號能完成 OAuth 授權。Google Auth Platform → 目標對象 → 測試使用者區塊按 + Add users。

輸入你要拿來測試的 Gmail(通常就是自己的帳號),按 Save。上限 100 位。

把步驟 5 下載的 credentials.json 放到程式同層資料夾,安裝套件:

pip install google-auth-oauthlib google-api-python-client

第一次執行會自動打開瀏覽器,用測試使用者帳號登入並同意授權(畫面會顯示「Google 尚未驗證這個應用程式」,點「繼續」即可,因為是你自己的 App)。授權後 token 會存在本機,之後不必重新登入。

# demo.py — 寄一封信 + 建一個行事曆活動
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build
import base64, os.path, pickle
from email.mime.text import MIMEText

SCOPES = [
    "https://www.googleapis.com/auth/gmail.send",
    "https://www.googleapis.com/auth/calendar.events",
]

# --- OAuth 授權(第一次會開瀏覽器) ---
creds = None
if os.path.exists("token.pickle"):
    with open("token.pickle", "rb") as f:
        creds = pickle.load(f)
if not creds or not creds.valid:
    flow = InstalledAppFlow.from_client_secrets_file("credentials.json", SCOPES)
    creds = flow.run_local_server(port=0)
    with open("token.pickle", "wb") as f:
        pickle.dump(creds, f)

# --- Gmail:寄信 ---
gmail = build("gmail", "v1", credentials=creds)
msg = MIMEText("哈囉,這封信是用 Gmail API 寄出的!")
msg["to"] = "someone@example.com"
msg["subject"] = "Gmail API 測試"
raw = base64.urlsafe_b64encode(msg.as_bytes()).decode()
gmail.users().messages().send(userId="me", body={"raw": raw}).execute()
print("信寄出去了!")

# --- Calendar:建立活動 ---
cal = build("calendar", "v3", credentials=creds)
event = {
    "summary": "API 課程練習",
    "start": {"dateTime": "2026-07-20T10:00:00+08:00"},
    "end":   {"dateTime": "2026-07-20T11:00:00+08:00"},
}
created = cal.events().insert(calendarId="primary", body=event).execute()
print("活動建好了:", created.get("htmlLink"))

Q1:授權時出現「拒絕存取」錯誤 (403: access_denied)?

登入的帳號不在測試使用者清單。回到步驟 7 把該帳號加進去。

Q2:出現「Google 尚未驗證這個應用程式」警告?

測試模式的正常現象。點「繼續」(有時藏在「進階」連結裡)即可,因為這是你自己建立的應用程式。

Q3:過幾天 token 失效、要求重新登入?

測試模式的 refresh token 有效期 7 天。刪掉 token.pickle 重新授權,或將應用程式發布為正式版。

Q4:找不到「OAuth 同意畫面」選單?

2024 年後 Google 把它整合進「Google Auth Platform」。路徑:API 和服務 → OAuth 同意畫面,或直接開 console.cloud.google.com/auth/overview。

Q5:API 已啟用,程式卻回報 API not enabled?

多半是專案選錯了。確認控制台左上角專案名稱,以及 credentials.json 是從同一個專案下載的。