Ads Data Get

SKILL.md

---
name: ads-data-get
description: 广告平台数据查询工具。获取 Facebook、TikTok 等广告账号的余额、消耗数据，支持多层级分析（Account/Campaign/AdSet/Ad）和国家维度 breakdown。适用场景：(1) 查询广告账号余额或可用额度，(2) 查询昨日消耗，(3) 获取广告账号汇总报告，(4) 多维度数据分析，(5) ROAS/CTR/CPM/CVR 指标计算。
---

# Ads Data Get

广告平台数据查询工具，支持 Facebook、TikTok 平台。

## 支持平台

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

---

## TikTok 广告数据分析

### 1. 快速汇总报告

```bash
# 获取所有账号余额/消耗汇总
python scripts/tiktok_ads.py

# JSON 格式输出
python scripts/tiktok_ads.py --json
```

### 2. 单账号全方位分析

```bash
# 分析指定账号（最近 7 天）
python scripts/tiktok_ads.py --analyze --account <advertiser_id>

# 指定时间范围
python scripts/tiktok_ads.py --analyze --account <advertiser_id> --since 2026-03-01 --until 2026-03-13

# 分析最近 30 天
python scripts/tiktok_ads.py --analyze --account <advertiser_id> --days 30
```

### 3. 单层级数据查询

```bash
# Campaign 级别数据
python scripts/tiktok_ads.py --account <advertiser_id> --level campaign --json

# AdGroup 级别数据
python scripts/tiktok_ads.py --account <advertiser_id> --level adgroup --json

# Ad 级别数据
python scripts/tiktok_ads.py --account <advertiser_id> --level ad --json

# 按国家分组
python scripts/tiktok_ads.py --account <advertiser_id> --level account --breakdown country --json
```

---

## Facebook 广告数据分析

### 1. 快速汇总报告

```bash
# 获取所有账号余额/消耗汇总
python scripts/facebook_ads.py

# JSON 格式输出
python scripts/facebook_ads.py --json
```

### 2. 单账号全方位分析

```bash
# 分析指定账号（最近 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
```

### 3. 单层级数据查询

```bash
# 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

```python
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(
    "<advertiser_id>",
    date_range={"start_date": "2026-03-01", "end_date": "2026-03-13"},
    include_country_breakdown=True
)
```

### Facebook

```python
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` 中配置：

```json
{
  "env": {
    "facebook_access_token": "EAAC...",
    "tiktok_access_token": "...",
    "tiktok_app_id": "..."
  }
}
```

---

## 注意事项

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