GA 採集流水線指南
按資源顯示 GA4 資料卡在註冊 → 採集(原始) → AI 彙總 → 顯示哪個階段的診斷頁面。
📋 概述
GA4 指標要顯示在**GA 分析報告**中,需要經過 4 個階段。
| 階段 | 意義 | 儲存位置 |
|---|---|---|
| 目錄(註冊) | 在**GA 資源管理**中註冊資源 | tGaProperty |
| 採集(原始) | 採集器從 GA4 Data API 取得的原始指標 | tKVS(kType='ga') |
| AI 彙總 | 將原始指標由 AI 加工成報告 | tGaAiReport |
| 顯示 | 在頁面上顯示上述結果 | /zh-TW/gareport |
如果只註冊了資源但沒有採集器運行,就會卡在目錄階段,頁面上什麼都不顯示。本頁面正是用來顯示「哪個階段是空的」。
🚦 狀態說明
| 狀態 | 意義 |
|---|---|
| 正常 | 採集與 AI 彙總均正常 |
| AI 待處理 | 原始資料已採集,但 AI 彙總尚未運行 |
| 未採集 | 原始採集本身沒有在運行(最常見的問題) |
| 未啟用 | 資源已停用(不採集) |
▶️ 「開始採集」按鈕
處於未採集狀態的資源,行中會顯示**[開始採集]**按鈕。點擊後會立即觸發該資源的一次性 GA4 採集(與定期採集排程無關)。
點擊後可能出現的訊息:
| 訊息 | 原因 | 解決方法 |
|---|---|---|
| 已開始採集 | 正常 | 稍後重新整理,確認「採集(原始)」時間已填入 |
| 該組織尚未註冊 GA 採集器(GA Collector) | 從未為該組織(csn)註冊過任何 GA 採集排程(CQE) — 這不是程式問題,而是尚未設定 | 依下方「🔗 連結 GA 採集器伺服器」步驟由管理員首次註冊 |
| 您沒有權限採集此 GA 資源 | 該資源屬於其他組織,或登入帳號不屬於該組織 | 切換到正確的組織(csn)後重試 |
🔗 連結 GA 採集器伺服器(管理員操作)
「該組織尚未註冊 GA 採集器」代表沒有任何伺服器(lssn)被設定為定期執行該組織的 GA 採集工作。這與在頁面上註冊資源是不同的伺服器基礎設施連結工作,需要另外的步驟。
為什麼僅靠 Web UI 不夠
CQE(排程腳本)註冊頁面(/zh-TW/cqeRepoPut)對腳本本文有4,000 字元限制,而 GA 採集腳本本文遠超此長度(Linux 版約 7,800 字元,Windows 版約 9,700 字元)。因此腳本本身的首次註冊只能透過 CLI 完成。將其連結到伺服器(排程分配)則可以透過 Web UI 完成。
第 1 步 — 註冊採集腳本 + 連結伺服器(僅首次,CLI)
使用 giipdb/mgmt/register-ga-cqe.ps1。此腳本一次完成以下兩件事:
- 將採集腳本本文註冊到 CQE 儲存庫(
CQERepoPut)→ 產生mssn - 將該腳本分配到指定伺服器(
lssn)每日執行(CQEQueuePut)
# 針對 Linux 伺服器(建議 — 自動從資料庫取得金鑰,不需本地金鑰檔)
pwsh .\mgmt\register-ga-cqe.ps1 -Lssn <目標伺服器 lssn> -MsType sh `
-Property 'properties/123456789' -Auid '<您的登入 ID>'
# 針對 Windows 伺服器(giip-803 之後:省略 -KeyFile 時自動從資料庫取得金鑰)
pwsh .\mgmt\register-ga-cqe.ps1 -Lssn <目標伺服器 lssn> -MsType ps1 `
-Property 'properties/123456789' -Dispatcher 'https://<giip byAK 派送器 URL>' -Auid '<您的登入 ID>'重要: 目標伺服器(-Lssn)必須屬於該 GA 資源所屬的組織(csn)。使用其他組織的伺服器註冊雖然能通過驗證,但會一直找不到該組織的 GA 資源/金鑰而失敗 — 請先在**伺服器清單**中確認目標伺服器所屬的組織。
透過 -Property 指定的資源必須已在**GA 資源管理**頁面註冊(包含服務帳戶金鑰)。
第 2 步 — 將已註冊的腳本連結到其他伺服器(可用 Web UI)
如果腳本(mssn)已存在,想在其他伺服器上執行相同的採集,可以透過 Web UI 完成。
- 前往**CQE 佇列註冊**頁面
- mssn: 點擊[選擇]按鈕搜尋並選擇既有的「GA Collector...」腳本
- Lssn Group: 勾選目標伺服器
- csn: 目標組織編號
- interval: 採集週期(分鐘)。每日一次填
1440 - custom_values: 針對 shell(Linux)目標的範例
(服務帳戶金鑰會自動從資料庫取得,不需設定GaProperty='properties/123456789'GaKeyFile) - 儲存 — 完成後在**依伺服器執行清單**中確認註冊
確認註冊狀態
🔗 後續步驟
版本: 1.0
最後更新: 2026-07-29
來源檔案: giipv3/public/help/ga-pipeline.zh-TW.md