标签 API-个推文档中心

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

标签 API

简述

开发者可以通过标签API，查询标签画像、创建自有标签。
说明：标签API涉及的功能为 VIP 功能，若须使用请点击右侧“技术咨询”了解详情。

【标签】用户标签查询

开发者可以通过用户id列表获取画像信息。

接口定义

接口地址: $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 \
-X POST \
-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/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
vert1	String	否	无	","分隔的256位向量数据
Vert3	String	否	无	","分隔的128位向量数据
code	Integer	否	无	失败code码
msg	String	否	无	失败原因

http code: 200(http code码说明)
正常响应出参示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "userId": "用户gtcid",
    "vert1": ",分隔的256位向量数据",
    "vert3": ",分隔的128位向量数据"
  }
}

请求示例

curl $BaseUrl/query_tag \
-X POST \
-H "Content-Type: application/json;charset=utf-8" \
-H "token: $token" \
-d '{"userId":"gtc_9c1e26f29921419ea2de7fccd720d8483805"}'

【向量】用户向量批量查询

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

接口定义

接口地址: $BaseUrl/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",
        "vert1": ",分隔的256位向量数据",
        "vert3": ",分隔的128位向量数据"
      },
      {
        "userId": "用户gtcid2",
        "vert1": "",
        "vert3": ""
      }
    ],
    "invalidVectors": [
    ]
  }
}

请求示例

curl $BaseUrl/batch_query_vector \
-X POST \
-H "Content-Type: application/json;charset=utf-8" \
-H "token: $token" \
-d '{"userIdList":["gtc_xxxxx1","gtc_xxxxx2"]}'

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

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

标签 API

标签 API

简述

【标签】用户标签查询

接口定义

Request请求说明

Response响应说明

请求示例

【标签】获取全量标签树

接口定义

Request请求说明

Response响应说明

请求示例

【标签】自有标签创建

接口定义

Request请求说明

Response响应说明

请求示例

【标签】自有标签编辑

接口定义

Request请求说明

Response响应说明

请求示例

【标签】自有标签值数据导入

接口定义

Request请求说明

Response响应说明

请求示例

【标签】自有标签触发计算

接口定义

Request请求说明

Response响应说明

请求示例

【向量】用户向量单个查询

接口定义

Request请求说明

Response响应说明

请求示例

【向量】用户向量批量查询

接口定义

Request请求说明

Response响应说明

请求示例

文档中心搜索