Meta Ads API 技能（完整版）

概述

该技能使智能体能够通过 Meta 营销 API 读取、创建和管理 Meta（Facebook/Instagram）广告系列。

基础配置

API 基础 URL

https://graph.facebook.com/v19.0/

必需输入项

• access_token
• ad_account_id（格式：act_）

认证方式

方法

在查询参数或请求头中使用访问令牌：

Authorization: Bearer 

或

?access_token=

所需权限

核心实体

• 广告系列（Campaign）→ 顶层目标
• 广告组（Ad Set）→ 预算 + 受众定向
• 广告（Ad）→ 创意内容（图片/视频 + 文案）

读取操作（主要）

1. 获取广告系列

端点

GET /act_/campaigns

示例

GET /act_/campaigns?fields=id,name,status,objective

2. 获取广告组

GET /act_/adsets?fields=id,name,campaign_id,status,daily_budget

3. 获取广告

GET /act_/ads?fields=id,name,adset_id,status

4. 广告系列数据洞察

GET //insights?fields=impressions,clicks,spend,ctr,cpc

5. 账户级数据洞察

GET /act_/insights?fields=impressions,clicks,spend&date_preset=last_7d

6. 时间范围筛选

time_range={'since':'2024-01-01','until':'2024-01-31'}

7. 状态筛选

effective_status=['ACTIVE']

8. 数据层级

level=campaign | adset | ad

分页处理

响应中包含以下字段：

paging.next

智能体规则

• 持续调用 paging.next 直至无更多结果
• 达到安全上限时停止（例如：最多 10 页）

写入操作

9. 创建广告系列

POST /act_/campaigns

请求体（Payload）：

name=My Campaign
objective=CONVERSIONS
status=PAUSED
special_ad_categories=[]

10. 创建广告组

POST /act_/adsets

请求体（Payload）：

name=Ad Set 1
daily_budget=1000
billing_event=IMPRESSIONS
optimization_goal=REACH
campaign_id=
targeting={"geo_locations":{"countries":["MA"]}}
status=PAUSED

11. 创建广告创意

POST /act_/adcreatives

请求体（Payload）：

name=Creative 1
object_story_spec={"page_id":"","link_data":{"message":"Hello","link":"https://example.com"}}

12. 创建广告

POST /act_/ads

请求体（Payload）：

name=Ad 1
adset_id=
creative={"creative_id":""}
status=PAUSED

13. 更新广告系列状态

POST /?status=PAUSED

数据洞察指标

常用字段：

• impressions（展示次数）
• clicks（点击次数）
• spend（花费）
• ctr（点击率）
• cpc（每次点击费用）
• conversions（转化次数，需已配置）

错误处理

速率限制

• 遵守 HTTP 429 状态码
• 采用指数退避策略重试
• 尽可能使用批量请求

智能体规则（重要）

安全性

• 所有广告系列默认以 PAUSED 状态创建
• 绝不暴露 access token
• 使用前必须校验所有 ID 的有效性

效率性

• 缓存广告系列列表
• 避免重复调用同一 API
• 在可行情况下优先使用 insights 接口，而非原始数据接口

可靠性

• 失败请求最多重试 3 次
• 记录所有 API 响应
• 检测并处理空响应

分析逻辑（智能体智能）

识别表现不佳的广告

• 高花费 + 低 CTR → 标记为异常
• 高 CPC → 建议暂停

识别优质广告

• 高 CTR + 低 CPC → 扩大预算

示例规则

IF spend > 50 AND ctr < 0.5%
THEN mark campaign as underperforming

典型请求流程

1. 获取广告系列列表
2. 获取对应数据洞察
3. 分析关键指标
4. 决策后续动作（如暂停、扩量等）
5. 执行广告系列状态更新（暂停/扩量）

最佳实践

• 使用长期有效的访问令牌
• 优先使用系统用户（Business Manager 中配置）
• 监控访问令牌有效期
• 始终使用带版本号的 API（v19.0 或更高版本）

注意事项

• 数据洞察存在延迟，非实时数据
• 转化追踪需依赖 Facebook Pixel 或 CAPI
• 部分功能需通过应用审核（App Review）后方可使用