Version | Path | 上线日期 | 弃用日期 | 生命周期结束日期 |
---|---|---|---|---|
12.0 | /12/ | 2022 年 10 月 27 日 | 待定 | 待定 |
11.0 | /11/ | 2022 年 3 月 31 日 | 待定 | 待定 |
10.0 | /10/ | 2021 年 8 月 31 日 | 2022 年 3 月 31 日 | 2022 年 10 月 27 日 |
9.0 | /9/ | 2021 年 3 月 2 日 | 2021 年 8 月 31 日 | 2022 年 3 月 31 日 |
8.0 | /8/ | 2020 年 9 月 8 日 | 2021 年 3 月 2 日 | 2021 年 8 月 31 日 |
7.0 | /7/ | 2020 年 3 月 3 日 | 2020 年 9 月 1 日 | 2021 年 3 月 2 日 |
6.0 | /6/ | 2019 年 8 月 28 日 | 2020 年 3 月 3 日 | 2020 年 9 月 1 日 |
5.0 | /5/ | 2019 年 2 月 28 日 | 2019 年 8 月 28 日 | 2020 年 3 月 3 日 |
4.0 | /4/ | 2018 年 8 月 28 日 | 2019 年 2 月 28 日 | 2019 年 8 月 28 日 |
3.0 | /3/ | 2018 年 2 月 1 日 | 2018 年 8 月 28 日 | 2019 年 2 月 28 日 |
2.0 | /2/ | 2017 年 7 月 10 日 | 2018 年 2 月 1 日 | 2018 年 8 月 1 日 |
1.0 | /1/ | 2016 年 3 月 31 日 | 2017 年 7 月 7 日 | 2018 年 1 月 10 日 |
0.0 | /0/ | 2013 年 2 月 21 日 | 不适用 | 2016 年 10 月 31 日 |
概述
- 从 API 请求/响应中移除某个参数
- 修改任何参数或 endpoint 的名称
- 值的表示形式发生变化(preview_url → card_uri)
- endpoint 行为发生变化(例如,异步 vs 同步统计)
- 添加/更改可选或必填参数(例如,将 name 设为请求中的必填字段)
版本策略
- 所有破坏性变更都将归入一个新版本
- 每当宣布新版本时,现有版本的弃用期为 6 个月
- 任何时间点,API 将同时接受来自两个版本的请求,但其中较旧的版本不再受支持
- 为加速新产品的采用,这些产品将持续发布(不受版本节奏限制)
-
所有 API 响应都会包含一个
x-current-api-version
,其值为当前 API 版本;此外,调用任何已弃用的 API endpoint 时还会返回x-api-warn
头。
v9
注意: 自本次发布起,Ads API 的第 7 版(v7)已结束生命周期,不再可用。
v8
v7
v6
v5
accounts/:account_id/account_media
endpoint 已被弃用。
与以往版本一样,将提供 6 个月的过渡期以迁移到 v5。自 2019-08-28 起,Ads API 的第 4 版将不再可用。我们鼓励所有合作伙伴尽快迁移到最新的 API 版本,以避免任何服务中断。Ads API 的第 3 版已达到生命周期终点,现已停止提供。
新增
CAMPAIGN
、FUNDING_INSTRUMENT
、LINE_ITEM
、MEDIA_CREATIVE
和 PROMOTED_TWEET
。
MEDIA_CREATIVE
统计
X Ads API 的分析 endpoints 现已为 Media Creative 实体提供度量。Media Creative 是在 X Audience Platform 上推广 in-stream 广告或图片的方式。X Ads UI 会在“In-stream videos”和“Display creatives”选项卡下显示 Media Creative 度量。同步synchronous和异步asynchronous分析 endpoints 现均支持 MEDIA_CREATIVE
实体枚举。
获取多个 card
在v3 发布中提供按 card URI 检索单个 card 的基础上进一步改进,现在可通过 GET accounts/:account_id/cards/all endpoint 获取多个 card。你可以在单个请求中检索最多 200 个 card,而无需为每个 card 分别发起请求。
需要注意两点:
- URL 路径现为
accounts/:account_id/cards/all
(先前路径已不可用)。此变更旨在与按 ID 检索 card 的 endpoint 保持一致。 - 必填请求参数现命名为 card_uris(复数)。
- GET accounts/:account_id/line_item_apps
- GET accounts/:account_id/media_creatives
- GET accounts/:account_id/promoted_accounts
- GET accounts/:account_id/preroll_call_to_actions
已更改
draft_only
| with_draft
| |
Network Activation Duration 定向
X Ads API 修复了一个显示问题:在添加 Network Activation Duration 定向后,响应中的定向 type 会带有 _IN_SEC 后缀。由于 Network Activation Duration 始终以月为单位表示,出现“秒”的引用会引发混淆。此修复使表示方式更一致并降低了困惑。
| v4 | v5 |
| :--- | :--- | :--- |
| NETWORK_ACTIVATION_DURATION_IN_SEC
| NETWORK_ACTIVATION_DURATION
| |
总计数与游标
在 v5 中,with_total_count 和 cursor 是互斥的。在同一请求中同时指定二者将返回 EXCLUSIVE_PARAMETERS 错误代码。在 v5 之前,当指定了 cursor 时,with_total_count 会被忽略。此更改使这种关系更加明确。
已移除
- 在 v4 中,我们已宣布 cards 的 preview_url 响应参数始终为 null。本次迁移的最后一步是从所有 cards 的响应中删除 preview_url。
- 将从以下资源中移除 account_id 响应属性,因为广告账户 ID 已包含在 URL 以及 request.params 中。(此列表中有意不包含资金工具,因为在可行的情况下,父级 ID 应当出现在响应对象中,而账户 ID 是资金工具的父级实体。)
- Account media
- App event providers
- App event tags
- Campaigns
- Cards
- Line items
- Promotable users
- Targeting criteria
- 对于 GET accounts/:account_id/targeting_criteria 请求,我们将不再返回 parent_ids 字段,因为它始终是空数组。
- 注意:这不影响图片和视频类型的 App 下载卡片。
- 添加到 Media Library 的
AMPLIFY_VIDEO
资产会自动作为 Account Media 资产添加,并带有PREROLL
创意类型。 - 添加到 Media Library 的特定尺寸图片会自动作为 Account Media 资产添加。创意类型(例如
INTERSTITIAL
)取决于图片尺寸。(关于尺寸,请参见我们的 Enumerations 页面。)
v4
新增
- TON Upload:
- GET accounts/:account_id/tailored_audience_changes
- GET accounts/:account_id/tailored_audience_changes/:tailored_audience_change_id
- POST accounts/:account_id/tailored_audience_changes
- PUT accounts/:account_id/tailored_audiences/global_opt_out
- Real Time Audiences:
- POST tailored_audience_memberships
list_type
参数。
Settings Endpoints
我们现已支持账户管理员设置和更新用户、账户及税务设置。User settings 对应于指定广告账户的用户级联系偏好。通过 PUT accounts/:account_id endpoint,广告主可更新其账户名称和行业类型。最后,tax settings endpoints 允许在征收增值税(VAT)的国家/地区的广告主更新公司名称、地址、VAT ID,以及账户归属(由广告主自有,或由代理商代表广告主管理)等信息。
变更
lookalike_expansion
参数的枚举值:POST accounts/:account_id/line_items 和 PUT accounts/:account_id/line_items/:line_item_id。
v3 | v4 |
---|---|
NARROW | DEFINED |
BALANCED | EXPANDED |
country_code
作为在 X Ads API 中推进一致性的一部分,我们将以下 endpoint 的参数名从 app_country_code
重命名为 country_code
。
- POST accounts/:account_id/cards/image_app_download
- PUT accounts/:account_id/cards/image_app_download/:card_id
- POST accounts/:account_id/cards/video_app_download
- PUT accounts/:account_id/cards/video_app_download/:card_id
preview_url
始终为 null
正如 v3 公告所述,所有现有卡片现在都具有 card_uri
。因此,preview_url
的值将始终为 null
。
提醒:使用卡片的 card_uri
值将其与 Tweet 关联。参见以下示例请求。
$ twurl -X POST -H ads-api.x.com “/4/accounts/18ce54d4x5t/tweet?text=Version 4&card_uri=card://958225772740714496”
已移除
-
v3 videos endpoint:
twurl -H ads-api.x.com "/3/accounts/18ce54d4x5t/videos"
-
v4 针对视频的 media library endpoint:
twurl -H ads-api.x.com "/4/accounts/18ce54d4x5t/media_library?media_type=VIDEO"
as_user_id
GET accounts/:account_id/tweet/preview/:tweet_id endpoint 上提供的 as_user_id
参数将不再受理。预览将始终以该 Tweet 作者的身份呈现。
v3
- 基于输入受众,检索最相关的 hashtags、@handles 和事件。
- 基于输入受众,检索关键的人口统计信息(如年龄、性别和家庭收入)。
- 基于关键词,检索 Tweet 量的时间序列。
其他更改
- GET insights/keywords/search endpoint 的响应现在包含 related_keywords 属性,其中提供与输入关键词相关的 30 个术语。
- 定向条件的最大批处理大小现为 500。
- 响应属性 card_uri 和 preview_url 现在互斥。卡片具有 card_uri 时,preview_url 为 null;卡片没有 card_uri 时,仅返回 preview_url。
- 自 2018-01-29 起创建的所有卡片都将具有 card_uri。
- 到第 4 版时,所有现有卡片都将具有 card_uri。
- 不能再创建使用 5:2 比例图片的卡片。尽管现有的 5:2 图片卡片仍可使用,我们仍建议合作伙伴改用表现更佳的 1.91:1 或 1:1 纵横比(在支持的情况下)。
- PUT accounts/:account_id/targeting_criteria endpoint 不再可用。之所以进行此更改,是因为该 endpoint 的替换行为易引起广告主困惑,且与我们其他一次仅更新单个资源的 PUT endpoints 不一致。相应地,合作伙伴应使用 POST batch/accounts/:account_id/targeting_criteria endpoint,以获得更大灵活性,包括在单个请求中同时添加和移除定向。
- funding instruments 的响应属性 paused 不再返回。请改为查看响应属性 entity_status 以确定某个 funding instrument 是否处于暂停状态。此外,由于 paused 和 cancelled 对应同一取值,响应中也不再返回 cancelled。
- 我们已从 GET accounts/:account_id/tweet/preview endpoint 中移除参数 card_id。
- 由于无法检索已删除的 Scheduled Tweets,with_deleted 参数不再受支持。
- 以下 endpoints 已移除 draft_only 参数,因为这些实体不可能处于草稿状态:
v2
-
total_count
现为可选响应属性。仅当with_total_count
设为true
时才会返回 -
line_items
和campaigns
请求与响应对象中的paused
与draft_only
字段被单一的entity_status
参数取代 -
POST accounts/:account_id/tweet 和 GET accounts/:account_id/tweet/preview endpoint 上的
status
参数已重命名为text
-
GET targeting_criteria/locations endpoint 的
location_type
枚举现为复数形式:COUNTRY
改为COUNTRIES
,REGION
改为REGIONS
,以此类推。唯一例外是在 v2 中,CITY
改为METROS
,以准确反映该位置类型指代指定市场区域(DMA)或“都会区” -
PUT accounts/:account_id/promoted_tweets endpoint 上的
display_properties
不再受支持。该值也将不再作为响应的一部分返回 - 因上述变更,不再支持更新(PUT)promoted_tweets 实体
-
GET accounts/:account_id/promoted_tweets endpoint 上的
line_item_id
参数已移除 - 在 v2 endpoint 上将不再能够创建 5:2 Website Card
-
不再返回
data_type
响应属性
- Cards v2
- 草稿 campaign/line item 的创建与激活
- 预定发布的 Tweets
- 异步作业摘要
- 在将卡片与 Tweet 关联时,应使用
card_uri
请求参数,而不是将preview_url
追加到 Tweet 文本 - 如果在响应中未返回
card_uri
参数(卡片创建步骤期间),则使用preview_url
- 所有新的卡片格式将在 API 中原生提供,并利用
card_uri
参数
- 视频网站卡(Video Website Cards):
- 在 POST accounts/:account_id/line_items 和 POST accounts/:account_id/campaigns 这两个 endpoint 上,可以将
entity_status
参数设置为DRAFT
,以创建新的草稿 Campaign 或 Line Item。 - 新建草稿所需的参数集:
草稿 Campaign | 草稿 Line Item |
---|---|
funding_instrument_id | campaign_id |
name | objective |
start_time | product_type |
placements |
- 草稿 Line Item 或 Campaign 只能将
entity_status
从DRAFT
转换为PAUSED
或ACTIVE
- 若要激活整个 Campaign(包含多个 Line Item),该 Campaign 下的每个 Line Item 以及 Campaign 本身都必须将
entity_status
设为ACTIVE
。 - 若要更改任何 Campaign 或 Line Item 的
entity_status
,请使用相应的 PUT endpoint。
- Scheduled Tweets 包含以下新的 endpoint
- Scheduled Tweets:
- Campaign Management:
- 新创建的 Scheduled Tweets 可安排在任意未来日期
- 目前无法预览已排程的 Tweet
-
只有状态为
SCHEDULED
的 Scheduled Tweets 才可编辑或删除 -
在到达
scheduled_at
日期/时间之前,Scheduled Tweets 不会 传播到 Enterprise Firehose 或任何其他 data API。
v1
- 版本化支持
- 不再支持
CUSTOM
目标 - Batch endpoints 现已全面可用
- 触达预估更新:
- 为提供更准确的触达预估,该 endpoint 现已支持预算维度。以下参数现为必填:
- [new]
campaign_daily_budget_amount_local_micro
currency
bid
objective
- [new]
- 响应对象已更新,现在会为响应值返回取值范围。
infinite_count
已重命名为infinite_bid_count
,以避免对其用途产生误解- 除
count
和infinite_bid_count
外,还将返回以下新数据指标:impressions
engagements
estimated_daily_spend_local_micro
- “定向受众”的 data type 变更
- 在我们所有的响应中,Tailored Audiences 的
data_type
已从tailored_audiences
变更为tailored_audience
。 - “共享定向受众”现已以仅限 API 的测试版形式提供。共享定向受众允许在多个广告账户之间共用同一受众。使用 POST accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions(及相关)endpoint 来管理你希望在多个广告账户间共享的定向受众权限。
- 在为广告主账户收集绩效分析方面有重大改进:
- 为与我们的最佳实践保持一致,我们现在仅允许通过同步统计 endpoint提取最长7 天的 data。
- 为简化提取度量,我们已将
metrics
参数替换为新的metric_groups
参数。开发者只需在特定请求中指定希望返回的度量组即可。- 对于不适用于特定实体的度量请求,将在响应中被排除,并以
null
值表示。这些度量不会计入你的分析费用上限。
- 对于不适用于特定实体的度量请求,将在响应中被排除,并以
- 该响应已被大幅简化,并将更贴近我们在 UI 中呈现度量的方式。
- 之前我们针对每个投放位置分别提供单独的度量(搜索中的 Promoted Tweets、时间线中的 Promoted Tweets、个人资料与 Tweet 详情中的 Promoted Tweets、X Audience Platform)。现在我们将为每个位置返回一组标准化的度量,取代
promoted_tweet_timeline_impressions
、promoted_tweet_search_impressions
、promoted_tweets_profile_impressions
、promoted_tweets_tpn_impressions
。当在以下任一类别下请求时,将以单一度量impressions
提供(适用于所有度量): ALL_ON_TWITTER
PUBLISHER_NETWORK
- 当你发起请求时,将只会返回一个
impressions
度量,便于与我们 UI 中的数值对齐。 - 你必须分别发起两次查询才能获取
ALL_ON_TWITTER
和PUBLISHER_NETWORK
的 data,因为二者不能合并。
- 之前我们针对每个投放位置分别提供单独的度量(搜索中的 Promoted Tweets、时间线中的 Promoted Tweets、个人资料与 Tweet 详情中的 Promoted Tweets、X Audience Platform)。现在我们将为每个位置返回一组标准化的度量,取代
- 基于开发者的反馈,异步统计 endpoint 现已上线!
- 一组用于以异步方式请求统计数据的新 endpoint,适用于无需立即获取的数据或历史数据拉取。
- 使用一个新的单一 endpoint 将统计作业排队。我们会在资源允许时拉取你请求的 data。
- 你可以查询作业状态 endpoint 以确定 data 是否可用。
- 一旦 data 可用,我们将提供一个提取 id,供你下载 JSON 响应,该响应将与同步 endpoint 的响应一致。
- 在单个作业中最多查询90 天的 data,涵盖最多20 个实体。
- 请查看我们的 analytics v1 迁移指南,其中包含 v0 度量到 v1 度量的映射关系
- 沙盒改进 * 您现在可以在沙盒环境中创建多个测试广告账户。 * 您现在可以仅在沙盒环境中为测试广告账户创建多个资金工具。这样您即可测试我们提供的所有资金工具类型。此前,只有
CREDIT_CARD
资金来源可用于测试。 * 想测试某个 beta 功能?您现在可以在沙盒环境中为账户切换功能开/关,以满足测试需求。