Ads Data Get — 获取广告数据

Ads Data Get 是一个广告平台数据查询工具，支持 Facebook 和 TikTok 平台。

支持平台 平台 | 功能 | 环境变量 ----|----|---- Facebook | 余额、消耗、多层级分析、国家维度 | facebook_access_token TikTok | 余额、消耗、多层级分析、国家维度 | tiktok_access_token, tiktok_app_id

TikTok 广告数据分析

• 快速汇总报告

# 获取所有账号余额/消耗汇总 python scripts/tiktok_ads.py # JSON 格式输出 python scripts/tiktok_ads.py --json

• 单账号全方位分析

# 分析指定账号（最近 7 天） python scripts/tiktok_ads.py --analyze --account # 指定时间范围 python scripts/tiktok_ads.py --analyze --account --since 2026-03-01 --until 2026-03-13 # 分析最近 30 天 python scripts/tiktok_ads.py --analyze --account --days 30

• 单层级数据查询

# Campaign 级别数据 python scripts/tiktok_ads.py --account --level campaign --json # AdGroup 级别数据 python scripts/tiktok_ads.py --account --level adgroup --json # Ad 级别数据 python scripts/tiktok_ads.py --account --level ad --json # 按国家分组 python scripts/tiktok_ads.py --account --level account --breakdown country --json

Facebook 广告数据分析

• 快速汇总报告

# 获取所有账号余额/消耗汇总 python scripts/facebook_ads.py # JSON 格式输出 python scripts/facebook_ads.py --json

• 单账号全方位分析

# 分析指定账号（最近 7 天） python scripts/facebook_ads.py --analyze --account act_586806297825353 # 指定时间范围 python scripts/facebook_ads.py --analyze --account act_586806297825353 --since 2026-03-01 --until 2026-03-13 # 分析最近 30 天 python scripts/facebook_ads.py --analyze --account act_586806297825353 --days 30

• 单层级数据查询

# Campaign 级别数据 python scripts/facebook_ads.py --account act_586806297825353 --level campaign --json # AdSet 级别数据 python scripts/facebook_ads.py --account act_586806297825353 --level adset --json # Ad 级别数据 python scripts/facebook_ads.py --account act_586806297825353 --level ad --json # 按国家分组 python scripts/facebook_ads.py --account act_586806297825353 --level account --breakdown country --json

命令行参数 参数 | 说明 | 示例 ----|----|---- --analyze | 执行全方位分析 | --analyze --account, -a | 指定账号 ID | --account act_123456 --level, -l | 数据层级: account/campaign/adset/ad | --level campaign --breakdown, -b | 分组维度 (可多次使用) | --breakdown country --since | 开始日期 | --since 2026-03-01 --until | 结束日期 | --until 2026-03-13 --days | 最近 N 天 | --days 30 --top | 显示 Top N 结果 | --top 20 --json, -j | JSON 格式输出 | --json

Python 调用示例 TikTok from scripts.tiktok_ads import ( get_summary, analyze_account, get_insights ) # 获取所有账号汇总 summary = get_summary() print(f"总可用额度: ${summary['total_available']:,.2f}") print(f"昨日总消耗: ${summary['total_yesterday_spend']:,.2f}") # 全方位账号分析 analysis = analyze_account( "", date_range={"start_date": "2026-03-01", "end_date": "2026-03-13"}, include_country_breakdown=True )

Facebook from scripts.facebook_ads import ( get_summary, analyze_account, get_insights, get_account_benchmarks ) # 获取所有账号汇总 summary = get_summary() print(f"总可用额度: ${summary['total_available']:,.2f}") print(f"昨日总消耗: ${summary['total_yesterday_spend']:,.2f}") # 全方位账号分析 analysis = analyze_account( "act_586806297825353", date_range={"since": "2026-03-01", "until": "2026-03-13"}, include_country_breakdown=True )

环境变量配置 在 ~/.openclaw/openclaw.json 的 env 中配置： { "env": { "facebook_access_token": "EAAC...", "tiktok_access_token": "...", "tiktok_app_id": "..." } }

注意事项 Facebook Access Token 有过期时间，长期使用需要定期刷新 TikTok 需要 Access Token 和 App ID 金额单位为美元 (USD) API 有调用频率限制，建议合理控制请求频率