添加或删除受众细分群映射
您可以使用本接口添加或删除受众细分群的映射。支持的映射包括单一ID映射（每个用户或设备对应一个受众ID）和多ID映射（每个用户或设备对应多个受众ID）。
请查看流式API - 流式API相关提示，了解同一个企业号下有多个广告账号的相关提示，以及身份标识符标准化指南，了解身份标识符标准化的相关步骤。
注意
要申请访问流式 API，可以从下拉菜单中选择“流式 API”，在开发者门户网站上使用白名单管理功能。我们会持续审核申请。注意
- 频控规则：
- 每个请求中最多 10 个受众 ID。
- 每个广告账户每个app的秒级调用限制（QPS）为 5,000。
- 每个广告账户每天最多 10 亿个 ID（用户或设备 ID）。
- 流式 API 特定的频控限制为10,000 QPS（初级），20,000 QPS（标准级）， 30,000 QPS（高级），50,000 QPS（合作级）。
- 每次请求的有效负载上限为 1,000 个 ID。
- 服务等级协议：发出 API 调用后，您将立即收到成功/错误的响应。在成功的情况下，我们的系统将异步处理这些 ID，其服务等级协议时间为 48 小时。
v1.2与v1.3版本对比
以下表格概括了 v1.2与v1.3接口的变化。
``xtable
|变化内容{20%}|v1.2{40%}|v1.3{40%}|
|---|---|---|
|接口路径| /v1.2/segment/mapping/| /v1.3/segment/mapping/|
|请求参数类型|advertiser_ids: number[]|advertiser_ids: string[]|
|请求参数名称和类型|audiences（batch_data下）: number[]|audience_ids （batch_data下）: string[] |
|废弃请求参数| / |data` |
## 请求
**地址** https://business-api.tiktok.com/open_api/v1.3/segment/mapping/
**方法** POST
**Header**
``` xtable
|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。可以通过[获取访问令牌](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162)接口获取。|
|Content-Type {必填}|string|请求信息类型<br>允许格式：`application/json`。|
参数
|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|advertiser_ids {必填}|string[]| 用于添加或删除受众细分群映射的广告主ID列表。所有广告主 ID 必须属于同一个企业号。 |
| action | string | 要进行的操作。<br><br>枚举值 ：<ul><li>`add`：为单一或多个受众添加 UID 映射。</li><li>`delete`：为单一或多个受众删除 UID 映射。</li></ul> 默认值： `add`。<br><br><p><span style="color:darkred"><b>注意</b></span>: UID 指：<ul><li>加密的设备 ID（对应`id_type`为`IDFA_MD5`，`AAID_MD5`，`IDFA_SHA256`或 `AAID_SHA256`)</li><li>外部用户 ID，例如加密邮件地址或加密电话号码（对应`id_type`为`EMAIL_SHA256`或`PHONE_SHA256`）。</li></ul> |
| id_schema {必填} | string[] | 传送受众时所用的 ID 类型。<br><br> 枚举值：<ul><li>`IDFA_MD5`: 以 MD5 加密 iOS IDFA。</li><li>`AAID_MD5`: 以 MD5 加密 Android AAID 或 GAID。</li><li>`IDFA_SHA256`: 以 SHA256 加密 iOS IDFA。</li><li>`AAID_SHA256`: 以 SHA256 加密 Android AAID 或 GAID。</li><li>`EMAIL_SHA256`: 以 SHA256 加密电子邮件地址。查看[身份标识符标准化指南](1850030360880129.html)，了解身份标识符标准化的相关步骤。</li><li>`PHONE_SHA256`: 以 SHA256 加密 E.164格式 的电话号码。举例：+1231234567。</li></ul><br><p><span style="color:darkred"><b>注意</b></span>: <ul><li>不允许传入重复的ID类型。</li><li>ID 类型可按任意顺序传入，且支持将枚举值按小写形式传入。</li></ul> |
| batch_data {必填} | object[][] | 本字段包含一个 JSON 格式的数组，其中有一组或多组以下字段。本对象用于添加或删除多 ID 映射（每个用户或设备对应多个受众 ID ）。 |
#| id | string | 用户或设备 ID。 |
#| audience_ids | string[] | 用于添加或删除多 ID 映射的受众 ID（`audience_id`）数组，受众ID必须归属于传入的广告主 ID 列表（`advertiser_ids`）中的至少一个广告主。<br><br><p><span style="color:darkred"><b>注意</b></span>： 您可通过[/segment/audience/](https://ads.tiktok.com/marketing_api/docs?id=1739940583739393)获取`audience_id`。 |
示例
(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/segment/mapping/' \
--header 'Access-Token: <put_your_access_token_here>' \
--header 'Content-Type: application/json' \
--data '{
"advertiser_ids":
["{{advertiser_id}}", "{{advertiser_id}}"], // advertisers must belong to the same business account
"action":"add",
"id_schema": [
"IDFA_SHA256"
],
"batch_data": [
[
{
"id": "{{id1}}",
"audience_ids": ["17181920"] // audiences must belong to at least one of the advertisers provided in the advertiser_ids field
},
{
"id": "{{id2}}",
"audience_ids": ["17181920"]
}
],
[
{
"id": "{{id3}}",
"audience_ids": ["123456","7891011","13141516"]
},
{
"id": "{{id4}}",
"audience_ids": ["17181920","2122232425","262728293"]
}
],
[
{}, //empty because this user does not have an IDFA
{
"id": "{{id5}}",
"audience_ids": ["17181920","2122232425","262728293"]
}
]
]
}'
(/code)
返回
|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|code |number|返回码，详见[附录-返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|message |string|返回信息，详见[附录-返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|data |object|返回数据。|
|request_id |string|请求的日志id，唯一标识一个请求。|
示例
(code Success-Response http)
HTTPS/1.1 200 OK
{
"code": 200,
"message": "OK",
"request_id": "XXXXXXXXXX",
"data": {}
}
(/code);
同一个企业号下有多个广告账号
- 一个企业号可以关联多个广告账号。这种情况下，您只需要对这个企业号下的任意一个广告账号进行一次授权获得访问令牌，就能对其他广告账号使用同一个访问令牌获得这些广告账号的数据。
- 您可以使用同一个企业号下任意广告账号获得的访问令牌，向此企业号的多个广告账号创建受众目标映射。