文档中心 登录/注册 SDK下载 个推学堂

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

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

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

{
  "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)"
    ]
}'

【用户群导出】用户群列表查询

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

接口定义

  • 接口地址: $BaseUrl/export/crowd/exportableCrowdList
  • 请求方式: POST
  • content-type:application/json;charset=utf-8

Request请求说明

Header参数说明

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

Response响应说明

  • 出参data字段定义
名称 类型 是否必须 默认值 描述
list List<Object> 否 无 用户群列表,目前最大size=100
total Long 否 无 用户群列表数量 
{
  "data": {
    "list": [
      // 用户群列表
      {
        "crowdId": "crowdId1",
        // 用户群id
        "crowdName": "用户群1"
        // 用户群名称
      }
    ],
    "total": 100
    // 列表数量
  },
  "code": "0",
  // 响应code码
  "msg": "成功"
  // 响应信息
}

请求示例

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

【用户群导出】创建用户群导出任务

开发者可以通过该接口创建用户群导出任务。
说明：创建用户群导出任务为 VIP 功能，若须查询请点击右侧“技术咨询”了解详情。

接口定义

  • 接口地址: $BaseUrl/export/crowd/createCrowdExportTask
  • 请求方式: POST
  • content-type:application/json;charset=utf-8

Request请求说明

Header参数说明

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

body参数说明

  • 入参字段定义
名称 类型 是否必须 默认值 描述
crowdId String 是 无 用户群id
uidType String 是 无 导出ID类型，目前支持CID和GTCID,大小写敏感。CID仅在创建用户群时对接推送或文件上传CID创建用户群时支持
  • 入参示例
{
  "crowdId": "crowdId1",
  "uidType": "GTCID"
}

Response响应说明

  • 出参data字段定义
名称 类型 是否必须 默认值 描述
taskId Long 否 无 任务id 
{
  "data": {
    "taskId": 1001
    // 任务id
  },
  "code": "0",
  // 响应code码
  "msg": "成功"
  // 响应信息
}

请求示例

curl $BaseUrl/export/crowd/createCrowdExportTask\
-X POST \
-H "Content-Type: application/json;charset=utf-8" \
-H "token: $token" \
-d '{
    "crowdId": "crowdId1",
    "uidType": "GTCID"
}'

【用户群导出】用户群导出任务列表查询

开发者可以通过该接口获取用户群导出任务列表信息。
说明：用户群导出任务列表查询为 VIP 功能，若须查询请点击右侧“技术咨询”了解详情。

接口定义

  • 接口地址: $BaseUrl/export/crowd/exportCrowdTaskList
  • 请求方式: POST
  • content-type:application/json;charset=utf-8

Request请求说明

Header参数说明

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

Response响应说明

  • 出参data字段定义
名称 类型 是否必须 默认值 描述
list List<Object> 否 无 用户群导出任务列表
total Long 否 无 用户群导出任务列表数量 
{
  "data": {
    "list": [
      // 用户群导出任务列表
      {
        "appId": "appId1",
        // 应用id
        "crowdId": "crowdId1",
        // 用户群id
        "taskId": 1001,
        // 任务id
        "uidType": "GTCID",
        // 导出ID类型
        "status": 1,
        // 任务状态,0:执行中、1：成功、2：失败
        "fileIdList": [
          // 文件Id列表，任务状态为成功时返回    
          "9e385078-8210-4ebc-a4fe-e8edde2476eb",
          "9e385078-8210-4ebc-a4fe-e8edde2476ec"
        ]
      }
    ],
    "total": 100
    // 列表数量
  },
  "code": "0",
  // 响应code码
  "msg": "成功"
  // 响应信息
}
  • 返回参数data说明
名称 类型 描述
$list List<Object> 用户群导出任务列表
appId String 应用id
crowdId String 用户群id
taskId Long 任务id
uidType String 导出ID类型
status Byte 任务状态,0:执行中、1：成功、2：失败
fileIdList List<String> 文件Id列表，任务状态为成功时返回。使用fileId导出用户群单个文件，目前最大size=50
$total Long 列表数量

请求示例

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

【用户群导出】用户群单个文件导出

开发者可以通过该接口导出用户群Id数据。
说明：用户群单个文件导出为 VIP 功能，若须查询请点击右侧“技术咨询”了解详情。

接口定义

  • 接口地址: $BaseUrl/export/crowd/exportCrowdSingleFile
  • 请求方式: POST
  • content-type:application/json;charset=utf-8

Request请求说明

Header参数说明

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

body参数说明

  • 入参字段定义
名称 类型 是否必须 默认值 描述
crowdId String 是 无 用户群id
taskId Long 是 无 任务id
fileId String 是 无 导出文件id
  • 入参示例
{
  "crowdId": "crowdId1",
  "taskId": 1001,
  "fileId": "9e385078-8210-4ebc-a4fe-e8edde2476eb"
}

Response响应说明

  • 出参data字段定义
名称 类型 是否必须 默认值 描述
list List<String> 否 无 id列表，目前最大size=1000000
total Long 否 无 id列表数量 
{
  "data": {
    "list": [
      // id列表
      "gtcid1",
      "gtcid2"
    ],
    "total": 10000000
    // id数量
  },
  "code": "0",
  // 响应code码
  "msg": "成功"
  // 响应信息
}

请求示例

curl $BaseUrl/export/crowd/exportCrowdSingleFile\
-X POST \
-H "Content-Type: application/json;charset=utf-8" \
-H "token: $token" \
-d '{
    "crowdId": "crowdId1",
    "taskId": 1001,
      "fileId": "9e385078-8210-4ebc-a4fe-e8edde2476eb"
}'

【标签】用户标签查询

开发者可以通过用户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> 否 无 无效标签用户信息返回列表 
{
  "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"]}'
在这篇文章中： 简述 【数据导入】埋点数据导入 【数据导入】外部用户导入 【用户群导出】用户群列表查询 【用户群导出】创建用户群导出任务 【用户群导出】用户群导出任务列表查询 【用户群导出】用户群单个文件导出 【标签】用户标签查询 【标签】获取全量标签树 【标签】自有标签创建 【标签】自有标签编辑 【标签】自有标签值数据导入 【标签】自有标签触发计算 【向量】用户向量单个查询 【向量】用户向量批量查询

文档中心搜索

技术
咨询

微信扫一扫

随时联系技术支持

在线
咨询