支持的筛选条件

您可以使用以下筛选条件缩小报表的范围。

在您开始之前，请阅读下列注意事项：

传递多个筛选条件时，筛选条件间是 AND 的关系。
当使用 IN 筛选类型时，filter_value必须是合法的 JSON 列表字符串。
示例："[\"ID1\",\"ID2\",\"ID3\"]"。
当使用 BETWEEN 筛选类型时，filter_value必须是合法的、包含两个元素的 JSON 数组字符串。
示例："[\"2022-02-24 11:57:51\",\"2022-03-24 11:57:51\"]"。

注意
- 若指定的筛选字段 field_name 和 data_level 不匹配，系统将返回报错："Invalid value for filter field: xxxx is not supported"。例如，若 data_level 为 AUCTION_AD，仅支持将 field_name 设置为广告层级的筛选字段（例如 ad_ids）。 - 异步DSA报表中仅支持campaign_ids，adgroup_ids和ad_ids为筛选条件。 - 同步竞价基础报表、受众分析报表、试玩素材报表和 DSA 报表中不包含通过 TikTok Shop 创建的商品最大成交额广告（Product GMV max ads）和直播商品交易总额最大化广告（LIVE GMV max ads）的报表数据。通过 API 或 TikTok 广告管理平台创建的购物广告则不受影响。

| 筛选字段 {23%} | 支持的筛选类型 {15%} | 支持的广告层级 {20%} | 备注 {42%} |
|---|---|---|---|
| campaign_ids | IN | 推广系列、广告组、广告| 推广系列ID，使用此筛选条件时，最多可传入100 个 `campaign_id`。筛选值示例：`"[123, 456, 789]"` 。|
| campaign_type | IN | 推广系列、广告组 | 推广系列类型。枚举值：`REGULAR_CAMPAIGN`（普通推广系列），`SKAN_CAMPAIGN`（iOS 14专属推广系列）。
| campaign_status | IN | 推广系列 | 推广系列状态，枚举值见：[枚举值-广告管理-一级状态](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138) 。<br><p><span style="color:darkred"><b>注意</b></span>：同步DSA报表中若未设置此筛选条件字段，则此字段默认设置为`STATUS_NOT_DELETE`。|
| adgroup_ids | IN | 广告组、广告 | 广告组ID，使用此筛选条件时，最多可传入100 个 `adgroup_id`。|
| adgroup_status | IN | 广告组 | 广告组状态，枚举值见： [枚举值-广告管理-一级状态](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138) 。<br><p><span style="color:darkred"><b>注意</b></span>：同步DSA报表中若未设置此筛选条件字段，则此字段默认设置为`STATUS_NOT_DELETE`。|
| ad_ids_v2 | IN | 广告 | <ul><li>可以筛选的 ID 类型包括：<ul><li>手动广告的 ID。</li><li>升级版 Smart+ <b>广告</b>（<b>素材组</b>）的 ID。</li></ul></li><li>需要将 `data_level` 设置为 `AUCTION_AD` 并在 `dimensions` 中包含 `ad_id_v2`。</li><li>使用此筛选条件时，最多可以指定 100 个值。</li><li>不能将此筛选条件与维度 `ad_id` 或筛选条件 `ad_ids` 一起使用。</li></ul> |
| ad_ids | IN | 广告 | 广告ID，使用此筛选条件时，最多可传入100 个`ad_id`。 |
| ad_status | IN | 广告 | 广告状态，枚举值见： [枚举值-广告管理-一级状态](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。<br><p><span style="color:darkred"><b>注意</b></span>：同步DSA报表中若未设置此筛选条件字段，则此字段默认设置为`STATUS_NOT_DELETE`。 |
| campaign_label_ids | IN、NOT_IN | 推广系列、广告组、广告 | 推广系列标签 ID 列表。<br><br>最大数量：50。<br><br>每个标签 ID 必须为 19 位数字字符串。<br><br><p><span style="color:darkred"><b>注意</b></span>：本筛选条件仅支持在同步报表中使用。</p> |
| campaign_label_names | CONTAIN_ANY_OF | 推广系列、广告组、广告 | 推广系列标签名称列表。<br><br>支持模糊匹配。<br><br>最大数量：10。<br><br><p><span style="color:darkred"><b>注意</b></span>：本筛选条件仅支持在同步报表中使用。</p> |
| campaign_label_types | IN、NOT_IN | 推广系列、广告组、广告 | 推广系列标签类型列表。<br><br>枚举值：<ul><li>`GENERAL`：通用标签。</li><li>`MARKETING_EVENT`：营销事件标签。</li></ul><br><p><span style="color:darkred"><b>注意</b></span>：本筛选条件仅支持在同步报表中使用。</p> |
| promotion_type | IN | 推广系列、广告组、广告 | 推广对象类型（优化位置）。<br><br>枚举值：<ul><li>`APP`：应用。</li><li>`WEBSITE`：落地页。</li><li>`INSTANT_FORM`：线索表单（即时表单）。</li><li>`LEAD_GEN_CLICK_TO_TT_DIRECT_MESSAGE`：TikTok 私信。</li><li>`LEAD_GEN_CLICK_TO_SOCIAL_MEDIA_APP_MESSAGE`：社交媒体应用。</li><li>`LEAD_GEN_CLICK_TO_CALL`：电话通话。</li><li>`OTHERS`：其他。</li></ul><br>本筛选条件只能用于同步报表中。|
| dpa_target_audience_type | IN | 推广系列、广告组、广告| DPA广告的受众类型。枚举值： `RETARGETING`, `PROSPECTING`。本筛选条件只能用于同步报表中。 |
|create_time| BETWEEN | 推广系列、广告组、广告 | 传入的ID维度（`campaign_id`/`adgroup_id`/`ad_id`）的创建时间范围。使用此筛选条件时，筛选的值需要是合法的、包含两个元素的 JSON数组字符串，第一个元素为开始时间，第二个元素为结束时间。举例：`"[\"2022-02-24 11:57:51\",\"2022-03-24 11:57:51\"]"`。本筛选条件只能用于同步报表中。<br>建议：为了让任务成功执行及任务速度不受影响，创建时间的范围建议在6个月以内。|
|create_time| GREATER_THAN | 推广系列、广告组、广告| 传入的ID维度（`campaign_id`/`adgroup_id`/`ad_id`）的最早创建时间。格式：`YYYY-MM-DD HH:MM:SS`（UTC时区）。举例：`"2022-02-24 11:57:51"` 将返回晚于该时间创建的维度。本筛选条件只能用于同步报表中。<br>建议：为了让任务成功执行及任务速度不受影响，创建时间的范围建议在6个月以内。|
|create_time| LOWER_THAN |推广系列、广告组、广告 | 传入的ID维度（`campaign_id`/`adgroup_id`/`ad_id`）的最晚创建时间。格式：`YYYY-MM-DD HH:MM:SS`（UTC时区）。举例：`"2022-02-24 11:57:51"` 将返回早于该时间创建的维度。本筛选条件只能用于同步报表中。<br>建议：为了让任务成功执行及任务速度不受影响，创建时间的范围建议在6个月以内。|