Campaign management

行项目

在 Postman 中运行 ❯

GET accounts/:account_id/line_items

检索与当前账号关联的部分或所有行项目的详细信息。

资源 URL

https://ads-api.twitter.com/10/accounts/:account_id/line_items

参数

名称 说明
account_id
必需

所使用账号的标识符。出现在资源路径中，通常是所有广告商 API 请求的必要参数，不包含 GET accounts。指定账号必须与已验证的用户关联。

类型：string

示例：18ce54d4x5t
campaign_ids
可选

通过指定以逗号分隔的标识符列表，将响应范围限定为特定广告活动的行项目。最多可提供 200 个 ID。

类型：string

示例：8gdx6
count
可选

指定每个不同请求尝试检索的记录数量。

类型：int

默认值：200
最小值、最大值：1、1000
cursor
可选

指定光标以获取下一页结果。参阅分页了解更多信息。

类型：string

示例：8x7v00oow
funding_instrument_ids
可选

通过指定以逗号分隔的标识符列表，将响应范围限定为采用特定支付手段的行项目。最多可提供 200 个 ID。

类型：string

示例：lygyi
line_item_ids
可选

通过指定以逗号分隔的标识符列表，将响应范围限定为所需的行项目。最多可提供 200 个 ID。

类型：string

示例：8v7jo
q
可选

可选查询，按name 指定资源范围。

类型：string

最小、最大长度：1、255
sort_by
可选

根据支持的属性，按升序或降序排序。参阅排序了解更多信息。

类型：string

示例：created_at-asc
with_deleted
可选

在请求中包含已删除的结果。

类型：boolean

默认值：false
可能值：true、false
with_draft
可选

在请求中包含广告活动草稿结果。

类型：boolean

默认值：false
可能值：true、false
with_total_count
可选

包含 total_count 响应属性。

注意：不包含此参数和 cursor。

注意：包含 total_count 的请求速率限制较低，目前设置为每 15 分钟 200 次。

类型：boolean

默认值：false
可能值：true、false

请求示例

GET https://ads-api.twitter.com/10/accounts/18ce54d4x5t/line_items?line_item_ids=8v7jo

响应示例

{
  "request": {
    "params": {
      "line_item_ids": [
        "8v7jo"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "bid_strategy": "MAX",
      "advertiser_user_id": 756201191646691328,
      "name": "Untitled",
      "placements": [
        "ALL_ON_TWITTER"
      ],
      "start_time": null,
      "bid_amount_local_micro": 100000,
      "advertiser_domain": null,
      "target_cpa_local_micro": null,
      "primary_web_event_tag": null,
      "pay_by": "ENGAGEMENT",
      "product_type": "PROMOTED_TWEETS",
      "end_time": null,
      "duration_in_days": 1,
      "total_budget_amount_local_micro": null,
      "objective": "ENGAGEMENTS",
      "id": "8v7jo",
      "entity_status": "ACTIVE",
      "goal": "ENGAGEMENT",
      "frequency_cap": 5,
      "categories": [],
      "currency": "USD",
      "created_at": "2017-05-27T08:04:00Z",
      "updated_at": "2017-05-27T08:06:25Z",
      "campaign_id": "8gdx6",
      "creative_source": "MANUAL",
      "deleted": false
    }
  ]
}

GET accounts/:account_id/line_items/:line_item_id

检索与当前账号关联的特定行项目。

资源 URL

https://ads-api.twitter.com/10/accounts/:account_id/line_items/:line_item_id

参数

名称 说明
account_id
必需

所使用账号的标识符。出现在资源路径中，通常是所有广告商 API 请求的必要参数，不包含 GET accounts。指定账号必须与已验证的用户关联。

类型：string

示例：18ce54d4x5t
line_item_id
必需

请求中对正在操作的行项目的引用。

类型：string

示例：8v7jo
with_deleted
可选

在请求中包含已删除的结果。

类型：boolean

默认值：false
可能值：true、false

请求示例

GET https://ads-api.twitter.com/10/accounts/18ce54d4x5t/line_items/8v7jo

响应示例

{
  "request": {
    "params": {
      "line_item_id": "8v7jo",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "bid_strategy": "MAX",
    "advertiser_user_id": 756201191646691328,
    "name": "Untitled",
    "placements": [
      "ALL_ON_TWITTER"
    ],
    "start_time": null,
    "bid_amount_local_micro": 100000,
    "advertiser_domain": null,
    "target_cpa_local_micro": null,
    "primary_web_event_tag": null,
    "pay_by": "ENGAGEMENT",
    "product_type": "PROMOTED_TWEETS",
    "end_time": null,
    "duration_in_days": 1,
    "total_budget_amount_local_micro": null,
    "objective": "ENGAGEMENTS",
    "id": "8v7jo",
    "entity_status": "ACTIVE",
    "goal": "ENGAGEMENT",
    "frequency_cap": 5,
    "categories": [],
    "currency": "USD",
    "created_at": "2017-05-27T08:04:00Z",
    "updated_at": "2017-05-27T08:06:25Z",
    "campaign_id": "8gdx6",
    "creative_source": "MANUAL",
    "deleted": false
  }
}

POST accounts/:account_id/line_items

创建属于当前账号且与指定广告活动关联的行项目。

广告活动中的所有行项目必须具有相同的 product_type 和 objective。

使用 PROMOTED_ACCOUNT 产品类型时，将推文与 line_item 关联会在移动设备上添加时间线位置和标准 PROMOTED_ACCOUNT 位置。

设置 android_app_store_identifier 或 ios_app_store_identifier 将自动为与正在推广的移动应用匹配的行项目添加定位标准；例如，传入 ios_app_store_identifier 将为 iOS 添加 PLATFORM 定位标准。

注意：每个广告活动最多有 100 个行项目，所有广告活动最多有 8,000 个活跃行项目。

资源 URL

https://ads-api.twitter.com/10/accounts/:account_id/line_items

参数

名称 说明
account_id
必需

所使用账号的标识符。出现在资源路径中，通常是所有广告商 API 请求的必要参数，不包含 GET accounts。指定账号必须与已验证的用户关联。

类型：string

示例：18ce54d4x5t
campaign_id
必需

要在其下创建行项目的广告活动的标识符。

类型：string

示例：8slvg
objective
必需

此行项目的广告活动目标。

类型：enum

可能值：APP_ENGAGEMENTS、APP_INSTALLS、REACH、FOLLOWERS、ENGAGEMENTS、VIDEO_VIEWS、PREROLL_VIEWS、WEBSITE_CLICKS
placements
必需

要显示此行项目的展示位置。指定以逗号分隔的位置值列表。

类型：enum

可能值：ALL_ON_TWITTER、PUBLISHER_NETWORK、TAP_BANNER、TAP_FULL、TAP_FULL_LANDSCAPE、TAP_NATIVE、TAP_MRECT、TWITTER_PROFILE、TWITTER_SEARCH、TWITTER_TIMELINE
product_type
必需

此行项目将包含的推广产品类型。

类型：enum

可能值：MEDIA、PROMOTED_ACCOUNT、PROMOTED_TWEETS
advertiser_domain
有时为必需

此广告商的网站域，不含协议规范。

注意：行项目位置设置为 PUBLISHER_NETWORK 时，为必需。

类型：string

示例：twitter.com
android_app_store_identifier
有时为必需

推广应用程序的 Google 应用商店标识符。

注意：APP_INSTALLS 和 APP_ENGAGEMENTS 对象要求至少设置一个应用商店标识符 -- android_app_store_identifier 或 ios_app_store_identifier。

类型：string

示例：com.twitter.android
bid_amount_local_micro
有时为必需

要与此行项目关联的出价金额。将使用与指定支付手段关联的货币。对于美元，5.50 美元表示为 5500000。

注意：如果 bid_strategy 设置为 MAX 或 TARGET，则为必需。

注意：仅接受大于零的值。

类型：long

示例：5500000
categories
有时为必需

此广告商的相关 IAB 类别。参阅 GET iab_categories.

注意：行项目位置设置为 PUBLISHER_NETWORK 时，为必需。

类型：string

示例：IAB3-1
ios_app_store_identifier
有时为必需

推广应用程序的 Apple App Store 标识符的数字部分。

注意：APP_INSTALLS 和 APP_ENGAGEMENTS 对象要求至少设置一个应用商店标识符 -- android_app_store_identifier 或 ios_app_store_identifier。

类型：string

示例：333903271
primary_web_event_tag
有时为必需

主 Web 事件标签的标识符。可用于更准确地跟踪与此行项目相关的广告活动的互动量。

注意：行项目目标设置为 WEBSITE_CONVERSIONS 时为必需。

类型：string

示例：nvo4z
advertiser_user_id
可选

推广 PREROLL_VIEWS 广告的用户名的 Twitter 用户标识符。只有特定客户端应用程序可使用此参数。

类型：long

示例：312226591
audience_expansion
可选

用于通过定位到与已定位用户相似的用户来扩展广告活动的覆盖。

注意：默认情况下，不会应用扩展。

类型：enum

可能值：BROAD、DEFINED、EXPANDED
bid_strategy
可选

出价机制。

AUTO 根据每日预算和广告活动排期日期自动优化出价。

MAX 设置允许的最高出价，当目标设置为 REACH 或 FOLLOWERS 时不可用。

TARGET 尝试将每日出价平均值设置为指定 bid_amount_local_micro 的 20% 以内，在目标设置为 REACH、FOLLOWERS 或 WEBSITE_CLICKS 时可用。

注意：如果设置为 AUTO，则会忽略 bid_amount_local_micro。

注意：默认值基于目标。

类型：enum

可能值：AUTO、MAX、TARGET
duration_in_days
可选

frequency_cap 实现的时间段。

类型：int

可能值：1、7、30
end_time
可选

行项目将停止投放的时间，以 ISO 8601 表示。

类型：string

示例：2017-10-05T00:00:00Z
entity_status
可选

行项目状态。

类型：enum

默认值：ACTIVE
可能值：ACTIVE、DRAFT、PAUSED
frequency_cap
可选

可以向用户投放广告的最大次数。

注意：仅支持 REACH、ENGAGEMENTS、VIDEO_VIEWS 和 PREROLL_VIEWS 目标。

类型：int

示例：5
goal
可选

与此行项目一起使用的优化设置。APP_CLICKS 和 APP_INSTALLS 选项适用于 APP_INSTALL 和 APP_ENGAGEMENTS，并且可能需要使用一个支持的 MACT 合作伙伴。

注意：默认值基于目标。

类型：enum

可能值：APP_CLICKS、APP_INSTALLS、ENGAGEMENT、FOLLOWERS、LINK_CLICKS、MAX_REACH、PREROLL、PREROLL_STARTS、REACH_WITH_ENGAGEMENT、VIDEO_VIEW、VIEW_3S_100PCT、VIEW_6S、VIEW_15S、WEBSITE_CONVERSIONS
name
可选

行项目名称。

类型：string

示例：demo

最小、最大长度：1、255
pay_by
可选

此行项目的收费单位。只能使用 APP_INSTALLS 目标为行项目修改此设置。

注意：默认的 pay_by 是根据广告活动目标和行项目的出价单位自动设置的。

类型：enum

可能值：APP_CLICK
start_time
可选

行项目将开始投放的时间，以 ISO 8601 表示。

类型：string

示例：2017-07-05T00:00:00Z
total_budget_amount_local_micro
可选

要分配给行项目的总预算金额。将使用与指定支付手段关联的货币。对于美元，37.50 美元表示为 37500000。

类型：long

示例：37500000

请求示例

POST https://ads-api.twitter.com/10/accounts/18ce54d4x5t/line_items?campaign_id=8slvg&objective=ENGAGEMENTS&product_type=PROMOTED_TWEETS&placements=ALL_ON_TWITTER&bid_amount_local_micro=3210000&entity_status=PAUSED

响应示例

{
  "data": {
    "bid_strategy": "MAX",
    "advertiser_user_id": 756201191646691328,
    "name": "Untitled",
    "placements": [
      "ALL_ON_TWITTER"
    ],
    "start_time": null,
    "bid_amount_local_micro": 3210000,
    "advertiser_domain": null,
    "target_cpa_local_micro": null,
    "primary_web_event_tag": null,
    "pay_by": "ENGAGEMENT",
    "product_type": "PROMOTED_TWEETS",
    "end_time": null,
    "duration_in_days": null,
    "total_budget_amount_local_micro": null,
    "objective": "ENGAGEMENTS",
    "frequency_cap": null,
    "id": "95lya",
    "entity_status": "PAUSED",
    "goal": "ENGAGEMENT",
    "categories": [],
    "currency": "USD",
    "created_at": "2017-06-23T01:59:22Z",
    "updated_at": "2017-06-23T01:59:22Z",
    "campaign_id": "8slvg",
    "creative_source": "MANUAL",
    "deleted": false
  },
  "request": {
    "params": {
      "placements": [
        "ALL_ON_TWITTER"
      ],
      "bid_amount_local_micro": 3210000,
      "product_type": "PROMOTED_TWEETS",
      "objective": "ENGAGEMENTS",
      "entity_status": "PAUSED",
      "account_id": "18ce54d4x5t",
      "campaign_id": "8slvg"
    }
  }
}

POST batch/accounts/:account_id/line_items

允许使用单个请求批量创建新的行项目。

批量请求

  • 目前最大批量大小为 40。
  • 所有参数都在请求正文中发送，并且需要 application/json 的 Content-Type。
  • 无论失败或成功，批量请求均作为一个整体，并且错误和成功的所有 API 响应都保留初始请求的项目顺序。

批量响应

批量 API 响应返回已排序的项目集合。否则，其结构将与相应的单项目端点相同。

批量错误

  • 请求级别的错误（例如，超过最大批量大小）会显示在 errors 对象下的响应中。
  • 项目级别的错误（例如，缺少必需的行项目参数）会显示在 operation_errors 对象下的响应中。

资源 URL

https://ads-api.twitter.com/10/batch/accounts/:account_id/line_items

参数

名称 说明
operation_type
必需

正在执行的每个项目操作类型。

类型：enum

可能值：Create、Delete、Update
params
必需
 包含行项目对象的所有参数的 JSON 对象。如需查看必需和可选行项目参数的列表，请点击此处。

请求示例

POST 'Content-Type: application/json' https://ads-api.twitter.com/10/batch/accounts/18ce54d4x5t/line_items

[  
  {  
    "operation_type":"Create",
    "params":{  
      "campaign_id":"8yn7m",
      "objective":"ENGAGEMENTS",
      "product_type":"PROMOTED_TWEETS",
      "placements":"ALL_ON_TWITTER",
      "bid_amount_local_micro":3210000,
      "entity_status":"PAUSED"
    }
  }
]

响应示例

{
  "data": [
    {
      "bid_strategy": "MAX",
      "advertiser_user_id": 756201191646691328,
      "name": "Untitled",
      "placements": [
        "ALL_ON_TWITTER"
      ],
      "start_time": null,
      "bid_amount_local_micro": 3210000,
      "advertiser_domain": null,
      "target_cpa_local_micro": null,
      "primary_web_event_tag": null,
      "pay_by": "ENGAGEMENT",
      "product_type": "PROMOTED_TWEETS",
      "end_time": null,
      "total_budget_amount_local_micro": null,
      "objective": "ENGAGEMENTS",
      "id": "9cqi0",
      "entity_status": "PAUSED",
      "goal": "ENGAGEMENT",
      "categories": [],
      "currency": "USD",
      "created_at": "2017-07-07T17:42:20Z",
      "updated_at": "2017-07-07T17:42:20Z",
      "campaign_id": "8yn7m",
      "creative_source": "MANUAL",
      "deleted": false
    }
  ],
  "request": [
    {
      "params": {
        "placements": [
          "ALL_ON_TWITTER"
        ],
        "bid_amount_local_micro": 3210000,
        "product_type": "PROMOTED_TWEETS",
        "objective": "ENGAGEMENTS",
        "entity_status": "PAUSED",
        "account_id": "18ce54d4x5t",
        "campaign_id": "8yn7m"
      },
      "operation_type": "Create"
    }
  ]
}

PUT accounts/:account_id/line_items/:line_item_id

更新与当前账号关联的指定行项目。

资源 URL

https://ads-api.twitter.com/10/accounts/:account_id/line_items/:line_item_id

参数

名称 说明
account_id
必需

所使用账号的标识符。出现在资源路径中，通常是所有广告商 API 请求的必要参数，不包含 GET accounts。指定账号必须与已验证的用户关联。

类型：string

示例：18ce54d4x5t
line_item_id
必需

请求中对正在操作的行项目的引用。

类型：string

示例：8v7jo
advertiser_domain
可选

此广告商的网站域，不含协议规范。

注意：行项目位置设置为 PUBLISHER_NETWORK 时，为必需。

类型：string

示例：twitter.com
advertiser_user_id
可选

推广 PREROLL_VIEWS 广告的用户名的 Twitter 用户标识符。只有特定客户端应用程序可使用此参数。

类型：long

示例：312226591
android_app_store_identifier
可选

推广应用程序的 Google 应用商店标识符。

注意：APP_INSTALLS 和 APP_ENGAGEMENTS 对象要求至少设置一个应用商店标识符 -- android_app_store_identifier 或 ios_app_store_identifier。

类型：string

示例：com.twitter.android
audience_expansion
可选

用于通过定位到与已定位用户相似的用户来扩展广告活动的覆盖。

类型：enum

可能值：BROAD、DEFINED、EXPANDED
bid_amount_local_micro
可选

要与此行项目关联的出价金额。将使用与指定支付手段关联的货币。对于美元，5.50 美元表示为 5500000。

注意：如果 bid_strategy 设置为 MAX 或 TARGET，则为必需。

注意：仅接受大于零的值。

类型：long

示例：140000
bid_strategy
可选

出价机制。

AUTO 根据每日预算和广告活动排期日期自动优化出价。

MAX 设置允许的最高出价，当目标设置为 REACH 或 FOLLOWERS 时不可用。

TARGET 尝试将每日出价平均值设置为指定 bid_amount_local_micro 的 20% 以内，在目标设置为 REACH 或 WEBSITE_CLICKS 时可用。

注意：如果设置为 AUTO，则会忽略 bid_amount_local_micro。

注意：默认值基于目标。

类型：enum

可能值：AUTO、MAX、TARGET
categories
可选

此广告商的相关 IAB 类别。参阅 GET iab_categories.

注意：行项目位置设置为 PUBLISHER_NETWORK 时，为必需。

类型：string

示例：IAB3-1
duration_in_days
可选

frequency_cap 实现的时间段。

类型：int

可能值：1、7、30
end_time
可选

行项目将停止投放的时间，以 ISO 8601 表示。

类型：string

示例：2017-10-05T00:00:00Z
entity_status
可选

行项目状态。

类型：enum

可能值：ACTIVE、PAUSED
frequency_cap
可选

可以向用户投放广告的最大次数。

注意：仅支持 REACH、ENGAGEMENTS、VIDEO_VIEWS 和 PREROLL_VIEWS 目标。

类型：int

示例：5
goal
可选

与此行项目一起使用的优化设置。APP_CLICKS 和 APP_INSTALLS 选项适用于 APP_INSTALL 和 APP_ENGAGEMENTS，并且可能需要使用一个支持的 MACT 合作伙伴。

注意：默认值基于目标。

类型：enum

可能值：APP_CLICKS、APP_INSTALLS、ENGAGEMENT、FOLLOWERS、LINK_CLICKS、MAX_REACH、PREROLL、PREROLL_STARTS、REACH_WITH_ENGAGEMENT、VIDEO_VIEW、VIEW_3S_100PCT、VIEW_6S、VIEW_15S、WEBSITE_CONVERSIONS
ios_app_store_identifier
可选

推广应用程序的 Apple App Store 标识符的数字部分。

注意：APP_INSTALLS 和 APP_ENGAGEMENTS 对象要求至少设置一个应用商店标识符 -- android_app_store_identifier 或 ios_app_store_identifier。

类型：string

示例：333903271
name
可选

行项目名称。

类型：string

示例：demo
start_time
可选

行项目将开始投放的时间，以 ISO 8601 表示。

类型：string

示例：2017-07-05T00:00:00Z
total_budget_amount_local_micro
可选

要分配给行项目的总预算金额。将使用与指定支付手段关联的货币。对于美元，37.50 美元表示为 37500000。

类型：long

示例：37500000

请求示例

PUT https://ads-api.twitter.com/10/accounts/18ce54d4x5t/line_items/8v7jo?bid_amount_local_micro=140000

响应示例

{
  "data": {
    "bid_strategy": "MAX",
    "advertiser_user_id": 756201191646691328,
    "name": "Untitled",
    "placements": [
      "ALL_ON_TWITTER"
    ],
    "start_time": null,
    "bid_amount_local_micro": 140000,
    "advertiser_domain": null,
    "target_cpa_local_micro": null,
    "primary_web_event_tag": null,
    "pay_by": "ENGAGEMENT",
    "product_type": "PROMOTED_TWEETS",
    "duration_in_days": 1,
    "end_time": null,
    "total_budget_amount_local_micro": null,
    "objective": "ENGAGEMENTS",
    "id": "8v7jo",
    "entity_status": "ACTIVE",
    "goal": "ENGAGEMENT",
    "frequency_cap": 5,
    "categories": [],
    "currency": "USD",
    "created_at": "2017-05-27T08:04:00Z",
    "updated_at": "2017-07-04T22:01:28Z",
    "campaign_id": "8gdx6",
    "creative_source": "MANUAL",
    "deleted": false
  },
  "request": {
    "params": {
      "line_item_id": "8v7jo",
      "bid_amount_local_micro": 140000,
      "account_id": "18ce54d4x5t"
    }
  }
}

DELETE accounts/:account_id/line_items/:line_item_id

删除属于当前账号的指定行项目。

注意：删除行项目的操作无法撤消，之后再尝试删除该资源将返回 HTTP 404。

注意：当某个行项目被删除时，如果请求中指定了 with_deleted=true，则只有 GET accounts/:account_id/promoted_tweets 和 GET accounts/:account_id/promoted_tweets/:promoted_tweet_id 端点会返回其 promoted_tweets 子实体。但实际上这些 promoted_tweets 实体并不会被删除（响应中包含 "deleted": false）。我们不会传递删除操作。

资源 URL

https://ads-api.twitter.com/10/accounts/:account_id/line_items/:line_item_id

参数

名称 说明
account_id
必需

所使用账号的标识符。出现在资源路径中，通常是所有广告商 API 请求的必要参数，不包含 GET accounts。指定账号必须与已验证的用户关联。

类型：string

示例：18ce54d4x5t
line_item_id
必需

请求中对正在操作的行项目的引用。

类型：string

示例：9f2ix

请求示例

DELETE https://ads-api.twitter.com/10/accounts/18ce54d4x5t/line_items/9f2ix

响应示例

{
  "data": {
    "bid_strategy": "MAX",
    "advertiser_user_id": 756201191646691328,
    "name": "Untitled",
    "placements": [],
    "start_time": null,
    "bid_amount_local_micro": 100000,
    "advertiser_domain": null,
    "target_cpa_local_micro": null,
    "primary_web_event_tag": null,
    "pay_by": "ENGAGEMENT",
    "product_type": "PROMOTED_TWEETS",
    "end_time": "2017-07-21T00:00:00Z",
    "duration_in_days": 1,
    "total_budget_amount_local_micro": null,
    "objective": "ENGAGEMENTS",
    "id": "9f2ix",
    "entity_status": "ACTIVE",
    "goal": "ENGAGEMENT",
    "frequency_cap": 5,
    "categories": [],
    "currency": "USD",
    "created_at": "2017-07-14T00:01:50Z",
    "updated_at": "2017-08-09T07:41:08Z",
    "campaign_id": "90r8n",
    "creative_source": "MANUAL",
    "deleted": true
  },
  "request": {
    "params": {
      "line_item_id": "9f2ix",
      "account_id": "18ce54d4x5t"
    }
  }
}