套餐版本要求:
TABLE 导出方式大于等于 SA3.0.1
FILE 导出方式大于等于 SA 3.0.2
背景
在使用神策数界系统管理实体标签及分群时,如果想让系统标签数据对接到自己的内部系统,在神策数界中,提供了一种交互方式去实现该功能。步骤如下:
- 创建分群 / 标签,并计算完成
- 调用实体群包生成 API,生成数据表 或 生成文件
- 通过 JDBC 方式导出数据表数据
- 调用文件下载接口(套餐SA 3.0.2+ 开始提供),下载文件
创建实体列表导出任务
URL | 请求方法 | 参数格式 | 描述 |
/api/v3/horizon/v1/entity-list/export-task/create | POST | application/json | 创建实体列表导出任务 |
请求参数
字段名 |
字段含义 | 字段类型 | 是否必填 | 示例 |
attribute_paths | 需要导出的属性列表 | array |
是,且必须包含实体主键, 可在【数据接入】-【元数据管理】-【用户表】中查看可以导出的属性列表,即需要导出的实体属性列表 (确定表头) |
["id", "age", "name","city"], 即导出 id, age, name, city 4 列属性. |
entity_name | 实体名称 | string | 是 |
user |
export_format | 输出方式 | object | 否 |
非必填,默认情况导出 TABLE 拉取数据的方式见下方详细接口说明. |
project_id | 项目 id | int | 是 | 2 |
segment_rule_expression |
分群规则 | object | 是 |
分群:下面例子的含义为分群为真
标签:下面的含义为标签有值
// 如果想指定 base_time 即获取某一天的分群 / 标签数据,增加 @{yyyyMMdd} 后缀即可,默认情况下拉取最新一份数据.
|
请求示例:
curl "http://{host}:{port}/api/v3/horizon/v1/entity-list/export-task/create" \
-H "Content-Type: application-json" \
-H "sensorsdata-project: {projectName}" \
-H "api-key: {ApiKey}" \
-d '{
"entity_name": "user",
"segment_rule_expression": {
"type": "EQL_BASED",
"eql_segment_rule": {
"eql": "user.$SegmentMembership.{分群名} == true"
}
},
"attribute_paths": [
"id",
"age",
"name",
"city"
]
}'
返回值示例:
{
"code": "SUCCESS",
"request_id": "21181032a2d85cc8f8bd403b8d374c19",
"data": {
"task_id": 1
}
}
查询实体列表导出任务结果
通过该接口可以查询到上一步提交的任务状态。可以通过轮训该接口来判断上一步提交的导出任务是否成功还是失败。
URL | 请求方法 | 参数格式 | 描述 |
/api/v3/horizon/v1/entity-list/export-task/get-status | GET | URL-PARAM | 查询实体列表导出任务 |
请求参数
参数名称 | 描述 | 类型 | 是否必填 | 示例 |
task_id | 任务 id | int | 是 | 1 |
返回字段
字段信息 | 描述 | 类型 | 示例 |
project_id | 项目 id | int | 2 |
task_id | 任务 id | int | 1 |
status | 任务状态 | string |
|
success_result |
成功信息,主要包含导出的结果信息 | object |
任务状态成功时,会返回如下信息 导出为 TABLE: { // 数据库名称 // 表名称 // 过期时间 超过该时间表会被清理 导出为 FILE: { // 文件 token, 即文件导出接口入参中的文件标识 默认情况数据 (TABLE/FILE) 两天后自动过期清理. |
failed_result | 失败信息,主要包含失败提示信息 | object |
{ |
请求示例:
curl "http://{host}:{port}/api/v3/horizon/v1/entity-list/export-task/get-status?task_id=1" \
-H "sensorsdata-project: {projectName}" \
-H "api-key: {ApiKey}"
任务未执行完成返回json
{
"code": "SUCCESS",
"request_id": "21181032a2d85cc8f8bd403b8d374c19",
"data": {
"project_id": 2,
"task_id": 1,
"status": "NEW"
}
}
任务执行失败的返回json
{
"code": "SUCCESS",
"request_id": "21181032a2d85cc8f8bd403b8d374c19",
"data": {
"project_id": 2,
"task_id": 1,
"status": "FAILED",
"failed_result": {
"failure_message": "Out Of Memory"
}
}
}
TABLE 导出方式成功返回json
{
"code": "SUCCESS",
"request_id": "21181032a2d85cc8f8bd403b8d374c19",
"data": {
"project_id": 2,
"task_id": 1,
"status": "SUCCESS",
"success_result": {
"table_result": {
"database_name": "horizon_workspace_production_2",
"table_name": "user_list_fcakj",
"expire_time": "2023-07-20T09:50:17.025Z"
}
}
}
}
FILE 导出方式成功返回json(SA 3.0.2)
{
"code": "SUCCESS",
"request_id": "101601209c70239bca3778eb24fe4283",
"data": {
"project_id": 3,
"task_id": 11,
"success_result": {
"file_result": {
"file_token": "2ef3b6c60daa464e8fd87acb9439b90c",
"expire_time": "2025-01-17T07:59:59.569Z"
}
},
"status": "SUCCESS"
}
}
获取导出结果
TABLE 导出方式
通过 jdbc 的形式进行下载,需要注意使用时注意并发,避免给 impala 带来负担.
参考文档:神策官网 - 使用 JDBC 进行数据访问
结果样例
- 表中的结果已经经过了权限过滤,但属性脱敏目前暂未实现,参考数据权限文档
- 字段名称即导出时候的属性名称,注意不区分大小写
- 请在过期时间内进行结果的获取,超过该时间会被清理
- 通过返回结果去获取数据库名称和表名称,不要硬编码
表结构样例
Query: describe user_list_fcakj
+-----------------+--------------------------+---------+
| name | type | comment |
+-----------------+--------------------------+---------+
| id | bigint | |
| normal_number01 | decimal(19,3,fixedpoint) | |
| normal_bool01 | bigint | |
| email | string | |
| hobbies | string | |
| register_time | bigint | |
+-----------------+--------------------------+---------+
属性值样例
数据类型 | 值(示例) |
字符串 | abc |
布尔 | 1 |
数值 | 100.100 |
日期 | 1706583289000 |
集合 | abc\ndef |
FILE 导出方式
使用文件下载接口获取即可
URL | 请求方法 | 参数格式 | 描述 |
/api/v3/horizon/v1/web/file-storage/download | GET | URL-PARAM | 下载文件 |
请求参数
参数名称 | 数据类型 | 值(示例) | 是否必填 | 描述 |
file_token | string | 例:21181032a2d85cc8f8bd403b8d374c19 | true | 上传文件返回的 file_token. |
请求示例
curl "http://{host}:{port}/api/v3/horizon/v1/web/file-storage/download?file_token={token信息}" \
-H "sensorsdata-project: {projectName}" \
-H "api-key: {ApiKey}"
返回值就是文件流
数据样例
- 由于特殊字符显示问题,"^A" 需要使用 "\1" 解析,为字段 / 列分隔符
- 由于特殊字符显示问题,"^C" 需要使用 "\3" 解析,为 list 类型数据分隔符
- "\N" 表示无数据
数据类型 | 值(示例) |
字符串 | abc |
布尔 | 1 或 0 |
数值 | 100.100 |
日期 | 1706583289000 |
集合 | abc\3def |