菜单

通过OpenApi 导出实体列表

套餐版本要求：

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
// 导出到表 默认以该种形式，需要通过 jdbc 的方式拉取数据
{
"format_type": "TABLE"
}
// 导出到文件，需要通过导出文件的接口拉取数据（需要套餐 >= SA 3.0.2）
{
  "format_type": "FILE"
}

拉取数据的方式见下方详细接口说明.
project_id 项目 id int 是 2

segment_rule_expression

 分群规则 object 是

分群：下面例子的含义为分群为真

{
    "type": "EQL_BASED",
    "eql_segment_rule": {
        "eql": "user.$SegmentMembership.{分群名} == true"
    }
}

标签：下面的含义为标签有值

{
    "type": "EQL_BASED",
    "eql_segment_rule": {
        "eql": "user.{标签名}.is_not_null()"
      }
}

// 如果想指定 base_time 即获取某一天的分群 / 标签数据，增加 @{yyyyMMdd} 后缀即可，默认情况下拉取最新一份数据.

{
    "type": "EQL_BASED",
    "eql_segment_rule": {
        "eql": "user.$SegmentMembership.{分群名}@20240115 == true"
     }
}

请求示例：

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 
/**
 * 新建, 还没有被调度执行
 */
NEW = 1;
/**
 * 运行中
 */
RUNNING = 2;
/**
 * 成功
 */
SUCCESS = 3;
/**
 * 失败
 */
FAILED = 4;
 
success_result
 成功信息，主要包含导出的结果信息 object

任务状态成功时，会返回如下信息

导出为 TABLE:

{
    "table_result": {

        // 数据库名称
        "database_name": "horizon_workspace_production_2",

        // 表名称
        "table_name": "user_list_fcakj",

        // 过期时间 超过该时间表会被清理
        "expire_time": "2023-07-20T09:50:17.025Z"
    }
}

导出为 FILE:

{
    "file_result": {

        // 文件 token, 即文件导出接口入参中的文件标识
        "file_token": "2ef3b6c60daa464e8fd87acb9439b90c",
        "expire_time": "2025-01-17T07:59:59.569Z"
    }
}

默认情况数据 (TABLE/FILE) 两天后自动过期清理.
failed_result 失败信息，主要包含失败提示信息 object

{
    "failure_message":"Out Of Memory"
}

请求示例：

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
上一个
数据导出
下一个
数据导入
最近修改: 2025-07-09