介绍
# Meta Ads API
## 描述
与 Meta (Facebook) 广告 API 的完全读/写集成，用于管理广告系列、广告组、广告以及访问效果洞察/指标。
## 设置
### 环境变量
- `META_ACCESS_TOKEN` - Meta 访问令牌（用户访问令牌或系统用户令牌） - `META_AD_ACCOUNT_ID` - 您的广告账户 ID（数字，不带 `act_` 前缀）
### 所需权限
- `ads_read` - 广告数据的读取权限 - `ads_management` - 创建、编辑和删除广告
### 令牌类型
**用户访问令牌** - 短期：约 2 小时 - 可延长至 60-90 天 - 通过 OAuth 流程或 Graph API 资源管理器获取
**系统用户令牌** - 无过期时间 - 推荐用于生产/自动化访问 - 在商务管理平台 中创建
### 身份验证
所有请求都需要将访问令牌作为查询参数或请求头携带：
``` Authorization: Bearer $META_ACCESS_TOKEN Content-Type: application/json ```
或者作为查询参数： ``` ?access_token=$META_ACCESS_TOKEN ```
## API 参考
基础 URL：`https://graph.facebook.com/v25.0/`
**重要：** 广告账户 ID 在 API 调用中必须加上 `act_` 前缀（例如 `act_123456789`）。
### 广告账户
#### 获取广告账户信息
```bash curl "https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID?fields=name,account_status,currency,timezone_name,amount_spent" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" ```
---
### 广告系列
#### 列出广告系列
```bash curl "https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/campaigns?fields=id,name,status,objective,daily_budget,lifetime_budget,created_time" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" ```
#### 获取单个广告系列
```bash curl "https://graph.facebook.com/v25.0/{CAMPAIGN_ID}?fields=id,name,status,objective,daily_budget,lifetime_budget,created_time,updated_time" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" ```
#### 创建广告系列
```bash curl -X POST "https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/campaigns" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "My Campaign", "objective": "OUTCOME_TRAFFIC", "status": "PAUSED", "special_ad_categories": [] }' ```
#### 更新广告系列
```bash curl -X POST "https://graph.facebook.com/v25.0/{CAMPAIGN_ID}" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Updated Campaign Name", "status": "ACTIVE" }' ```
#### 暂停广告系列
```bash curl -X POST "https://graph.facebook.com/v25.0/{CAMPAIGN_ID}" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "status": "PAUSED" }' ```
#### 删除广告系列
```bash curl -X DELETE "https://graph.facebook.com/v25.0/{CAMPAIGN_ID}" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" ```
---
### 广告组
#### 列出广告组
```bash curl "https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/adsets?fields=id,name,status,campaign_id,daily_budget,lifetime_budget,targeting,optimization_goal" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" ```
#### 获取单个广告组
```bash curl "https://graph.facebook.com/v25.0/{ADSET_ID}?fields=id,name,status,campaign_id,daily_budget,lifetime_budget,targeting,optimization_goal,bid_amount,billing_event" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" ```
#### 创建广告组
```bash curl -X POST "https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/adsets" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "My Ad Set", "campaign_id": "{CAMPAIGN_ID}", "daily_budget": 5000, "billing_event": "IMPRESSIONS", "optimization_goal": "LINK_CLICKS", "bid_amount": 200, "targeting": { "geo_locations": { "countries": ["US"] }, "age_min": 18, "age_max": 65 }, "status": "PAUSED" }' ```
**注意：** 预算值以美分为单位（例如，5000 = $50.00）。
#### 更新广告组
```bash curl -X POST "https://graph.facebook.com/v25.0/{ADSET_ID}" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Updated Ad Set Name", "daily_budget": 10000, "status": "ACTIVE" }' ```
#### 暂停广告组
```bash curl -X POST "https://graph.facebook.com/v25.0/{ADSET_ID}" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "status": "PAUSED" }' ```
#### 删除广告组
```bash curl -X DELETE "https://graph.facebook.com/v25.0/{ADSET_ID}" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" ```
---
### 广告
#### 列出广告
```bash curl "https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/ads?fields=id,name,status,adset_id,campaign_id,creative,created_time" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" ```
#### 获取单个广告
```bash curl "https://graph.facebook.com/v25.0/{AD_ID}?fields=id,name,status,adset_id,campaign_id,creative,tracking_specs,created_time,updated_time" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" ```
#### 创建广告
```bash curl -X POST "https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/ads" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "My Ad", "adset_id": "{ADSET_ID}", "creative": { "creative_id": "{CREATIVE_ID}" }, "status": "PAUSED" }' ```
#### 创建附带内联创意的广告
```bash curl -X POST "https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/ads" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "My Ad", "adset_id": "{ADSET_ID}", "creative": { "object_story_spec": { "page_id": "{PAGE_ID}", "link_data": { "link": "https://example.com", "message": "Check out our website!", "name": "Example Site", "call_to_action": { "type": "LEARN_MORE" } } } }, "status": "PAUSED" }' ```
#### 更新广告
```bash curl -X POST "https://graph.facebook.com/v25.0/{AD_ID}" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Updated Ad Name", "status": "ACTIVE" }' ```
#### 暂停广告
```bash curl -X POST "https://graph.facebook.com/v25.0/{AD_ID}" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "status": "PAUSED" }' ```
#### 删除广告
```bash curl -X DELETE "https://graph.facebook.com/v25.0/{AD_ID}" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" ```
---
### 广告创意
#### 列出广告创意
```bash curl "https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/adcreatives?fields=id,name,object_story_spec,thumbnail_url" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" ```
#### 创建广告创意
```bash curl -X POST "https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/adcreatives" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "My Creative", "object_story_spec": { "page_id": "{PAGE_ID}", "link_data": { "link": "https://example.com", "message": "Ad copy text here", "name": "Headline", "description": "Description text", "call_to_action": { "type": "SHOP_NOW" } } } }' ```
---
### 洞察（效果指标）
#### 获取账户级别洞察
```bash curl "https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/insights?fields=spend,impressions,clicks,reach,cpc,cpm,ctr&date_preset=last_30d" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" ```
#### 获取广告系列洞察
```bash curl "https://graph.facebook.com/v25.0/{CAMPAIGN_ID}/insights?fields=spend,impressions,clicks,reach,frequency,cpc,cpm,ctr,actions&date_preset=last_7d" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" ```
#### 获取广告组洞察
```bash curl "https://graph.facebook.com/v25.0/{ADSET_ID}/insights?fields=spend,impressions,clicks,reach,cpc,cpm,ctr,actions&date_preset=last_7d" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" ```
#### 获取广告洞察
```bash curl "https://graph.facebook.com/v25.0/{AD_ID}/insights?fields=spend,impressions,clicks,reach,cpc,cpm,ctr,actions&date_preset=last_7d" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" ```
#### 获取自定义日期范围洞察
```bash curl "https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/insights?fields=spend,impressions,clicks,cpc,cpm,ctr&time_range={\"since\":\"2026-01-01\",\"until\":\"2026-01-31\"}" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" ```
#### 获取细分维度洞察
```bash curl "https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/insights?fields=spend,impressions,clicks,cpc&breakdowns=age,gender&date_preset=last_7d" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" ```
#### 获取每日洞察
```bash curl "https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/insights?fields=spend,impressions,clicks&time_increment=1&date_preset=last_7d" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" ```
#### 获取带归因窗口的洞察
```bash curl "https://graph.facebook.com/v25.0/{CAMPAIGN_ID}/insights?fields=spend,actions,action_values&action_attribution_windows=[\"7d_click\",\"1d_view\"]&date_preset=last_7d" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" ```
## 广告目标
| 目标 | 描述 | |-----------|-------------| | `OUTCOME_AWARENESS` | 品牌知名度和覆盖人数 | | `OUTCOME_ENGAGEMENT` | 帖子互动、主页赞、活动响应 | | `OUTCOME_TRAFFIC` | 为网站或应用引流 | | `OUTCOME_LEADS` | 潜在客户挖掘 | | `OUTCOME_APP_PROMOTION` | 应用安装和互动 | | `OUTCOME_SALES` | 转化和目录销售 |
**旧版目标（仍支持）：** - `BRAND_AWARENESS`, `REACH`, `LINK_CLICKS`, `POST_ENGAGEMENT`, `VIDEO_VIEWS`, `LEAD_GENERATION`, `CONVERSIONS`, `APP_INSTALLS`
## 定向选项
### 地理定向
```json { "geo_locations": { "countries": ["US", "CA"], "regions": [{"key": "4081"}], "cities": [{"key": "2420379", "radius": 25, "distance_unit": "mile"}], "zips": [{"key": "US:90210"}] } } ```
### 人口统计定向
```json { "age_min": 25, "age_max": 54, "genders": [1, 2] } ```
性别值：`1` = 男性，`2` = 女性
### 兴趣定向
```json { "flexible_spec": [{ "interests": [{"id": "6003139266461", "name": "Technology"}] }] } ```
## 预算类型
| 类型 | 描述 | |------|-------------| | `daily_budget` | 每日最高花费（单位：分） | | `lifetime_budget` | 广告系列/广告组运行期间的总预算（单位：分） |
**重要：** 预算值以最小货币单位为单位（美元为美分）。示例：`5000` = $50.00
## 状态值
| 状态 | 描述 | |--------|-------------| | `ACTIVE` | 当前正在运行 | | `PAUSED` | 手动暂停 | | `DELETED` | 软删除 | | `ARCHIVED` | 已归档，未运行 |
## 可用指标
| 指标 | 描述 | |--------|-------------| | `spend` | 总花费金额 | | `impressions` | 广告展示次数 | | `clicks` | 广告点击次数 | | `reach` | 查看广告的唯一用户数 | | `frequency` | 每人查看广告的平均次数 | | `cpc` | 单次点击成本 | | `cpm` | 千次展示成本 | | `ctr` | 点击率（点击次数 / 展示次数） | | `cpp` | 千人覆盖成本 | | `actions` | 总操作数（转化），按类型细分 | | `action_values` | 转化价值 | | `conversions` | 转化次数 | | `cost_per_action_type` | 按类型计算的单次操作成本 |
## 归因窗口
| 窗口 | 描述 | |--------|-------------| | `1d_click` | 1 天点击归因 | | `7d_click` | 7 天点击归因（默认） | | `28d_click` | 28 天点击归因 | | `1d_view` | 1 天浏览归因 |
**注意：** 截至 2026 年 1 月，7 天浏览 (`7d_view`) 和 28 天浏览 (`28d_view`) 归因窗口已被移除。仅保留 `1d_view` 用于浏览归因。
## 细分维度
| 细分 | 描述 | |-----------|-------------| | `age` | 年龄范围（18-24, 25-34 等） | | `gender` | 男性、女性、未知 | | `placement` | 广告展示位置（信息流、快拍等） | | `device_platform` | 设备类型（移动端、桌面端） | | `platform_position` | 平台内的位置 | | `publisher_platform` | Facebook、Instagram、Audience Network | | `country` | 查看者所在国家 | | `region` | 查看者所在地区/州 |
## 日期预设
| 预设 | 描述 | |--------|-------------| | `today` | 仅今天 | | `yesterday` | 仅昨天 | | `this_month` | 本月 | | `last_month` | 上月 | | `last_7d` | 过去 7 天 | | `last_14d` | 过去 14 天 | | `last_28d` | 过去 28 天 | | `last_30d` | 过去 30 天 | | `last_90d` | 过去 90 天 |
## 分页
API 使用基于游标的分页。响应中包含带有游标的 `paging` 对象。
```json { "data": [...], "paging": { "cursors": { "before": "abc123", "after": "xyz789" }, "next": "https://graph.facebook.com/v25.0/..." } } ```
要获取下一页：
```bash curl "https://graph.facebook.com/v25.0/act_$META_AD_ACCOUNT_ID/campaigns?fields=id,name&after={AFTER_CURSOR}" \ -H "Authorization: Bearer $META_ACCESS_TOKEN" ```
**限制：** - 默认：每页 25 条记录 - 最大：每页 5000 条记录（使用 `limit` 参数）
## 速率限制
速率限制按广告账户计算，公式如下：
``` Call Limit = 60 + (400 × Active Ads) - (0.001 × API Errors) ```
- 最低：每小时 60 次调用 - 随着活跃广告数量的增加而增加 - 随 API 错误的发生而减少
**处理速率限制：** - 检查 `X-Business-Use-Case-Usage` 请求头以获取当前使用情况 - 收到 429 响应时实施指数退避 - 从 1 秒延迟开始，每次重试加倍（最多重试 5 次）
## 令牌管理
### 延长用户访问令牌
短期用户令牌（约 2 小时）可以交换为长期令牌（60-90 天）：
```bash curl "https://graph.facebook.com/v25.0/oauth/access_token?grant_type=fb_exchange_token&client_id={APP_ID}&client_secret={APP_SECRET}&fb_exchange_token={SHORT_LIVED_TOKEN}" ```
响应： ```json { "access_token": "long_lived_token_here", "token_type": "bearer", "expires_in": 5184000 } ```
### 调试令牌
检查令牌的有效性和权限：
```bash curl "https://graph.facebook.com/v25.0/debug_token?input_token={TOKEN_TO_CHECK}&access_token={APP_ID}|{APP_SECRET}" ```
### 推荐：系统用户令牌
对于生产用途，请在商务管理平台中创建系统用户：
1. 前往商务设置 (Business Settings) > 用户 (Users) > 系统用户 (System Users) 2. 创建一个具有“管理员” 角色的新系统用户 3. 将广告账户分配给该系统用户 4. 生成具有 `ads_read` 和 `ads_management` 权限的令牌
系统用户令牌不会过期。
## 更新日志
### v1.0.0
- 初始版本，支持完全读/写访问 - 广告账户：获取信息 - 广告系列：列表、获取、创建、更新、暂停、删除 - 广告组：列表、获取、创建、更新、暂停、删除，支持定向 - 广告：列表、获取、创建、更新、暂停、删除 - 广告创意：列表、创建 - 洞察：账户/广告系列/广告组/广告级别，包含所有指标 - 支持细分维度、日期范围和归因窗口 - 广告目标和定向文档 - 预算类型（每日/终生），以分为单位 - 分页文档 - 速率限制和令牌管理