标签 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> 无效标签用户信息返回列表
{
  "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响应说明

{
  "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响应说明

{
  "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响应说明

{
  "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响应说明

{
  "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响应说明

{
  "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 失败原因
{
  "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> 无效向量用户信息返回列表
{
  "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"]}'

文档中心搜索

技术
咨询

微信扫一扫

随时联系技术支持

在线
咨询