Audiences

自定义受众（已弃用）

在 Postman 中运行 ❯

注意：此页面上的端点已弃用。它们在 v8 中仍然可用，但在 v9 中不可用。

GET accounts/:account_id/tailored_audiences

检索与当前账号关联的部分或所有自定义受众的详细信息。

资源 URL

https://ads-api.twitter.com/8/accounts/:account_id/tailored_audiences

参数

名称 说明
account_id
必需

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

类型：string

示例：18ce54d4x5t
count
可选

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

类型：int

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

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

类型：string

示例：8x7v00oow
permission_scope
可选

允许筛选你拥有的列表响应或与你共享的列表响应。默认情况下，不指定此参数则只能查看自已拥有的受众。

类型：enum

默认值：OWNER
可能值：OWNER、SHARED
q
可选

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

注意：执行不区分大小写的前缀匹配。

类型：string

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

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

类型：string

示例：created_at-asc
tailored_audience_ids
可选

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

类型：string

示例：1nmth
with_deleted
可选

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

类型：boolean

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

包含 total_count 响应属性。

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

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

类型：boolean

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

请求示例

GET https://ads-api.twitter.com/8/accounts/18ce54d4x5t/tailored_audiences?tailored_audience_ids=1nmth

响应示例

{
  "request": {
    "params": {
      "tailored_audience_ids": [
        "1nmth"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "targetable": true,
      "name": "twurl-using-subshell-for-file",
      "targetable_types": [
        "CRM",
        "EXCLUDED_CRM"
      ],
      "audience_type": "CRM",
      "description": null,
      "permission_level": "READ_WRITE",
      "owner_account_id": "18ce54d4x5t",
      "id": "1nmth",
      "reasons_not_targetable": [],
      "created_at": "2017-01-08T08:19:58Z",
      "updated_at": "2017-01-08T16:21:13Z",
      "partner_source": "OTHER",
      "deleted": false,
      "audience_size": 1470
    }
  ]
}

GET accounts/:account_id/tailored_audiences/:tailored_audience_id

检索与当前账号关联的指定自定义受众。

资源 URL

https://ads-api.twitter.com/8/accounts/:account_id/tailored_audiences/:tailored_audience_id

参数

名称 说明
account_id
必需

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

类型：string

示例：18ce54d4x5t
tailored_audience_id
必需

请求中对正在操作的自定义受众的引用。

类型：string

示例：2906h
with_deleted
可选

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

类型：boolean

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

请求示例

GET https://ads-api.twitter.com/8/accounts/18ce54d4x5t/tailored_audiences/2906h

响应示例

{
  "request": {
    "params": {
      "tailored_audience_id": "2906h",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "targetable": false,
    "name": "developers",
    "targetable_types": [
      "CRM",
      "EXCLUDED_CRM"
    ],
    "audience_type": "CRM",
    "description": null,
    "permission_level": "READ_WRITE",
    "owner_account_id": "18ce54d4x5t",
    "id": "2906h",
    "reasons_not_targetable": [],
    "created_at": "2017-08-22T23:34:26Z",
    "updated_at": "2017-08-22T23:34:26Z",
    "partner_source": "OTHER",
    "deleted": false,
    "audience_size": 140321
  }
}

POST accounts/:account_id/tailored_audiences

创建与当前账号关联的自定义受众新占位符。

资源 URL

https://ads-api.twitter.com/8/accounts/:account_id/tailored_audiences

参数

名称 说明
account_id
必需

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

类型：string

示例：18ce54d4x5t
name
必需

此受众的显示名称。

类型：string

示例：ads api users
description
可选

此受众的说明。

类型：string

示例：Collection of all users of the Ads API

请求示例

POST https://ads-api.twitter.com/8/accounts/18ce54d4x5t/tailored_audiences?name=developers

响应示例

{
  "data": {
    "targetable": false,
    "name": "developers",
    "targetable_types": [
      "CRM",
      "EXCLUDED_CRM"
    ],
    "audience_type": "CRM",
    "description": null,
    "permission_level": "READ_WRITE",
    "owner_account_id": "18ce54d4x5t",
    "id": "2906h",
    "reasons_not_targetable": [
      "PROCESSING",
      "TOO_SMALL"
    ],
    "created_at": "2017-08-22T23:34:26Z",
    "updated_at": "2017-08-22T23:34:26Z",
    "partner_source": "OTHER",
    "deleted": false,
    "audience_size": null
  },
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "name": "developers"
    }
  }
}

PUT accounts/:account_id/tailored_audiences/:tailored_audience_id

更新与当前账号关联的指定自定义受众。

资源 URL

https://ads-api.twitter.com/8/accounts/:account_id/tailored_audiences/:tailored_audience_id

参数

名称 说明
account_id
必需

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

类型：string

示例：18ce54d4x5t
tailored_audience_id
必需

请求中对正在操作的自定义受众的引用

类型：string

示例：2906h
name
可选

此受众的显示名称。

类型：string

示例：ads api users
description
可选

此受众的说明。

类型：string

示例：Collection of all users of the Ads API

请求示例

PUT https://ads-api.twitter.com/8/accounts/18ce54d4x5t/tailored_audiences/2906h?name=developers_changed

响应示例

{
  "data": {
    "targetable": false,
    "name": "developers_changed",
    "targetable_types": [
      "CRM",
      "EXCLUDED_CRM"
    ],
    "audience_type": "CRM",
    "description": null,
    "permission_level": "READ_WRITE",
    "is_owner": true,
    "id": "2906h",
    "reasons_not_targetable": [
      "PROCESSING",
      "TOO_SMALL"
    ],
    "created_at": "2017-08-22T23:34:26Z",
    "updated_at": "2017-08-22T23:34:26Z",
    "partner_source": "OTHER",
    "deleted": false,
    "audience_size": null
  },
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "name": "developers_changed"
    }
  }
}

POST batch/accounts/:account_id/tailored_audiences

允许批量创建自定义受众。参阅自定义受众概述页面，获取有关受众的信息。

注意：此批量端点目前处于封闭测试阶段，选定的广告商可用。在该测试阶段，只能创建基于移动自定义受众的灵活受众。

批量请求

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

批量响应

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

批量错误

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

灵活受众

在 Postman 中运行 ❯
  • 灵活受众创建后将无法改变。
  • 以具有布尔逻辑组合的树形结构输入自定义受众，以此创建灵活受众
  • 最多可使用 10 个自定义受众叶节点来创建灵活受众。

资源 URL

https://ads-api.twitter.com/8/batch/accounts/:account_id/tailored_audiences

参数

名称 说明
account_id
必需

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

类型：string

示例：18ce54d4x5t
audience_type
必需

要创建的受众类型。

类型：enum

可能值：FLEXIBLE、MOBILE_AUDIENCE
child_segments
必需

包含对象的数组，这些对象指定了要定位的自定义受众成员的子集。每个对象应该包含 tailored_audience_id、frequency、frequency_comparator、lookback_window、negate，在某些情况下，还应该包含 child_segments。

类型：array
name
必需

受众的显示名称。

类型：string

示例：my_flexible_audience_name
operation_type
必需

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

类型：enum

可能值：Create、Update、Delete
boolean_operator
有时为必需

父（包含）对象中各子分段之间的逻辑关系。如果父对象的 child_segment 非空，则为必需。

类型：enum

可能值：AND、OR
lookback_window
有时为必需

指定了天数范围的整数值，用户在此时间范围内采取指定操作并符合给定的自定义受众要求。

类型：int

可能值：1、7、14、30
segments
有时为必需

包含 boolean_operator 和 child_segments 的对象，该对象指定了要定位的自定义受众成员的子集。

类型：object
tailored_audience_id
有时为必需

用作子分段的自定义受众 ID。

类型：string

示例：tyfo
frequency
可选

整数值，指定了用户在回看窗口中采取指定操作并符合给定自定义受众要求的频率。

类型：int

默认值：1
frequency_comparator
可选

请求中输入的 frequency 的比较器。

注意：在下面的值中，GTE 表示大于等于，LT 表示小于，以此类推。

类型：string

可能值：NUM_GTE、NUM_GT、NUM_EQ、NUM_LTE、NUM_LT 默认值：NUM_GTE
negate
可选

否定分段，且随后不会包含在组合中。

类型：boolean

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

请求示例

POST https://ads-api.twitter.com/8/batch/accounts/18ce54d4x5t/tailored_audiences

[  
  {  
    "operation_type":"Create",
    "params":{  
      "name":"my_flexible_audience_name",
      "audience_type":"FLEXIBLE",
      "segments":{  
        "boolean_operator":"AND",
        "child_segments":[  
          {  
            "tailored_audience_id":"TYIF",
            "frequency":1,
            "frequency_comparator":"NUM_GT",
            "lookback_window":30,
            "negate":true,
            "child_segments":[  

            ]
          },
          {  
            "boolean_operator":"OR",
            "child_segments":[  
              {  
                "tailored_audience_id":"TXR1",
                "lookback_window":30,
                "child_segments":[  

                ]
              },
              {  
                "tailored_audience_id":"TYFO",
                "frequency":1,
                "frequency_comparator":"NUM_GT",
                "lookback_window":30,
                "negate":true,
                "child_segments":[  

                ]
              }
            ]
          }
        ]
      }
    }
  }
]

响应示例

{
  "data": {
    "targetable": false,
    "name": "my_flexible_audience_name",
    "targetable_types": [
      "FLEXIBLE",
      "EXCLUDED_FLEXIBLE"
    ],
    "audience_type": "FLEXIBLE",
    "id": "13ld7",
    "reasons_not_targetable": [
      "PROCESSING",
      "TOO_SMALL"
    ],
    "metadata": [
      {
        "tailored_audience_id": "13ld7",
        "account_id": "qsx3w2",
        "name": "my_flexible_audience_name",
        "audience_source": "FLEXIBLE_AUDIENCE",
        "upload_status": "UPLOADED",
        "segments": {
          "boolean_operator": "AND",
          "frequency": 1,
          "frequency_comparator": "NUM_GTE",
          "negate": false,
          "child_segments": [
            {
              "tailored_audience_id": "tyif",
              "lookback_window": 30,
              "frequency": 1,
              "frequency_comparator": "NUM_GT",
              "negate": true,
              "child_segments": [

              ]
            },
            {
              "boolean_operator": "OR",
              "frequency": 1,
              "frequency_comparator": "NUM_GTE",
              "negate": false,
              "child_segments": [
                {
                  "tailored_audience_id": "txr1",
                  "lookback_window": 30,
                  "frequency": 1,
                  "frequency_comparator": "NUM_GTE",
                  "negate": false,
                  "child_segments": [

                  ]
                },
                {
                  "tailored_audience_id": "tyfo",
                  "lookback_window": 30,
                  "frequency": 1,
                  "frequency_comparator": "NUM_GT",
                  "negate": true,
                  "child_segments": [

                  ]
                }
              ]
            }
          ]
        }
      }
    ],
    "created_at": "2015-11-10T21:26:43Z",
    "updated_at": "2015-11-11T01:11:47Z",
    "partner_source": "OTHER",
    "deleted": false,
    "audience_size": null
  },
  "request": [
    {
      "params": {
        "name": "my_flexible_audience_name",
        "audience_type": "FLEXIBLE",
        "segments": {
          "boolean_operator": "AND",
          "child_segments": [
            {
              "tailored_audience_id": "TYIF",
              "lookback_window": 30,
              "frequency": 1,
              "frequency_comparator": "NUM_GT",
              "negate": true,
              "child_segments": [

              ]
            },
            {
              "boolean_operator": "OR",
              "child_segments": [
                {
                  "tailored_audience_id": "TXR1",
                  "lookback_window": 30,
                  "child_segments": [

                  ]
                },
                {
                  "tailored_audience_id": "TYFO",
                  "lookback_window": 30,
                  "frequency": 1,
                  "frequency_comparator": "NUM_GT",
                  "negate": true,
                  "child_segments": [

                  ]
                }
              ]
            }
          ]
        },
        "account_id": "qsx3w2"
      },
      "operation_type": "Create"
    }
  ]
}

DELETE accounts/:account_id/tailored_audiences/:tailored_audience_id

删除属于当前账号的指定自定义受众。

资源 URL

https://ads-api.twitter.com/8/accounts/:account_id/tailored_audiences/:tailored_audience_id

参数

名称 说明
account_id
必需

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

类型：string

示例：18ce54d4x5t
tailored_audience_id
必需

请求中对正在操作的自定义受众的引用。

类型：string

示例：2906h

请求示例

DELETE https://ads-api.twitter.com/8/accounts/18ce54d4x5t/tailored_audiences/2906h

响应示例

{
  "data": {
    "targetable": false,
    "name": "developers",
    "targetable_types": [
      "CRM",
      "EXCLUDED_CRM"
    ],
    "audience_type": "CRM",
    "description": null,
    "permission_level": "READ_WRITE",
    "owner_account_id": "18ce54d4x5t",
    "id": "2906h",
    "reasons_not_targetable": [
      "TOO_SMALL"
    ],
    "created_at": "2017-08-22T23:34:26Z",
    "updated_at": "2017-08-30T18:09:00Z",
    "partner_source": "OTHER",
    "deleted": true,
    "audience_size": null
  },
  "request": {
    "params": {
      "tailored_audience_id": "2906h",
      "account_id": "18ce54d4x5t"
    }
  }
}