用 Claude Code 串接 Cloudflare Web Analytics API：自動產生每日流量報告

編譯摘要

用 Claude Code 串接 Cloudflare Web Analytics API：自動產生每日流量報告 — 編譯摘要

濃縮

核心結論：

  1. Cloudflare Web Analytics 的 GraphQL API 有三個不直覺的坑：wrangler OAuth token 權限不足、siteTag 與 beacon token 不同、欄位名稱不直覺（如 requestPath 而非 path）。
  2. /loop 排程只存在於當前 session，不適合每日任務；cron job 才是持久化排程的正確方案。
  3. 從 API 取得數據到 cron job 產出第一份報告，整個過程約一小時，大部分時間花在摸索 API 結構。

關鍵證據：

  • 自動注入模式下，siteTag 與 Dashboard 的 beacon token 不同，需用 requestHost 反查。
  • 效能數據使用不同的 dataset（rumPerformanceEventsAdaptiveGroups），單位是微秒。
  • 報告格式選 Markdown，因為終端機、GitHub、筆記軟體都能直接閱讀。

質疑

結論 1：API 的三個坑

  • 前提假設：使用自動注入模式。手動注入 JS snippet 的用戶可能不會遇到 siteTag 問題。
  • 換技術棧：其他分析工具（Google Analytics、Plausible）的 API 坑完全不同，經驗不可直接移植。
  • 邊界條件：Cloudflare 更新 API 後，這些坑可能已被修復或產生新的坑。

結論 2：cron 優於 /loop

  • 前提假設：任務需要在 Claude Code 關閉後仍持續執行。如果是開發期間的臨時監控，/loop 可能更方便。
  • 反例：雲端排程（如 GitHub Actions 的 cron trigger）可能比本機 cron 更可靠（不依賴電腦開機）。

對標

  1. ETL 流程（Extract-Transform-Load）：從 API 取數據 → 用 jq 轉換 → 輸出 Markdown，是一個微型的 ETL pipeline。
  2. 日報文化：日本企業的「日報」制度同樣強調每日回顧數據，差別在於自動化取代了人工整理。
  3. 監控告警系統：從 Prometheus + Grafana 到簡單的 cron + Markdown，是監控系統從重量級到輕量級的光譜。

關聯概念

  • [[自動化報告流程]]
  • [[API 串接踩坑模式]]
  • [[Claude Code 排程機制]]