OPEN API-个推文档中心

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

OPEN API

简述

开发者可以通过开放接口实现特定功能需求。

【数据导入】埋点数据导入

开发者可以通过接口导入数据。

接口定义

接口地址: $BaseUrl/import/data
请求方式: POST
content-type:application/json;charset=utf-8

Request请求说明

Header参数说明

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

body参数说明

入参字段定义

名称	类型	是否必须	默认值	描述
appId	`String`	是	无	应用id
templateId	`Long`	是	无	模版id
dataList	`List<String>`	是	无	客户埋点数据列表，size最大支持200

入参示例

{
    "templateId":3124,
    "dataList":[
      "xxxxxx--1","xxxxxx--2"
    ]
}

Response响应说明

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

{
    "msg": "成功",            // 响应信息
    "code": 0            // 响应code码
}

请求示例

curl $BaseUrl/import/data \
-X POST \
-H "Content-Type: application/json;charset=utf-8" \
-H "token: $token" \
-d '{
     "templateId":1324,
     "dataList":[
          "xxxxxx--1","xxxxxx--2"
     ]
 }'

【数据导入】外部用户导入

开发者可以通过外部用户数据导入接口导入自己感兴趣的用户id列表，用于后续在运营工具作为人群圈人、洞察的分析对象。

接口定义

接口地址: $BaseUrl/import/user/id
请求方式: POST
content-type:application/json;charset=utf-8

Request请求说明

Header参数说明

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

body参数说明

入参字段定义

名称	类型	是否必须	默认值	描述
idType	`string`	是	无	id类型，目前支持mobile_md5，imei_md5，oaid_md5，idfa_md5，cid以及gtcid
idList	`List<String>`	是	无	用户标识id列表，根据id类型分别对应不同的id数据，详见用户id说明，size最大支持200

入参示例

{
    "idType":"mobile_md5",
    "idList":[
      "md5($mobile_md5)" // 32位小写
    ]
}

Response响应说明

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

{
    "msg": "成功",            // 响应信息
    "code": 0            // 响应code码
}

请求示例

curl $BaseUrl/import/user/id \
-X POST \
-H "Content-Type: application/json;charset=utf-8" \
-H "token: $token" \
-d '{
    "idType":"mobile_md5",
    "idList":[
      "md5($mobile_md5)"
    ]
}'

【标签】用户标签查询

开发者可以通过用户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": "成功"                // 响应信息
}

个推标签code码说明文档

请求示例

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

【标签】自有标签创建

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

接口定义

接口地址: $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 > OPEN API

OPEN API

OPEN API

简述

【数据导入】埋点数据导入

接口定义

Request请求说明

Response响应说明

请求示例

【数据导入】外部用户导入

接口定义

Request请求说明

Response响应说明

请求示例

【标签】用户标签查询

接口定义

Request请求说明

Response响应说明

请求示例

【标签】自有标签创建

接口定义

Request请求说明

Response响应说明

请求示例

【标签】自有标签编辑

接口定义

Request请求说明

Response响应说明

请求示例

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

接口定义

Request请求说明

Response响应说明

请求示例

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

接口定义

Request请求说明

Response响应说明

请求示例

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

接口定义

Request请求说明

Response响应说明

请求示例

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

接口定义

Request请求说明

Response响应说明

请求示例

文档中心搜索