Campaign management

广告活动

在 Postman 中运行 ❯

GET accounts/:account_id/campaigns

检索与当前账号关联的部分或所有广告活动的详细信息。

资源 URL

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

参数

名称 说明
account_id
必需

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

类型：string

示例：18ce54d4x5t
campaign_ids
可选

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

类型：string

示例：8wku2
count
可选

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

类型：int

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

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

类型：string

示例：8x7v00oow
funding_instrument_ids
可选

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

类型：string

示例：lygyi
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/campaigns?campaign_ids=8wku2

响应示例

{
  "request": {
    "params": {
      "campaign_ids": [
        "8wku2"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "name": "batch campaigns",
      "start_time": "2017-06-30T00:00:00Z",
      "reasons_not_servable": [
        "PAUSED_BY_ADVERTISER",
        "INCOMPLETE"
      ],
      "servable": false,
      "daily_budget_amount_local_micro": 140000000,
      "end_time": null,
      "funding_instrument_id": "lygyi",
      "standard_delivery": true,
      "total_budget_amount_local_micro": null,
      "id": "8wku2",
      "entity_status": "PAUSED",
      "currency": "USD",
      "created_at": "2017-06-30T21:17:16Z",
      "updated_at": "2017-06-30T21:17:16Z",
      "deleted": false
    }
  ]
}

GET accounts/:account_id/campaigns/:campaign_id

检索与当前账号关联的特定广告活动。

资源 URL

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

参数

名称 说明
account_id
必需

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

类型：string

示例：18ce54d4x5t
campaign_id
必需

请求中对正在操作的广告活动的引用。

类型：string

示例：8wku2
with_deleted
可选

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

类型：boolean

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

请求示例

GET https://ads-api.twitter.com/10/accounts/18ce54d4x5t/campaigns/8wku2

响应示例

{
  "request": {
    "params": {
      "campaign_id": "8wku2",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "batch campaigns",
    "start_time": "2017-06-30T00:00:00Z",
    "reasons_not_servable": [
      "PAUSED_BY_ADVERTISER",
      "INCOMPLETE"
    ],
    "servable": false,
    "daily_budget_amount_local_micro": null,
    "end_time": null,
    "funding_instrument_id": "lygyi",
    "standard_delivery": true,
    "total_budget_amount_local_micro": null,
    "id": "8wku2",
    "entity_status": "PAUSED",
    "currency": "USD",
    "created_at": "2017-06-30T21:17:16Z",
    "updated_at": "2017-06-30T21:17:16Z",
    "deleted": false
  }
}

POST accounts/:account_id/campaigns

创建与当前账号关联的新广告活动。

注意：每个账号的活跃广告活动默认限制为 200 个。但是，不活跃广告活动没有数量限制。该限制可以提高到 8,000 个活跃广告活动。要启用更高的上限，广告商必须向其 Twitter 账号管理员发出请求。

资源 URL

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

参数

名称 说明
account_id
必需

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

类型：string

示例：18ce54d4x5t
funding_instrument_id
必需

创建广告活动时采用的支付手段的标识符。

类型：string

示例：lygyi
name
必需

广告活动名称。最大长度：255 个字符。

类型：string

示例：demo
start_time
必需

广告活动开始时间，以 ISO 8601 表示。

类型：string

示例：2017-07-05T00:00:00Z
daily_budget_amount_local_micro
有时为必需

要分配给广告活动的每日预算金额。将使用与指定支付手段关联的货币。对于美元，5.50 美元表示为 5500000。

注意：此值应小于或等于 total_budget_amount_local_micro，且对于大多数支付手段类型都是必需的。

类型：long

示例：5500000
end_time
可选

广告活动结束时间，以 ISO 8601 表示。

类型：string

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

广告活动状态。

类型：enum

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

账簿参考编号。使用此字段有助于进行发票对账。最大长度：50 个字符。

类型：string

示例：D00805843
standard_delivery
可选

启用标准或加速投放。有关标准投放与加速投放的更多信息，请参阅预算花费进度。

类型：boolean

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

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

类型：long

示例：37500000

请求示例

POST https://ads-api.twitter.com/10/accounts/18ce54d4x5t/campaigns?funding_instrument_id=lygyi&name=demo&start_time=2017-07-05&daily_budget_amount_local_micro=140000000&entity_status=PAUSED

响应示例

{
  "data": {
    "name": "demo",
    "start_time": "2017-07-05T00:00:00Z",
    "reasons_not_servable": [
      "PAUSED_BY_ADVERTISER",
      "INCOMPLETE"
    ],
    "servable": false,
    "daily_budget_amount_local_micro": 140000000,
    "end_time": null,
    "funding_instrument_id": "lygyi",
    "standard_delivery": true,
    "total_budget_amount_local_micro": null,
    "id": "8slvg",
    "entity_status": "PAUSED",
    "currency": "USD",
    "created_at": "2017-06-23T01:59:12Z",
    "updated_at": "2017-06-23T01:59:12Z",
    "deleted": false
  },
  "request": {
    "params": {
      "name": "demo",
      "start_time": "2017-07-05T00:00:00Z",
      "daily_budget_amount_local_micro": 140000000,
      "funding_instrument_id": "lygyi",
      "entity_status": "PAUSED",
      "account_id": "18ce54d4x5t"
    }
  }
}

POST batch/accounts/:account_id/campaigns

允许使用单个请求批量创建新的广告活动。

批量请求

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

批量响应

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

批量错误

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

资源 URL

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

参数

名称 说明
operation_type
必需

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

类型：enum

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

请求示例

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

[  
  {  
    "operation_type":"Create",
    "params":{  
      "start_time":"2017-07-10",
      "name":"batch campaigns",
      "funding_instrument_id":"lygyi",
      "daily_budget_amount_local_micro":140000000,
      "entity_status":"PAUSED"
    }
  }
]

响应示例

{
  "data": [
    {
      "name": "batch campaigns",
      "start_time": "2017-07-10T00:00:00Z",
      "reasons_not_servable": [
        "PAUSED_BY_ADVERTISER",
        "INCOMPLETE"
      ],
      "servable": false,
      "daily_budget_amount_local_micro": 140000000,
      "end_time": null,
      "funding_instrument_id": "lygyi",
      "standard_delivery": true,
      "total_budget_amount_local_micro": null,
      "id": "8yn7m",
      "entity_status": "PAUSED",
      "currency": "USD",
      "created_at": "2017-07-07T17:28:50Z",
      "updated_at": "2017-07-07T17:28:50Z",
      "deleted": false
    }
  ],
  "request": [
    {
      "params": {
        "name": "batch campaigns",
        "start_time": "2017-07-10T00:00:00Z",
        "funding_instrument_id": "lygyi",
        "daily_budget_amount_local_micro": 140000000,
        "entity_status": "PAUSED",
        "account_id": "18ce54d4x5t"
      },
      "operation_type": "Create"
    }
  ]
}

PUT accounts/:account_id/campaigns/:campaign_id

更新与当前账号关联的指定广告活动。

资源 URL

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

参数

名称 说明
account_id
必需

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

类型：string

示例：18ce54d4x5t
campaign_id
必需

请求中对正在操作的广告活动的引用。

类型：string

示例：8wku2
daily_budget_amount_local_micro
可选

要分配给广告活动的每日预算金额。将使用与指定支付手段关联的货币。对于美元，5.50 美元表示为 5500000。如果未提供，广告活动的支出将根据总预算和广告活动排期时间长短平均分配。

注意：此参数应该小于或等于 total_budget_amount_local_micro。

类型：long

示例：5500000
end_time
可选

广告活动结束时间，以 ISO 8601 表示。

类型：string

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

广告活动状态。

类型：enum

可能值：ACTIVE、PAUSED
name
可选

广告活动名称。最大长度：255 个字符。

类型：string

示例：demo
purchase_order_number
可选

账簿参考编号。使用此字段有助于进行发票对账。最大长度：50 个字符。

类型：string

示例：D00805843
standard_delivery
可选

启用标准或加速投放。有关标准投放与加速投放的更多信息，请参阅预算花费进度。

类型：boolean

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

广告活动开始时间，以 ISO 8601 表示。

类型：string

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

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

类型：long

示例：140000000

请求示例

PUT https://ads-api.twitter.com/10/accounts/18ce54d4x5t/campaigns/8wku2?total_budget_amount_local_micro=140000000

响应示例

{
  "data": {
    "name": "batch campaigns",
    "start_time": "2017-06-30T00:00:00Z",
    "reasons_not_servable": [
      "PAUSED_BY_ADVERTISER",
      "INCOMPLETE"
    ],
    "servable": false,
    "daily_budget_amount_local_micro": null,
    "end_time": null,
    "funding_instrument_id": "lygyi",
    "standard_delivery": true,
    "total_budget_amount_local_micro": 140000000,
    "id": "8wku2",
    "entity_status": "PAUSED",
    "currency": "USD",
    "created_at": "2017-06-30T21:17:16Z",
    "updated_at": "2017-07-04T21:41:49Z",
    "deleted": false
  },
  "request": {
    "params": {
      "campaign_id": "8wku2",
      "total_budget_amount_local_micro": 140000000,
      "account_id": "18ce54d4x5t"
    }
  }
}

DELETE accounts/:account_id/campaigns/:campaign_id

删除属于当前账号的指定广告活动。

注意：删除广告活动的操作无法撤消，之后再尝试删除该资源将返回 HTTP 404。

资源 URL

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

参数

名称 说明
account_id
必需

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

类型：string

示例：18ce54d4x5t
campaign_id
必需

请求中对正在操作的广告活动的引用。

类型：string

示例：8yn7m

请求示例

DELETE https://ads-api.twitter.com/10/accounts/18ce54d4x5t/campaigns/8yn7m

响应示例

{
  "data": {
    "name": "batch campaigns",
    "start_time": "2017-07-10T00:00:00Z",
    "reasons_not_servable": [
      "DELETED"
    ],
    "servable": false,
    "daily_budget_amount_local_micro": 140000000,
    "end_time": null,
    "funding_instrument_id": "lygyi",
    "standard_delivery": true,
    "total_budget_amount_local_micro": null,
    "id": "8yn7m",
    "entity_status": "PAUSED",
    "currency": "USD",
    "created_at": "2017-07-07T17:28:50Z",
    "updated_at": "2017-08-09T07:35:30Z",
    "deleted": true
  },
  "request": {
    "params": {
      "campaign_id": "8yn7m",
      "account_id": "18ce54d4x5t"
    }
  }
}