紀錄工作經驗、相關知識,解決技術相關問題。

Node JS, 網站相關

Google Calendar API 串接:取得人事行政總處辦公日曆表 CSV 資料與自動化同步教學

Google Calendar API 串接:取得人事行政總處辦公日曆表 CSV 資料與自動化同步教學 特色圖片

在查閱與確認年度國定假日後,許多企業內部系統或 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 8601 dateTime 再送出,台北時間(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 之前先進行解碼與格式標準化:

  1. 依檔案編碼解碼,並移除開頭的 BOM。
  2. 將 西元日期 轉成 YYYY-MM-DD,end.date 設為隔天。
  3. 略過 備註 為空白的列,其餘列的 備註 對應至 summary 與 description。

Q2:Google Calendar API 的配額與 Rate Limit 要怎麼排查?

問題原因

官方配額文件列出的限制是每專案每分鐘 10,000 次、每使用者每專案每分鐘 600 次,以滑動視窗計算。每專案每日 1,000,000 次是計費門檻,不是速率配額。

超過限制時,官方錯誤頁說明 rateLimitExceeded 可能以 403 或 429 回傳,userRateLimitExceeded 則是 403。

解法

  1. 採用 Exponential Backoff(指數退避):官方建議的等待時間是 min((2^n) + 隨機毫秒, maximum_backoff),隨機毫秒最多 1,000,maximum_backoff 通常是 32 或 64 秒。範本照這個公式實作。
  2. 控制呼叫頻率:每位使用者每分鐘 600 次約等於每秒 10 次,範本每筆間隔 300 ms,遠低於這個速率。
  3. 批次請求不能用來繞過限制: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更新」檔案。若每次都全量重新寫入,會消耗配額並造成重複事件。

解法

  1. 唯一鍵設計:新增事件時,把日期寫入 extendedProperties.private.dgpaDate(範本已這樣做)。官方限制屬性的 key 最長 44 字元、value 最長 1024 字元。
  2. 差異比對 (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 批次刪除或更新已匯入的補行上班或放假事件?

問題原因

人事行政總處更新年度檔案後,先前匯入的事件可能與新檔不一致,需要清除或修正。

解法

  1. 用 events.list 搭配 q 關鍵字搜尋(如 補行上班),或用 privateExtendedProperty 篩選出事件列表。
  2. 逐筆呼叫 events.delete({ calendarId, eventId });官方的刪除請求是 DELETE .../calendars/calendarId/events/eventId。
  3. 刪除同樣受配額限制,務必搭配 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 不在此列。

解法

  1. 生產環境解法:若為內部服務,建議改用 Service Account,不需要處理 Refresh Token 的生命週期。
  2. 正式發布解法:若必須使用個人日曆授權,請至 Google Cloud Console 將 OAuth 應用程式的發布狀態從「Testing」切換為「In Production」,並確保排程至少每六個月使用一次 Token。
  3. 自動更新機制:在 Node.js 中使用 oauth2Client.on('tokens', (tokens) => { ... }) 監聽事件。googleapis 官方 README 的範例是在 tokens.refresh_token 存在時才儲存,請寫回安全的持久化儲存區(如資料庫或加密檔案)。

參考資料與延伸閱讀

發佈留言