导航|地址|刷新
标签 API-个推文档中心






文档中心开发者中心

，欢迎您！

您的优惠服务将于到期。





基本资料



安全设置



应用管理




退出登录
登录/注册SDK下载个推学堂请选择产品
消息推送

用户运营

OneID服务

AI应用工坊

统计分析

用户分析

标签管理

模型管理

短信服务

数字人外呼

一键认证

合规检测

点击提升







体验更多产品服务


欢迎登录开发者中心

立即登录

本月不再提醒





产品简介

产品使用手册
生命周期
概览

价值用户挖掘

沉默用户促活

流失用户预测

卸载原因分析


埋点行为数据采集和管理

数据统计分析和洞察

用户分层打标和群体扩量

场景模板
场景运营介绍


运营计划

用户群管理

数据管理

权限管理

流程画布

AI助手
ChatBI智能问数


Webhook
业务介绍

技术对接说明



应用场景
埋点应用场景案例


服务端
RestAPI
开发须知

接口调用规范

鉴权API

标签API

用户API

统计API

公共参数

返回码说明



客户端
Android
集成文档

API文档

使用文档

SDK集成视频


iOS
集成文档

API文档

使用文档

隐私清单说明


HarmonyOS
集成文档

API接口

使用文档


H5&小程序
集成文档

API文档


客户端插件

SDK更新日志


常见问题




当前位置：用户运营 > 服务端 > RestAPI > 标签API



标签 API


标签 API

简述

开发者可以通过标签API，查询标签画像、创建自有标签。


【标签】用户标签查询

开发者可以通过用户id列表获取画像信息。
说明：该功能为 VIP 功能，若须使用请点击右侧“技术咨询”了解详情。


接口定义

接口地址: $BaseUrl/query_tag

请求方式: POST

content-type:application/json;charset=utf-8

Request请求说明

Header参数说明

名称	类型	是否必须	默认值	描述
token	String	是	无	接口访问凭据，获取方式请参考获取鉴权token

body参数说明

入参字段定义

名称	类型	是否必须	默认值	描述
userIdList	List<String>	是	无	用户gtcid列表，size最大支持200

入参示例
{ "userIdList": [ "xxxxxx--1", "xxxxxx--2" ] }
Response响应说明

出参data字段定义

名称	类型	是否必须	默认值	描述
validTags	List<Object>	否	无	有效标签用户及标签信息返回列表
invalidTags	List<Object>	否	无	无效标签用户信息返回列表

http code: 200(http code码说明)

正常响应出参示例
{ "data": { "validTags": [ // 有效标签列表 { "userId": "gtcid1", // 用户id"tags": { // 标签信息"custom": [ // 自定义标签code列表，自定义标签可通过页面根据规则打标创建"自定义标签code1", "自定义标签code2" ], "gt": [ // 个推标签code列表"个推标签code1", "个推标签code2" ], "external": [ // 客户自有标签code列表，自有标签可通过页面、openapi根据用户id数据打标创建"客户自有标签code1", "客户自有标签code2" ] } } ], "invalidTags": [ // 无效标签列表 { "userId": "gtcid2", // 用户id"msg": "用户暂无画像", // 错误信息"code": 105// 错误码 } ] }, "code": "0", // 响应code码"msg": "成功"// 响应信息 }
请求示例
curl $BaseUrl/query_tag \ -X POST \ -H "Content-Type: application/json;charset=utf-8"\ -H "token: $token"\ -d '{ "userIdList":[ "gtcid1","gtcid2" ] }'
【标签】获取全量标签树

支持开发者通过标签树接口获取客户个推、自定义及自有标签的标签分类、标签及标签值数据，包含标签名称、编码、状态等信息。


接口定义

接口地址: $BaseUrl/query_tag_tree

请求方式: POST

content-type:application/json;charset=utf-8

Request请求说明

Header参数说明

名称	类型	是否必须	默认值	描述
token	String	是	无	接口访问凭据，获取方式请参考获取鉴权token

Response响应说明

http code: 200(http code码说明)

正常响应出参示例
{ "code": 0, "msg": "成功", "data": { "customTagList": [ // 自定义标签列表 { "name": "自定义标签名称1", // 标签分类、标签及标签值名称"code": "自定义标签code1", // 编码"type": 1, // 标签类型，0：目录,1：标签,2:标签值 "status": 0, // 状态，0：启用，1：停用"level": 1, // 自定义、自有标签返回，当前所在层级"calculationStatus": null, "childTagList": [ // 子分类/标签/标签值列表 { "name": "自定义标签标签值名称1", "code": "自定义标签标签值code1", "type": 2, "status": 0, "level": 2, "childTagList": null, "calculationStatus": null } ] } ], "externalTagList": [ // 自有标签列表 { "name": "自有标签名称1", "code": "自有标签code1", "type": 1, "status": 0, "level": 1, "childTagList": [ { "name": "自有标签标签值名称1", "code": "自有标签标签值code1", "type": 2, "status": 0, "level": 2, "childTagList": null, "calculationStatus": null } ], "calculationStatus": 0// 执行状态，仅自有标签标签类型使用，- 1 未执行 0 成功 1 失败 2 运行中 3 运行超时 4 待运行 } ], "gtagList": [ // 个推标签列表 { "name": "个推标签分类名称1", "code": "个推标签分类code1", "type": 0, "status": 0, "level": null, "childTagList": [ { "name": "个推标签名称1", "code": "个推标签code1", "type": 1, "status": 0, "level": null, "childTagList": null, "calculationStatus": null } ], "calculationStatus": null } ] } }
请求示例
curl $BaseUrl/query_tag_tree \ -X POST \ -H "Content-Type: application/json;charset=utf-8" \ -H "token: $token"
【标签】自有标签创建

支持开发者通过标签创建接口将自有标签及对应的标签值导入到【标签管理】的自有标签分类下，后续可在用户运营中用于用户群管理、画像洞察以及自定义标签的创建。


接口定义

接口地址: $BaseUrl/externalTag/add

请求方式: POST

content-type:application/json;charset=utf-8

Request请求说明

Header参数说明

名称	类型	是否必须	默认值	描述
token	String	是	无	接口访问凭据，获取方式请参考获取鉴权token

body参数说明

入参字段定义

名称	类型	是否必须	默认值	描述
dirId	Long	否	无	标签分类编码，可通过【标签管理】新建自有标签分类，并通过页面导出自有标签code获取，不传则默认在自有标签一级分类下创建标签
name	String	是	无	标签名称
description	String	否	无	标签描述
tagValueList	List<Object>	是	无	标签值列表，详细内容见TagValue

TagValue

名称	类型	是否必须	默认值	描述
tagValCn	String	是	无	标签值名称
idType	String	否	无	标签值id类型，目前支持mobile_md5，imei_md5，oaid_md5，idfa_md5，cid以及gtcid

入参示例
{ "dirId": 1, "name":"标签名称", "description":"标签描述", "tagValueList":[ { "tagValCn":"标签值名称1", "idType":"gtcid" }, { "tagValCn":"标签值名称2", "idType":"cid" } ] }
Response响应说明

http code: 200(http code码说明)

正常响应出参示例
{ "code": 0, "msg": "成功", "data": { "tagCode": "2114101", // 标签编码"name": "标签名称", // 标签名称"tagValueList": [ { "tagValCode": "2114101-1", // 标签值编码"tagValName": "标签值名称1"// 标签值名称 }, { "tagValCode": "2124101-2", "tagValName": "标签值名称2" } ] } }
请求示例
curl $BaseUrl/externalTag/add \ -X POST \ -H "Content-Type: application/json;charset=utf-8" \ -H "token: $token" \ -d '{"dirId": 1, "name":"标签名称", "description":"标签描述", "tagValueList":[ { "tagValCn":"标签值名称1", "idType":"gtcid" }, { "tagValCn":"标签值名称2", "idType":"cid" } ] }'
【标签】自有标签编辑

支持开发者通过接口对自有标签的标签名称、标签值名称、以及标签值ID类型进行编辑，同时支持清除历史标签值id数据。


接口定义

接口地址: $BaseUrl/externalTag/edit

请求方式: POST

content-type:application/json;charset=utf-8

Request请求说明

Header参数说明

名称	类型	是否必须	默认值	描述
token	String	是	无	接口访问凭据，获取方式请参考获取鉴权token

body参数说明

入参字段定义

名称	类型	是否必须	默认值	描述
dirId	Long	否	无	标签分类编码，可通过【标签管理】新建自有标签分类，并通过页面导出自有标签code获取，不传则默认在自有标签一级分类下创建标签
tagCode	String	是	无	标签编码
name	String	是	无	标签名称
description	String	否	无	标签描述
tagValueList	List<Object>	是	无	标签值列表，详细内容见TagValue

TagValue

名称	类型	是否必须	默认值	描述
tagValCn	String	是	无	标签值名称
idType	String	否	无	标签值id类型，目前支持mobile_md5，imei_md5，oaid_md5，idfa_md5，cid以及gtcid
tagValCode	String	否	无	标签值编码，不传默认为新增标签值，否则为编辑历史标签值
reset	Boolean	否	false	是否重置标签值历史上报数据，不传则默认保留历史上报数据，新增标签值（tagValCode为空）必须传true

入参示例
{ "dirId": 1, "tagCode": "2114101", "name":"标签名称", "description":"标签描述", "tagValueList":[ { "tagValCn": "标签值1", "idType": "gtcid", "tagValCode": "2114101-1", "reset": false }, { "tagValCn":"标签值2", "idType":"cid", "tagValCode": "2114101-2", "reset": true }, { "tagValCn":"标签值3", "idType":"imei_md5", "reset": true } ] }
Response响应说明

http code: 200(http code码说明)

正常响应出参示例
{ "code": 0, "msg": "成功" }
请求示例
curl $BaseUrl/externalTag/edit \ -X POST \ -H "Content-Type: application/json;charset=utf-8" \ -H "token: $token" \ -d '{ "dirId": 1, "tagCode": "2114101", "name":"标签名称", "description":"标签描述", "tagValueList":[ { "tagValCn": "标签值1", "idType": "gtcid", "tagValCode": "2114101-1", "reset": false }, { "tagValCn":"标签值2", "idType":"cid", "tagValCode": "2114101-2", "reset": true }, { "tagValCn":"标签值3", "idType":"imei_md5", "reset": true } ] }'
【标签】自有标签值数据导入

支持开发者将id数据导入至已存在的指定标签的标签值下。


接口定义

接口地址: $BaseUrl/externalTag/tagVal/data/import

请求方式: POST

content-type:application/json;charset=utf-8

Request请求说明

Header参数说明

名称	类型	是否必须	默认值	描述
token	String	是	无	接口访问凭据，获取方式请参考获取鉴权token

body参数说明

入参字段定义

名称	类型	是否必须	默认值	描述
tagValCode	String	是	无	标签值编码
idList	List<String>	是	无	用户标识id列表，根据id类型分别对应不同的id数据，详见用户id说明，size最大支持200

入参示例
{ "tagValCode": "2114101-1", "idList": [ "gtc_0000000000000000000000000000000001" ] }
Response响应说明

http code: 200(http code码说明)

正常响应出参示例
{ "code": 0, "msg": "成功" }
请求示例
curl $BaseUrl/externalTag/tagVal/data/import \ -XPOST \ -H"Content-Type: application/json;charset=utf-8" \ -H"token: $token" \ -d '{ "tagValCode": "2114101", "idList": [ "gtc_0000000000000000000000000000000001" ] }'
【标签】自有标签触发计算

支持开发者通过接口触发自有标签更新计算（请确保标签所属标签值数据已导入数据，通过open api创建、编辑的自有标签，在数据导入完成后必须调用该接口，否则标签不触发计算）。


接口定义

接口地址: $BaseUrl/externalTag/trigger

请求方式: POST

content-type:application/json;charset=utf-8

Request请求说明

Header参数说明

名称	类型	是否必须	默认值	描述
token	String	是	无	接口访问凭据，获取方式请参考获取鉴权token

body参数说明

入参字段定义

名称	类型	是否必须	默认值	描述
tagCodeList	List<String>	是	无	标签编码列表

入参示例
{ "tagCodeList": [ "2114101", "2114102" ] }
Response响应说明

http code: 200(http code码说明)

正常响应出参示例
{ "code": 0, "msg": "成功" }
请求示例
curl $BaseUrl/externalTag/trigger \ -X POST \ -H "Content-Type: application/json;charset=utf-8"\ -H "token: $token"\ -d '{ "tagCodeList": [ "2114101", "2114102" ] }'
【向量】用户向量单个查询

开发者可以通过用户id获取向量信息。
说明：该功能为 VIP 功能，若须使用请点击右侧“技术咨询”了解详情。


接口定义

接口地址: $BaseUrl/v2/query_vector

请求方式: POST

content-type:application/json;charset=utf-8

Request请求说明

Header参数说明

名称	类型	是否必须	默认值	描述
token	String	是	无	接口访问凭据，获取方式请参考获取鉴权token

body参数说明

入参字段定义

名称	类型	是否必须	默认值	描述
userId	String	是	无	用户gtcid

入参示例
{ "userId": "gtc_xxxxxxx" }
Response响应说明

出参data字段定义

名称	类型	是否必须	默认值	描述
userId	String	否	无	用户gtcid
vert	String	否	无	","分隔的向量数据
code	Integer	否	无	失败code码
msg	String	否	无	失败原因

http code: 200(http code码说明)

正常响应出参示例
{ "code": 0, "msg": "成功", "data": { "userId": "用户gtcid", "vert": ",分隔的向量数据" } }
请求示例
curl $BaseUrl/v2/query_vector \ -X POST \ -H "Content-Type: application/json;charset=utf-8" \ -H "token: $token" \ -d '{"userId":"gtc_9c1e26f29921419ea2de7fccd720d8483805"}'
【向量】用户向量批量查询

开发者可以通过用户id列表获取向量信息。【建议使用单查】
说明：该功能为 VIP 功能，若须使用请点击右侧“技术咨询”了解详情。


接口定义

接口地址: $BaseUrl/v2/batch_query_vector

请求方式: POST

content-type:application/json;charset=utf-8

Request请求说明

Header参数说明

名称	类型	是否必须	默认值	描述
token	String	是	无	接口访问凭据，获取方式请参考获取鉴权token

body参数说明

入参字段定义

名称	类型	是否必须	默认值	描述
userIdList	List<String>	是	无	用户gtcid列表，size最大支持50

入参示例
{ "userIdList": [ "gtc_xxxxxx--1", "gtc_xxxxxx--2" ] }
Response响应说明

出参data字段定义

名称	类型	是否必须	默认值	描述
validVectors	List<Object>	否	无	有效向量用户及向量信息返回列表
invalidVectors	List<Object>	否	无	无效向量用户信息返回列表

http code: 200(http code码说明)

正常响应出参示例
{ "code": 0, "msg": "成功", "data": { "validVectors": [ { "userId": "用户gtcid1", "vert": ",分隔的向量数据" }, { "userId": "用户gtcid2", "vert": "" } ], "invalidVectors": [ ] } }
请求示例
curl $BaseUrl/v2/batch_query_vector \ -X POST \ -H "Content-Type: application/json;charset=utf-8" \ -H "token: $token" \ -d '{"userIdList":["gtc_xxxxx1","gtc_xxxxx2"]}'



以上文档对您是否有帮助？
有帮助没帮助



您的改进建议

是否遇到以下问题

问题类型


1、内容与功能不一致；

2、文章描述不清晰；

3、图片和视频难理解；

4、对产品功能不满意；

5、不是我想要的内容；

6、其他:


问题类型不能为空



反馈建议



联系方式



取 消提 交





反馈成功

非常感谢您的反馈，我们会继续努力做到更好！
确定






在这篇文章中：简述【标签】用户标签查询【标签】获取全量标签树【标签】自有标签创建【标签】自有标签编辑【标签】自有标签值数据导入【标签】自有标签触发计算【向量】用户向量单个查询【向量】用户向量批量查询







文档中心搜索

搜 索















------
导航页 打开网址