Facebook 市场营销 API 概述

Facebook 市场营销 API (Marketing API) 是一组 Graph API 端点，允许开发者以编程方式创建、管理和优化 Facebook 广告系列。通过此 API，您可以自动化广告投放流程，集成广告数据到自有系统，以及大规模管理账户。

核心概念

• 广告账户 (Ad Account) — 在 Facebook 上投放广告的实体，以 act_{id} 格式标识
• 广告系列 (Campaign) — 最高层级，定义业务目标（如流量、转化）
• 广告组 (Ad Set) — 中间层级，包含预算、排期、定位和竞价设置
• 广告 (Ad) — 最低层级，包含要展示的创意内容
• 广告创意 (Ad Creative) — 定义广告的布局和内容（图片、视频、文案）

API 版本：本文档使用 v25.0 端点。所有示例中的 <AD_ACCOUNT_ID>、<ACCESS_TOKEN> 等需替换为实际值。

1. 开始使用营销 API

要使用市场营销 API，你必须遵循关键步骤来设置环境并获得 API 功能的访问权限。

广告帐户要求

必须拥有活跃广告账户。在 Meta 广告管理工具中可找到广告账户编号：登录 Facebook → 广告管理工具 → 设置 → 账户概览。

Meta 开发者账户 & 创建应用

详情参阅 注册成为 Meta 开发者及 创建应用。

授权和认证

请参见 授权 了解验证用户和应用并授予权限的流程。参见 身份验证 了解获取、扩展和更新访问口令的方法。

继续学习

• 创建广告系列
• 管理广告系列
• 优化广告系列

2. 授权

访问等级更名："标准访问级别"现为受限访问级别，"高级访问级别"现为完全访问级别。
完全访问的资格要求已从过去 15 天 1,500 次调用降至 500 次。

授权流程验证将访问市场营销 API 的用户和应用，并向其授予权限。

市场营销 API 访问层级

获得完整访问权限

• 过去 15 天内成功至少 500 次营销 API 调用
• 过去 500 次调用中错误率低于 15%

管理其他用户的广告时，使用 scope 参数请求 ads_management 或 ads_read 权限：

https://www.facebook.com/v25.0/dialog/oauth?
  client_id=<YOUR_APP_ID>&redirect_uri=<YOUR_URL>&scope=ads_management

公司验证

通过公司验证流程验证公司实体身份。

3. 身份验证

每个营销 API 调用都需要一个访问口令作为参数。

用户访问口令

使用 图谱 API 探索工具获取：选择应用 → 用户口令 → 添加权限（ads_read 或 ads_management）→ 生成访问口令。

通过 访问口令调试工具可调试和延长口令期限。

系统用户访问口令

在 Meta Business Suite 中创建，用于服务器到服务器交互。不会过期。详情参阅 系统用户。

授权码流程

# 用户允许后获得授权码
http://YOUR_URL?code=<AUTHORIZATION_CODE>

# 换取访问口令
https://graph.facebook.com/v25.0/oauth/access_token?
  client_id=<YOUR_APP_ID>&redirect_uri=<YOUR_URL>
  &client_secret=<YOUR_APP_SECRET>&code=<AUTHORIZATION_CODE>

安全最佳实践

• 使用 HTTPS 安全传输访问口令
• 利用加密数据库存储口令
• 仅请求必需的权限
• 定期刷新口令，设置处理过期的机制

4. 基本广告创建

使用营销 API 创建广告需要设置广告系列、广告组和广告创意。主要端点包括 campaigns、adsets、adcreatives 和 ads。

campaigns 端点

curl -X POST \
  https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/campaigns \
  -F 'name=My Campaign' \
  -F 'objective=LINK_CLICKS' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>'

adsets 端点

curl -X POST \
  https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adsets \
  -F 'name=My Ad Set' \
  -F 'campaign_id=<CAMPAIGN_ID>' \
  -F 'daily_budget=1000' \
  -F 'targeting={"geo_locations":{"countries":["US"]}}' \
  -F 'access_token=<ACCESS_TOKEN>'

ads 端点

curl -X POST \
  https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/ads \
  -F 'name=My Ad' \
  -F 'adset_id=<AD_SET_ID>' \
  -F 'creative={"creative_id": "<CREATIVE_ID>"}' \
  -F 'status=ACTIVE' \
  -F 'access_token=<ACCESS_TOKEN>'

5. 创建广告系列

向 /act_<AD_ACCOUNT_ID>/campaigns 发送 POST 请求。

curl -X POST \
  https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/campaigns \
  -F 'name=My Campaign' \
  -F 'objective=LINK_CLICKS' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>'

必要参数

6. 创建广告组

创建广告系列后，创建广告组以包含竞价、定位和预算信息。

curl -X POST \
  https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adsets \
  -F 'name=My Ad Set' \
  -F 'campaign_id=<CAMPAIGN_ID>' \
  -F 'daily_budget=1000' \
  -F 'targeting={"geo_locations":{"countries":["US"]}}' \
  -F 'access_token=<ACCESS_TOKEN>'

7. 创建广告创意

广告创意定义广告的视觉和文本元素。向 /act_<AD_ACCOUNT_ID>/adcreatives 发送 POST 请求。

curl -X POST \
  https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adcreatives \
  -F 'name=Sample Creative' \
  -F 'object_story_spec={
      "page_id": "<PAGE_ID>",
      "link_data": {
        "message": "Check out our new product!",
        "link": "https://www.example.com/product",
        "caption": "Our New Product",
        "picture": "https://www.example.com/image.jpg",
        "call_to_action": {
          "type": "SHOP_NOW"
        }
      }
    }' \
  -F 'access_token=<ACCESS_TOKEN>'

8. 创建广告

将现有广告组和广告创意合并为广告。

curl -X POST \
  https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/ads \
  -F 'name=My Ad' \
  -F 'adset_id=AD_SET_ID' \
  -F 'creative={"creative_id": "<CREATIVE_ID>"}' \
  -F 'status=ACTIVE' \
  -F 'access_token=<ACCESS_TOKEN>'

9. 广告系列管理

修改广告系列

curl -X POST \
  https://graph.facebook.com/v25.0/<CAMPAIGN_ID> \
  -F 'objective=CONVERSIONS' \
  -F 'daily_budget=2000' \
  -F 'status=ACTIVE' \
  -F 'access_token=<ACCESS_TOKEN>'

暂停 / 归档 / 删除

# 暂停
curl -X POST https://graph.facebook.com/v25.0/<CAMPAIGN_ID> \
  -F 'status=PAUSED' -F 'access_token=<ACCESS_TOKEN>'

# 归档
curl -X POST https://graph.facebook.com/v25.0/<CAMPAIGN_ID> \
  -F 'status=ARCHIVED' -F 'access_token=<ACCESS_TOKEN>'

# 删除（不可撤销）
curl -X DELETE https://graph.facebook.com/v25.0/<CAMPAIGN_ID> \
  -F 'access_token=<ACCESS_TOKEN>'

警告：删除操作无法撤销。删除前请仔细检查广告系列编号。

10. 广告优化基础知识

customaudiences 端点

curl -X POST \
  https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/customaudiences \
  -F 'name=My Custom Audience' \
  -F 'subtype=CUSTOM' \
  -F 'access_token=<ACCESS_TOKEN>'

insights 端点

curl -X GET \
  https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/insights \
  -F 'fields=impressions,clicks,spend' \
  -F 'time_range={"since":"2023-01-01","until":"2023-12-31"}' \
  -F 'access_token=<ACCESS_TOKEN>'

11. 监测和分析

使用 Insights API 监控广告系列表现。

curl -X GET \
  https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/insights \
  -F 'fields=impressions,clicks,spend,ctr,cpc' \
  -F 'time_range={"since":"2023-01-01","until":"2023-12-31"}' \
  -F 'level=campaign' \
  -F 'access_token=<ACCESS_TOKEN>'

关键指标

• CTR — 点击率，衡量广告吸引力
• CPC — 单次点击费用
• ROAS — 广告花费回报
• Impressions — 展示次数

成效驱动的优化

持续监控表现数据，发现趋势并做出调整。高互动但低转化时，尝试不同 CTA 或改善定位。特定人群数据表现更佳时，重新分配预算。

12. 优化建议

受众定位

• 使用自定义受众：基于网站访客或应用用户创建受众，覆盖已熟悉您服务的用户
• 细分受众：使用人口筛选器（年龄、性别、位置、兴趣）提高精准度
• 类似受众：创建 lookalike audiences 触达新潜在客户

预算分配

• 明确目标并相应分配预算
• 根据表现调整预算，将资金转移到表现优异的领域
• 设置每日预算控制开支

广告创意

• 投资高品质图片和视频，优化桌面和移动设备
• 持续 A/B 测试不同创意、标题和 CTA
• 使用动态创意自动展示最佳版本

实时优化

• 使用 Insights API 收集实时数据
• 广告系列中期调整定位参数
• 设置定期报告面板监控表现

转化 API

在广告主服务器到 Meta 系统之间建立连接，优化广告定位、降低单次成效费用和衡量成效。参阅 转化 API 文档。

Ad Account（广告账户）

代表在 Facebook 上创建和管理广告的业务实体。多人可以以不同访问级别管理一个账户。

限制

关键字段

常见错误

Campaign（广告系列）

最高级别组织结构，代表单一业务目标。所有广告系列必须指定 special_ad_categories 字段（v7.0+）。

关键字段

创建（POST）

curl -X POST \
  -F 'name="My campaign"' \
  -F 'objective="OUTCOME_TRAFFIC"' \
  -F 'status="PAUSED"' \
  -F 'special_ad_categories=[]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/campaigns

子端点

Ad Set（广告组）

共享相同预算、排期、竞价和定位数据的广告组。限制：普通账户最多 5,000 个，批量账户最多 10,000 个。

关键字段

创建

curl -X POST \
  -F 'name="My First Adset"' \
  -F 'lifetime_budget=20000' \
  -F 'campaign_id="<AD_CAMPAIGN_ID>"' \
  -F 'bid_amount=100' \
  -F 'billing_event="LINK_CLICKS"' \
  -F 'optimization_goal="LINK_CLICKS"' \
  -F 'targeting={"geo_locations":{"countries":["US"]}}' \
  -F 'status="PAUSED"' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adsets

Ad（广告）

包含要展示的信息，与广告组关联。同组内广告共享预算、排期和定位。

读取

# 按广告 ID
curl -X GET -d 'fields="id,name"' -d 'access_token=<TOKEN>' \
  https://graph.facebook.com/v25.0/<AD_ID>/

# 按广告账户
curl -G -d "fields=name" -d "access_token=<TOKEN>" \
  "https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/ads"

创建

curl -X POST \
  -F 'name="My Ad"' \
  -F 'adset_id="<AD_SET_ID>"' \
  -F 'creative={"creative_id": "<CREATIVE_ID>"}' \
  -F 'status="PAUSED"' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/ads

关键字段

Ad Creative（广告创意）

定义广告的布局和内容。可独立创建或作为广告组的一部分。

创建

curl -X POST \
  -F 'name=Sample Creative' \
  -F 'object_story_spec={
      "page_id": "<PAGE_ID>",
      "link_data": {
        "message": "Check out our new product!",
        "link": "https://www.example.com/product",
        "caption": "Our New Product",
        "picture": "https://www.example.com/image.jpg",
        "call_to_action": {"type": "SHOP_NOW"}
      }
    }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adcreatives

关键参数

文本限制

Business（商务管理平台）

代表 Facebook 上的一个业务实体。

关键字段

创建

POST /{user_id}/businesses -F 'name=My Business'

子端点

Ads Pixel（广告像素代码）

Facebook 像素是一段 JavaScript 代码，放置在网站各页面上，用于捕获网站意图并创建网站自定义受众。

关键字段

创建

POST /v25.0/act_<AD_ACCOUNT_ID>/adspixels -F 'name=My WCA Pixel'

Custom Audience（自定义受众）

2025 年 9 月 2 日起：Meta 将限制可能暗示健康状况、财务状况等的自定义受众。

关键字段

System User（系统用户）

用于服务器到服务器交互的账户。系统用户访问口令不会过期。每个商务平台有数量上限（有限访问=1，完全访问=10）。

创建

POST /{business_id}/system_users
-F 'name=My System User'
-F 'role=ADMIN'

可用角色：ADMIN, EMPLOYEE, FINANCE_EDITOR, FINANCE_ANALYST, ADS_RIGHTS_REVIEWER, DEVELOPER。

子端点

Insights（成效分析）

提供广告表现指标。支持同步查询和异步报告创建。

iOS 14.5 警告：无法跨 iOS 14.5 和非 iOS 14.5 广告系列聚合非内联转化指标。

同步查询

curl -X GET -G \
  -d 'fields="impressions"' \
  -d 'breakdown="publisher_platform"' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v25.0/<AD_SET_ID>/insights

异步报告

POST /act_{ad_account_id}/insights