在查閱與確認年度國定假日後,許多企業內部系統或 HR 工具需要將官方放假資訊自動整合至團隊日曆中。想透過 Google Calendar API 串接行政院人事行政總處的辦公日曆表,實務上常遭遇 OAuth 2.0 權限設定繁瑣、全天事件日期處理錯誤,以及大量寫入觸發 Rate Limit 等工程瓶頸。
官方資料集提供的檔案格式是 CSV,並沒有 JSON 介面。本文的範例會先讀取 CSV,再轉成 Google Calendar API 的 Event 結構。
想了解歷年放假資訊細節,可前往 〈2023 行事曆 – 放假一次看〉 觀看。本文將聚焦於 API 授權流程、資料格式轉換,以及自動化同步的部署與維護。
若你需要快速複製程式碼,可直接跳往 三、 實作範本:生產環境完整程式碼。
一、 核心速查與常見瓶頸對照
將政府開放資料(Open Data)串接至 Google Calendar 時,開發者最常因為資料格式不符或 API 呼叫頻率超限而導致同步失敗。
1. 常見錯誤寫法的工程瓶頸
- 全天事件日期處理不當:把
20260101這類日期字串先轉成 UTC 的 ISO 8601dateTime再送出,台北時間(UTC+8)與 UTC 的日期可能差一天。全天事件直接送start.date/end.date的yyyy-mm-dd字串即可。 - 無控管地寫入 API:在迴圈中逐筆呼叫
events.insert,未設定間隔與 Exponential Backoff,容易觸發rateLimitExceeded(官方錯誤頁說明可能以 403 或 429 回傳)。 - 混淆權限機制:在無人值守的 Cron Job 中使用需要使用者互動授權的 OAuth 2.0 Flow,Refresh Token 失效後背景作業整批失敗(失效原因見 Q7)。
2. 核心機制規格對照表
| 同步維度 | Service Account 方案 | OAuth 2.0 User Consent 方案 | 官方 Google 行事曆專用 CSV |
|---|---|---|---|
| 適用場景 | 無人值守的伺服器對伺服器同步 | 使用者授權存取自己的日曆 | 不寫程式,直接使用官方預先整理的檔案 |
| 授權驗證 | 以金鑰簽署 JWT 換取 access token,使用者不需參與 | 使用者同意授權並取得 Refresh Token | 不經過 API |
| 配額限制 | 共用 Calendar API 配額(每專案每分鐘 10,000 次、每使用者每專案每分鐘 600 次) | 同左 | 無 API 配額 |
| 寫入彈性 | 可呼叫 insert/patch/delete,範圍取決於授權 scope 與日曆權限 | 受授權 scope 限制 | 由檔案內容決定 |
二、 關鍵機制解析:底層規範與注意事項
1. 人事行政總處辦公日曆表資料集(CSV)
資料來源是政府資料開放平臺的〈中華民國政府行政機關辦公日曆表〉,提供機關為行政院人事行政總處。資料集頁面標示的重點如下:
- 檔案格式:CSV,每個年度一個檔案,另有「Google行事曆專用」版本。
- 欄位:
西元日期、星期、是否放假、備註。 - 更新頻率:每 1 年;授權方式:政府資料開放授權條款-第 1 版。
是否放假欄位說明:0 表示該日要上班,2 表示該日放假。
以 116 年的檔案為例,內容格式如下:
西元日期,星期,是否放假,備註
20270101,五,2,開國紀念日
20270102,六,2,
欄位轉成 Google Calendar 全天事件時的對應方式:
西元日期(如20270101):轉成YYYY-MM-DD,設定為start.date,end.date設為隔天。是否放假:2是放假,0是上班。備註:節日名稱或「補假」,可放進summary與description。
這份資料有兩個容易踩到的地方:
- 一般週末的
是否放假也是2,但備註是空白。只用是否放假 == 2判斷,會把每個週六日都匯入成放假事件。 - 補班日是
是否放假為0、備註為「補行上班」的星期六或日,例如 113 年檔案的20240217。
補充說明:官方資料集沒有提供 JSON 介面,欄位名稱是中文標題,不是
date、isHoliday。檔案編碼也隨年度不同:116 年、115 年檔案是 UTF-8(含 BOM),114 年的「1141020更新」檔案是 Big5,程式要依檔案選擇解碼方式。
人事行政總處的〈116 年辦公日曆表〉公告頁附件只有 xlsx、pdf、ods,CSV 要到上述資料集頁面下載。
2. 時區與全天事件 (All-day Event) 規範
Google Calendar API 對於全天事件的要求如下:
- 使用
start.date與end.date欄位(格式yyyy-mm-dd),而非start.dateTime。官方說明這兩個欄位用於全天事件。 end是不含當日的結束時間(官方欄位說明為 exclusive)。例如 2026 年 1 月 1 日放假一天,start.date為2026-01-01,end.date設定為2026-01-02。- 官方對
dateTime的說明是:除非明確指定timeZone,否則需要帶時區偏移。全天事件只送日期字串,就不必經過 UTC 時間轉換。
三、 實作範本:生產環境完整程式碼
以下提供 Python 與 Node.js 兩種語言的實作範本,流程是讀取官方 CSV、轉成全天事件、以退避機制寫入。
補充說明:範本只做新增,重複執行會產生重複事件,避免方式見 Q4。
calendar.events是官方列出events.insert可用的 scope 之一。
範本一:Python 讀取 DGPA CSV 並寫入 Google Calendar API
import csv
import io
import random
import time
from datetime import datetime, timedelta
import requests
from google.oauth2.service_account import Credentials
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError
SCOPES = ['https://www.googleapis.com/auth/calendar.events']
SERVICE_ACCOUNT_FILE = 'service_account.json'
CALENDAR_ID = '[email protected]'
# 資料集頁(https://data.gov.tw/dataset/14718)列出的當年度 CSV 下載網址
CSV_URL = 'https://www.dgpa.gov.tw/FileConversion?filename=dgpa/files/202607/f538b1ff-ba60-4c63-9477-10db8e6612d1.csv&nfix=&name=116%e5%b9%b4%e4%b8%ad%e8%8f%af%e6%b0%91%e5%9c%8b%e6%94%bf%e5%ba%9c%e8%a1%8c%e6%94%bf%e6%a9%9f%e9%97%9c%e8%be%a6%e5%85%ac%e6%97%a5%e6%9b%86%e8%a1%a8_utf8bom.csv'
def fetch_rows():
response = requests.get(CSV_URL, timeout=30)
response.raise_for_status()
# 116 年檔案為 UTF-8(含 BOM);Big5 編碼的年度檔要改用 'big5'
text = response.content.decode('utf-8-sig')
return list(csv.DictReader(io.StringIO(text)))
def to_event(row):
remark = (row.get('備註') or '').strip()
date_str = row.get('西元日期')
# 一般週末的「是否放假」也是 2,但備註是空白,沒有備註的列不匯入
if not date_str or not remark:
return None
label = '放假' if row.get('是否放假') == '2' else '上班'
start_dt = datetime.strptime(date_str, '%Y%m%d')
return {
'summary': f'【{label}】{remark}',
'description': f'行政院人事行政總處辦公日曆表:{remark}',
'start': {'date': start_dt.strftime('%Y-%m-%d')},
'end': {'date': (start_dt + timedelta(days=1)).strftime('%Y-%m-%d')}, # end 是不含當日的結束日
'transparency': 'transparent', # 不佔用忙碌狀態
'extendedProperties': {'private': {'dgpaDate': date_str}},
}
def insert_with_backoff(service, event, max_retry=5):
for n in range(max_retry + 1):
try:
return service.events().insert(calendarId=CALENDAR_ID, body=event).execute()
except HttpError as err:
# 403 與 429 依官方建議退避:min(2^n 秒 + 隨機毫秒(最多 1,000), 32 秒)
if err.resp.status not in (403, 429) or n == max_retry:
raise
time.sleep(min(2 ** n + random.random(), 32))
def sync_to_google_calendar():
creds = Credentials.from_service_account_file(SERVICE_ACCOUNT_FILE, scopes=SCOPES)
service = build('calendar', 'v3', credentials=creds)
for row in fetch_rows():
event = to_event(row)
if event is None:
continue
try:
insert_with_backoff(service, event)
print(f"成功新增事件: {event['start']['date']} {event['summary']}")
time.sleep(0.3) # 控制呼叫頻率
except HttpError as err:
print(f"寫入失敗 ({event['start']['date']}): {err}")
if __name__ == '__main__':
sync_to_google_calendar()
範本二:Node.js 環境使用 googleapis 套件同步資料
Node.js 範本使用內建的 fetch,只需要 npm install googleapis。
const { google } = require('googleapis');
const SCOPES = ['https://www.googleapis.com/auth/calendar.events'];
const KEY_PATH = './service_account.json';
const CALENDAR_ID = '[email protected]';
// 資料集頁(https://data.gov.tw/dataset/14718)列出的當年度 CSV 下載網址
const CSV_URL = 'https://www.dgpa.gov.tw/FileConversion?filename=dgpa/files/202607/f538b1ff-ba60-4c63-9477-10db8e6612d1.csv&nfix=&name=116%e5%b9%b4%e4%b8%ad%e8%8f%af%e6%b0%91%e5%9c%8b%e6%94%bf%e5%ba%9c%e8%a1%8c%e6%94%bf%e6%a9%9f%e9%97%9c%e8%be%a6%e5%85%ac%e6%97%a5%e6%9b%86%e8%a1%a8_utf8bom.csv';
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
// 欄位順序:西元日期,星期,是否放假,備註(備註內容沒有逗號,可直接用 split)
function parseCsv(text) {
const clean = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
return clean
.split(/\r?\n/)
.filter(Boolean)
.slice(1)
.map((line) => {
const [date, weekday, isHoliday, remark = ''] = line.split(',');
return { date, weekday, isHoliday, remark: remark.trim() };
});
}
// 以 UTC 運算加一天,結果不受執行環境時區影響
function nextDay(yyyymmdd) {
const [y, m, d] = [yyyymmdd.slice(0, 4), yyyymmdd.slice(4, 6), yyyymmdd.slice(6, 8)].map(Number);
return new Date(Date.UTC(y, m - 1, d + 1)).toISOString().slice(0, 10);
}
// 一般週末的「是否放假」也是 2,但備註是空白,沒有備註的列不匯入
function toEvent(row) {
if (!row.date || !row.remark) return null;
const label = row.isHoliday === '2' ? '放假' : '上班';
const start = `${row.date.slice(0, 4)}-${row.date.slice(4, 6)}-${row.date.slice(6, 8)}`;
return {
summary: `【${label}】${row.remark}`,
description: `行政院人事行政總處辦公日曆表:${row.remark}`,
start: { date: start },
end: { date: nextDay(row.date) }, // end 是不含當日的結束日
transparency: 'transparent', // 不佔用忙碌狀態
extendedProperties: { private: { dgpaDate: row.date } },
};
}
// 403 與 429 依官方建議退避:min(2^n 秒 + 隨機毫秒(最多 1,000), 32 秒)
async function insertWithBackoff(calendar, params, maxRetry = 5) {
for (let n = 0; ; n += 1) {
try {
return await calendar.events.insert(params);
} catch (err) {
const status = Number(err.response?.status ?? err.code);
if (![403, 429].includes(status) || n >= maxRetry) throw err;
await sleep(Math.min(2 ** n * 1000 + Math.random() * 1000, 32000));
}
}
}
async function main() {
const auth = new google.auth.GoogleAuth({ keyFile: KEY_PATH, scopes: SCOPES });
const calendar = google.calendar({ version: 'v3', auth });
const res = await fetch(CSV_URL);
if (!res.ok) throw new Error(`下載失敗:HTTP ${res.status}`);
// 116 年檔案為 UTF-8(含 BOM);若改用 Big5 編碼的年度檔,需改成 new TextDecoder('big5')
const text = new TextDecoder('utf-8').decode(await res.arrayBuffer());
for (const row of parseCsv(text)) {
const event = toEvent(row);
if (!event) continue;
try {
await insertWithBackoff(calendar, { calendarId: CALENDAR_ID, requestBody: event });
console.log(`[成功] ${event.start.date} ${event.summary}`);
await sleep(300); // 控制呼叫頻率
} catch (err) {
console.error(`[錯誤] ${event.start.date}:`, err.message);
}
}
}
main().catch(console.error);
補充說明:重試條件包含 403,因為
rateLimitExceeded可能以 403 回傳;但 403 也可能是權限不足,這類錯誤重試用完後會直接拋出,請依錯誤訊息的reason判斷。
四、 常見問題與排錯(Q&A)
Q1:如何把人事行政總處 CSV 的欄位對應到 Google Calendar API 的 Event 結構?
問題原因
官方 CSV 的欄位名稱(西元日期、星期、是否放假、備註)與 Google Calendar API 的 Event 結構不同。此外,各年度檔案的編碼不一致,有 UTF-8(含 BOM)也有 Big5,若沒有先判斷編碼,會出現亂碼,或讓第一個欄位名稱多出 BOM 字元。
解法
建立一個資料洗淨層(Data Cleaning Layer),在呼叫 API 之前先進行解碼與格式標準化:
- 依檔案編碼解碼,並移除開頭的 BOM。
- 將
西元日期轉成YYYY-MM-DD,end.date設為隔天。 - 略過
備註為空白的列,其餘列的備註對應至summary與description。
Q2:Google Calendar API 的配額與 Rate Limit 要怎麼排查?
問題原因
官方配額文件列出的限制是每專案每分鐘 10,000 次、每使用者每專案每分鐘 600 次,以滑動視窗計算。每專案每日 1,000,000 次是計費門檻,不是速率配額。
超過限制時,官方錯誤頁說明 rateLimitExceeded 可能以 403 或 429 回傳,userRateLimitExceeded 則是 403。
解法
- 採用 Exponential Backoff(指數退避):官方建議的等待時間是
min((2^n) + 隨機毫秒, maximum_backoff),隨機毫秒最多 1,000,maximum_backoff通常是 32 或 64 秒。範本照這個公式實作。 - 控制呼叫頻率:每位使用者每分鐘 600 次約等於每秒 10 次,範本每筆間隔 300 ms,遠低於這個速率。
- 批次請求不能用來繞過限制:Calendar API 批次文件說明單一批次最多 1000 個呼叫,且批次內每個呼叫仍各自計入配額。
Q3:使用 Service Account 與 OAuth 2.0 在自動化同步場景下的權限差異?
問題原因
開發者常誤用一般 OAuth 2.0 Client ID 來做後台 Cron Job,導致程式執行一段時間後因 Refresh Token 失效而中斷。
解法
- Service Account(服務帳號):官方文件把它定義為屬於應用程式、而非個別使用者的帳號,適合伺服器對伺服器的自動化同步,使用者不需要參與。token 過期時,程式重新簽署 JWT 並換取新的 access token,不需要儲存 Refresh Token。
- OAuth 2.0 User Consent:適用於使用者登入並授權存取自己的 Google 日曆,需要妥善儲存 Refresh Token(失效原因見 Q7)。
要讓服務帳號寫入某個日曆,實務上由日曆擁有者在 Google 日曆的共用設定中,把服務帳號的 Email 加入並給予「變更活動」權限(Google 日曆說明頁列出的權限名稱包含「變更活動」與「變更活動及查看活動詳細資料」)。Workspace 管理員也可以改用網域全域委派,由服務帳號模擬網域內的使用者。
Q4:如何偵測人事行政總處行事曆更新並觸發差異化同步 (Delta Sync)?
問題原因
依人事行政總處辦公日曆表頁面引用的規定,次年度日曆表原則上在每年 6 月 30 日前公告,有特殊情形可延至 8 月 31 日前(116 年版的公告時間是 115 年 5 月 21 日)。
已公告的年度也可能再發布更新版,例如資料集中的 114 年版就另有「1141020更新」檔案。若每次都全量重新寫入,會消耗配額並造成重複事件。
解法
- 唯一鍵設計:新增事件時,把日期寫入
extendedProperties.private.dgpaDate(範本已這樣做)。官方限制屬性的 key 最長 44 字元、value 最長 1024 字元。 - 差異比對 (Delta Check):同步前先呼叫
events.list,帶入privateExtendedProperty=dgpaDate=20260101(官方格式為propertyName=value,只比對 private 屬性)。若事件已存在且內容一致就略過;內容變更時呼叫events.patch;不存在才呼叫events.insert。
Q5:Node.js 環境下 googleapis 套件處理時區偏移 (Timezone Offset) 的常見陷阱?
問題原因
Node.js 的 new Date('2026-01-01') 會被解析為 UTC 時間 2026-01-01T00:00:00.000Z。若搭配本機時區的方法(如 getDate()、setDate())運算,結果會隨執行環境的時區而異。
解法
全天事件只需要 YYYY-MM-DD 字串。需要加一天時,全程使用 UTC 運算,結果就不受執行環境時區影響:
const rawDate = '20261231'; // 人事行政總處格式
const formattedDate = `${rawDate.slice(0, 4)}-${rawDate.slice(4, 6)}-${rawDate.slice(6, 8)}`;
// 以 UTC 運算加一天,回傳 YYYY-MM-DD 字串
function getNextDayString(yyyymmdd) {
const [y, m, d] = [yyyymmdd.slice(0, 4), yyyymmdd.slice(4, 6), yyyymmdd.slice(6, 8)].map(Number);
return new Date(Date.UTC(y, m - 1, d + 1)).toISOString().slice(0, 10);
}
const event = {
summary: '【放假】國定假日',
start: { date: formattedDate },
end: { date: getNextDayString(rawDate) },
};
console.log(event.start.date, event.end.date);
執行結果:
2026-12-31 2027-01-01
Q6:如何透過 Google Calendar API 批次刪除或更新已匯入的補行上班或放假事件?
問題原因
人事行政總處更新年度檔案後,先前匯入的事件可能與新檔不一致,需要清除或修正。
解法
- 用
events.list搭配q關鍵字搜尋(如補行上班),或用privateExtendedProperty篩選出事件列表。 - 逐筆呼叫
events.delete({ calendarId, eventId });官方的刪除請求是DELETE .../calendars/calendarId/events/eventId。 - 刪除同樣受配額限制,務必搭配 Q2 的退避與間隔。
Q7:在 Cron Job 執行期間,如何處理 OAuth 2.0 Refresh Token 過期失效問題?
問題原因
Google 官方 OAuth 2.0 文件列出 Refresh Token 失效的原因,常見的有:
- OAuth 同意畫面的發布狀態是 Testing,且請求的 scope 不只基本個人資料時,Refresh Token 有效期限是 7 天。
- 使用者撤銷了應用程式的存取權。
- Refresh Token 連續六個月沒有使用。
- 每個 Google 帳號、每個 OAuth client ID 最多 100 個 Refresh Token,超過時最舊的會失效;服務帳號不受這項限制。
官方另說明,使用者變更密碼會讓 Refresh Token 失效的情況,僅限於 Token 含 Gmail scope,Calendar scope 不在此列。
解法
- 生產環境解法:若為內部服務,建議改用 Service Account,不需要處理 Refresh Token 的生命週期。
- 正式發布解法:若必須使用個人日曆授權,請至 Google Cloud Console 將 OAuth 應用程式的發布狀態從「Testing」切換為「In Production」,並確保排程至少每六個月使用一次 Token。
- 自動更新機制:在 Node.js 中使用
oauth2Client.on('tokens', (tokens) => { ... })監聽事件。googleapis 官方 README 的範例是在tokens.refresh_token存在時才儲存,請寫回安全的持久化儲存區(如資料庫或加密檔案)。
參考資料與延伸閱讀
- 中華民國政府行政機關辦公日曆表(政府資料開放平臺)
- 中華民國一百一十六年政府行政機關辦公日曆表(行政院人事行政總處)
- Google Calendar API:Events: insert
- Google Calendar API:Events: list
- Google Calendar API:Manage quotas
- Google Calendar API:Handle API errors
- Google Calendar API:Batch requests
- Google Calendar API:Extended properties
- OAuth 2.0 for Server to Server Applications(Service Account)
- Using OAuth 2.0 to Access Google APIs:Refresh token expiration
- googleapis/google-api-nodejs-client(GitHub)
- RFC 5545: Internet Calendaring and Scheduling Core Object Specification (iCalendar)
- 站內延伸閱讀:2023 行事曆 – 放假一次看
發佈留言