報表數字(預覽)
狀態:預覽(
preview),2026-11-06 加入。 契約已定案、可以呼叫,但尚未適用正式版的支援與棄用保證:欄位、錯誤細節與行為在轉為ga之前仍可能調整,調整會照版本與棄用公告。
讓租戶的機器帳號讀取自己的報表數字,例如每日的流量與結帳成效。這些數字和後台報表頁看到的相同。
| 能力 | 操作 | 作用 |
|---|---|---|
lightup.analytics.traffic.read |
GET /v1/analytics/traffic/query |
讀取一個指標 |
lightup.analytics.traffic.read |
GET /v1/analytics/traffic/metrics |
列出可用的指標 |
目前只開放流量與結帳漏斗的次數(工作階段、頁面、加購、結帳與付款的次數),不含金額。依渠道的訂單與營收屬於營收報表;營收、廣告與其他領域的報表能力還在規劃中,見能力目錄。
範圍與授權
- 只限機器流程。 呼叫者必須持有 service account 的 token(
client_credentials,workload)。使用者本人的 token 會被拒絕。 - 只限自己的租戶。 租戶只取自 token,請求裡沒有可以指定租戶的參數。
- 只回彙總。 次數、比例與分佈,不含任何個人資料;網址路徑中的識別碼會換成
:id。
查詢
GET /v1/analytics/traffic/query?topic=traffic&metric=channels&granularity=day&start=2026-11-05&end=2026-11-12
start 含、end 不含,都是租戶時區的日期。先呼叫 GET /v1/analytics/traffic/metrics,可以知道有哪些指標、每個指標支援哪些粒度。
回應的 meta.notes 寫著這批數字的限制,例如資料從哪一天開始才有,請一併讀取。meta.isPartial 為 true 表示有部分資料讀取失敗,數字可能偏低。
限制
| 項目 | 上限 | 超過時 |
|---|---|---|
| 範圍 | 最長 400 天;day 粒度最長 92 天 |
422 schema_invalid |
| 列數 | 每次最多 5,000 列 | 422 schema_invalid,請縮小範圍 |
請把用量控制在同時 2 個查詢、每分鐘 30 次以內。 超過時會收到 429 rate_limited 並帶 Retry-After。這是你可以放心使用的範圍,不是精確的上限:實際開始拒絕的時間點可能稍晚,請不要依賴它。
一次查詢約需 0.2–2 秒,太久會回 503,可以依 Retry-After 重試。這組操作是給每日報表用的,不適合輪詢。