修改受众

您可以使用本接口修改已创建的受众群体。

对于客户文件受众，TikTok API for Business支持以下三种修改操作：
1. REPLACE （替换）：用参数中的数据文件去替换之前（所有）的数据文件
2. APPEND（新增）：增加新的数据文件
3. REMOVE （移除）：移除指定的数据文件

提示

请查看下表了解本接口相关的限额，任务并行和支持范围限制。

| 类型 {30%}| 详情{70%} |
|---|---|
| 限额 | <ul><li>受众修改操作的限额为每连续的 24 小时内 24 次（新增，移除或替换），该限制为受众层级的限制。</li><li> 通过文件“替换”受众的操作限额为每日1次，该限制为受众层级的限制。</li></ul> |
| 任务并行| <ul><li>需先等待当前的受众修改操作完成，再进行新的修改操作，该限制为受众层级的限制。</li><li> 若有进行中的“替换”（`REPLACE`）操作，则新的“替换”操作会被拒绝。</li></ul>|
| 支持范围 |<ul><li> 只有客户文件受众支持修改受众文件。</li><li> 广告互动受众/应用事件受众/网站访客受众/相似受众仅支持修改受众名称。</li><li> 对于即将过期或者已过期的受众群体，您只能将其删除，而无法进行其他修改。您可以使用`is_expiring`和`expired_time`查找相应的受众群体。</li><li>新增（`APPEND`）、移除（`REMOVE`）或替换（`REPLACE`）操作成功的前提是操作完成后受众大小不低于1000。否则新增、移除或替换操作将会失败。</li><li>对于`REMOVE` （移除）：您只能移除部分数据文件，不能移除全部的数据文件。</li></ul>|
|服务等级协议 |发出API调用后，您将立即收到成功/错误的响应。在成功的情况下，我们的系统将异步处理这些ID，其服务等级协议时间为48小时。 |

v1.2与v1.3版本对比

以下表格概括了 v1.2与v1.3接口的变化。 ``xtable |变化内容{30%}|v1.2{35%}|v1.3{35%}| |---|---|---| |接口路径| /v1.2/dmp/custom_audience/update/|/v1.3/dmp/custom_audience/update/| |请求参数类型|advertiser_id: number custom_audience_id: number |advertiser_id: string custom_audience_id: string | |新增请求参数|/|file_paths: string | |废弃请求参数|/|file_path`: string[]
|


## 请求

**地址** https://business-api.tiktok.com/open_api/v1.3/dmp/custom_audience/update/

**方法** POST

**Header**

``` xtable
|字段{30%}|类型{10%}|描述{60%}|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。可以通过[获取访问令牌](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162)接口获取。|
|Content-Type {必填}|string|请求信息类型<br>允许格式：`application/json`。|

参数

|字段{30%}|类型{10%}|描述{60%}|
|---|---|---|
|advertiser_id {必填}|string|广告主ID。|
|custom_audience_id {必填}|string|自定义受众ID。|
|custom_audience_name {+条件必填}|string|自定义受众的新名称。限128字符内。该字段和`file_paths`字段至少要传一个。|
|audience_sub_type|string| 受众子类型，表明该受众可用于的广告类型。<br>允许的枚举值：`REACH_FREQUENCY`（允许在覆盖和频次推广系列中使用此受众）。这意味着您只能将受众子类型从`NORMAL`改为`REACH_FREQUENCY`，而无法反向操作。<br><p><span style="color:darkred"><b>注意</b></span>：<p><ul><li>如果更新本字段，其他字段的更新会被忽略。<li>如果您想要更新相似受众，不能将`audience_sub_type`设置为`REACH_FREQUENCY`，否则会出错。|
|file_paths{+条件必填}|string[]|用于更新客户文件受众的数据文件。该字段和`custom_audience_name`字段至少要传一个。<br>为确保稳定性，单次请求推荐数量<b><50</b>。<br>传入本字段后，您可以传入`action`字段指定操作类型（`APPEND`, `REMOVE` 或 `REPLACE`）。<br>这些文件必须与您要修改的受众使用相同的加密方法进行加密。|
|action |string|数据文件操作类型。当传入`file_paths`时，该字段有效。枚举值: <ul><li>`APPEND`：上传文件扩充原始客户文件受众数据。仅增加原始文件中没有的数据。</li><li>`REMOVE`：上传文件删除原始客户文件受众数据。仅删除与原始文件重复的数据。</li><li>`REPLACE`：上传文件替换原始客户文件受众数据。替换全部原始受众数据。</li></ul>默认值: `REPLACE`。<br><p><span style="color:darkred"><b>注意</b></span>：新增（`APPEND`），移除（`REMOVE`）或替换（`REPLACE`）操作成功的前提是操作完成后受众大小不低于1000。否则新增、移除或替换操作将会失败。|

示例

(code curl http)
curl -H "Access-Token:xxx" -H "Content-Type:application/json" -X POST \\
-d '{
    "action": "ACTION", 
    "advertiser_id": "ADVERTISER_ID", 
    "custom_audience_id": "CUSTOM_AUDIENCE_ID", 
    "file_paths": ["FILE_PATHS"]
}' \\
https://business-api.tiktok.com/open_api/v1.3/dmp/custom_audience/update/
(/code)

|字段|类型|描述|
|---|---|---|
|code |number|返回码，详见[附录-返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|message |string|返回信息，详见[附录-返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|data |object|返回数据。<br>本字段将返回空对象（`{}`）。  |
|request_id |string|请求的日志id，唯一标识一个请求。  |

示例

(code Success-Response http)
HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {}
}
(/code);