前言¶
在 B 站三連推廣裏做投放，後臺能看報表，但一旦要按賬戶、計劃、單元或創意做批量覈對，或把日/小時數據接到自己的腳本和 Agent 流程裏，手工導出往往跟不上。Marketing API（MAPI）側有自定義報表接口，但維度名、指標名、舊版結構與創意驅動 2.0 兩套口徑不能混用，日期範圍也要按天循環請求。下面介紹 SkillHub 上的 B站三連廣告-報表，它把 POST /open_api/report/v3/custom/query 的用法、約束和錯誤處理寫進 Agent 可執行的 SKILL 說明，並與同系列的授權主流程 Skill 銜接。
這是什麼¶
B站三連廣告-報表（包內標識 bilibili-sanlian-ads-reporting）面向 Bilibili 三連廣告 MAPI 的投放報表場景：通過自定義報表端點查詢消耗、曝光、點擊、轉化等投放指標，支持按賬戶、計劃、單元、創意（舊結構）或項目、媒體（創意驅動投放 2.0）等維度聚合，粒度可選日期或小時。
Skill 託管在 SkillHub（用戶 user_b0010d5c），分類爲 data-analysis；公開頁顯示評分 93403、下載約 2492 次（數據取自 Skill 線索，以 SkillHub 頁面爲準）。當前資源快照版本爲 3.0.4，約 7 個文件、107.4 KB，更新時間爲 2026-10-12。
同系列中，創編與列表類接口不返回花費、曝光、點擊；投放效果數據應走本 Skill 所描述的報表端點。賬戶餘額、預算、資金流水屬於 bilibili-sanlian-ads-account-finance，與報表消耗不是同一套數據，字段級也無法一一對賬。
核心功能¶
經與 Skill 說明覈對，能力集中在單一報表端點及其查詢規則上。
自定義報表查詢¶
核心請求爲：
POST https://cm.bilibili.com/takumi/api/open_api/report/v3/custom/query
Authorization: Bearer {access_token}
Content-Type: application/json
X-Call-Source: sanlian-skills
X-Sanlian-Skills-Version: 3.0.4
請求體中選定維度（dimensions）、指標（metrics）、起止時間，並可加 filters 過濾。完整維度與指標列表以 Skill 內 references/807_自定義報表.md（對應開發者文檔「投放報表 / 自定義報表」，doc_id 807）爲準；名稱必須爲文檔中的精確字符串，未知指標會直接被拒。
賬戶級與對象級口徑¶
- 賬戶彙總：只傳
account_id，不附加計劃/單元/創意/項目/媒體維度或過濾。一次賬戶級查詢可同時覆蓋舊版投放與創意驅動 2.0 投放的彙總。 - 對象級：在
dimensions或filters[].field中出現對象 ID 時，會進入「舊版模式」或「創意驅動 2.0 模式」之一，兩套指標表不同。
| 舊版模式 | 創意驅動 2.0 模式 | |
|---|---|---|
| 觸發條件 | campaign_id、unit_id 或 creative_id 出現在維度或過濾字段 |
promotion_id 或 media_id 出現在維度或過濾字段 |
| 指標集 | 舊版指標集 | 116 個基礎指標 |
| 衍生指標 | 支持 | 不支持（無 cost_per_*、*_rate、*_roi 等，需用絕對值自行計算） |
兩套維度不能混查；混用會返回「系統繁忙」，應拆成兩次請求。指標不在當前模式列表中會返回「指標 [xxx] 不存在」，屬參數錯誤，不宜當作瞬時故障重試。
時間、過濾與返回行含義¶
- 單日請求：
start_time與end_time必須爲同一天，格式YYYY-MM-DD。跨多天區間需在 Agent 或腳本中按天順序循環，一天完成並校驗後再發下一天，不要並行扇出。 - 過濾：每個 filter 的
values最多 100 個 ID，且 filter 存在時values不能爲空；更大 ID 集需拆分多次請求。 - 粒度：可選按日或按小時；按小時會顯著增加行數，需配合分頁策略。
- 無花費無行：接口只返回有消耗的 row；缺行表示當日該對象無消耗，不是漏數，也無需爲此重試。
金額字段¶
- 無後綴字段單位爲元（展示用）。
- 帶
_milli後綴爲毫分位原值（1 元 = 100000），對賬、計費覈對建議用整數運算處理_milli字段。
Agent 側調用約定¶
Skill 要求所有 MAPI 調用經封裝腳本執行，而不是手寫 curl / requests / fetch，且不要跨賬戶或對象並行請求：
# Unix / macOS / Linux
scripts/mapi.sh call [--query-file q.json] [--body-file body.json]
# Windows
py -3 scripts/mapi_client.py call [--query-file q.json] [--body-file body.json]
腳本負責加載與刷新 token、附加請求頭、限速（Rule 1）及統一錯誤分類。業務成敗以響應體爲準，不能只看 HTTP 狀態碼。
中文觸發詞包括：報表、數據、消耗、花費、曝光、點擊、轉化、投放數據、自定義報表、看數據、跑量情況。對話裏出現「昨天」「最近」「跑得好」等表述時，Skill 要求先解析爲明確時區、日期、指標與對象範圍，再發起請求。
安裝與啓用¶
SkillHub 官方地址：
https://api.skillhub.cn/user_b0010d5c/sanlian-ads-reporting
當前環境對該 URL 的頁面抓取未成功（HTTP 405），具體「安裝」按鈕或 CLI 命令請以 SkillHub 站內說明爲準。Skill 遵循通用 SKILL.md 格式，安裝後由支持 Skills 的客戶端（如 Cursor、Claude Code 等）加載；各客戶端啓用路徑若與 SkillHub 文檔不一致，以你使用的客戶端與 SkillHub 當前指引爲準。
前置依賴（Skill 內硬性要求）：
- 有效的 MAPI
access_token與廣告主account_id。缺任一項時，應先使用同系列bilibili-sanlian-ads（B站三連廣告-授權與主流程）完成 OAuth、刷新 token 並確認賬戶範圍。 - 調用報表前閱讀
references/807_自定義報表.md拼請求體。 - 遵守主 Skill 中的順序調用與出錯即停原則；長區間先估算「按天 / 按頁」調用計劃再執行。
Skill 頁註明可能涉及第三方服務或模型，需按介紹配置相應 API Key（若你的部署路徑需要）。
典型用法¶
下面是與官方 Skill 說明一致的可復現流程，不代替真實 token 與 account_id。
查昨日賬戶總消耗¶
- 通過
bilibili-sanlian-ads確認access_token與account_id。 - 在
body.json中設置賬戶級查詢：僅account_id，start_time與end_time均爲目標自然日（例如2026-10-19），選定文檔中的消耗、曝光、點擊、轉化類指標名。 - 執行：
scripts/mapi.sh call --body-file body.json
- 解析響應體中的業務狀態與數據行；若需多日，將日期改爲下一天並等待上一日響應校驗完成後再發。
按計劃看投放表現（舊版結構）¶
- 在
dimensions或filters中使用campaign_id（或unit_id/creative_id），進入舊版指標集。 - 指標名僅從舊版列表選取；需要點擊率、轉化成本等衍生指標時，在舊版模式下使用接口提供的衍生字段（2.0 模式需自行用基礎指標計算）。
- 單日、單頁順序查詢；filter 中計劃 ID 超過 100 個時拆批。
創意驅動 2.0（項目 / 媒體）¶
- 維度或過濾使用
promotion_id或media_id，勿與campaign_id等舊版字段同請求。 - 僅請求 116 個基礎指標；ROI、率類需本地計算。
- 與舊版計劃數據對比時，分別拉兩套報表，不要期望一次請求合併。
與資金類問題的區分¶
用戶問「花了多少錢 / 效果怎樣」→ 本 Skill。問「賬戶餘額、預算、流水」→ 轉 bilibili-sanlian-ads-account-finance。
適用場景與注意¶
適合：
- 已接入或計劃接入 B 站三連 MAPI，需要在 Agent 對話中用自然語言拉自定義報表的團隊。
- 需要按日或按小時覈對消耗、曝光、點擊、轉化，且願意遵守「按天順序、不併行扇出」的調用紀律的自動化腳本維護者。
- 同時使用舊版計劃/單元/創意與創意驅動 2.0，需要 Skill 明確兩套維度與指標邊界的情況。
注意：
- 須先具備 MAPI 授權與 App 憑證；平臺對 MAPI 接入有商務與權限門檻，需向 B 站側申請 Appkey / Appsecret 及報表拉取權限。
- 不要猜測指標英文名，也不要從其他廣告平臺直譯指標名。
- 查詢失敗時，先檢查：起止日期是否同一天且格式正確、指標是否屬於當前模式、維度是否混用；勿通過反覆替換維度/指標「試 API」。
- 報表消耗與財務賬戶數據系統不同，對賬時需區分數據源。
結尾¶
B站三連廣告-報表把三連 MAPI 自定義報表的端點、雙投放結構、按日循環與金額精度寫進可執行的 Skill 規則，並與授權主流程、財務 Skill 分工清晰，適合把「看數據、看消耗、看跑量」交給 Agent 時作爲專用能力加載。
官方地址：https://api.skillhub.cn/user_b0010d5c/sanlian-ads-reporting
