数据集信息 API--智能数据洞察-火山引擎

文档中心

导航

数据集信息 API

最近更新时间：2025.03.27 14:43:04首次发布时间：2024.03.15 14:50:59

1. 概述

本文为您介绍的是“数据集信息类的 Open API”，您将了解到用户可以通过 API 进行查看数据集详情页、编辑页的基础信息以及更新基础信息、设置标签等操作。
注意：在您使用本文所述的 API 前，还需完成接入 JWT-Token 和申请 Token 的前置操作，请先了解调用方式，详情可阅读调用方式。

2. 接口介绍

2.1 查看数据集信息-详情页

权限需求
资源
权限
数据集
read
接口描述与说明：获取数据集详情页展示的数据集信息内容

资源	权限
数据集	read

请求说明

请求地址：{{domain}}/aeolus/api/v4/open/dataset/{{dataSetId}}/overview

请求示例

curl --location --request GET '{{domain}}/aeolus/api/v4/open/dataset/{{dataSetId}}/overview' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{jwtToken}}'

请求参数

名称	类型	必选	示例值	描述
dataSetId	integer	是	123	数据集ID

返回参数

参数	类型	描述
accessCount	integer	数据集30天相关图表访问量
appId	integer	项目Id
connectionMode	integer	数据集连接模式[0:抽取, 1:直连]
ctime	datetime	数据集创建时间
dagTagConf.dimTbNodes	list	维度表节点Id
demoUrl	string	数据集使用说明
descr	string	数据集描述
doradoPriority	string	同步任务优先级[normal、high、super_high]
driverName	string	存储引擎
editable	boolean	数据集是否可以修改[true、false]
frequency	string	数据集同步的频率[daily、hourly、weekly、monthly]
hot	integer	访问热度[0：没热度]
id	integer	数据集ID
lastSyncTime	datetime	最近同步时间
lineNum	integer	数据集所存数据条数
mtime	datetime	数据集最近修改时间
name	string	数据集名称
onPrivateCluster	integer	数据集是否建立于私有集群[0：不是私有集群；1：是私有集群]
roleList	list	当前token身份拥有的数据集权限 [admin所有者"、read_role读角色、 write_role写角色"、view_only_role仅阅览角色"、 read_all_role全局查看角色]
size	float	数据集所存数据大小[单位是动态的，可能是KB, MB, GB...]
sourceKey	string	数据集建立/输出来源 [abi, cdp, prep] 说明：prep表示通过可视化建模生成的数据集
status	integer	数据集状态；0为正常状态
syncMode	integer	同步模式[0: Dorado各种to ClickHouse通道任务、1: 可视化建模任务、2: Dorado hsql任务，利用tqs执行导入]
syncType	integer	同步调度模式[1为自动同步; 2为手动同步]
ttl	integer	数据集生命周期 -> 数据保存周期，默认7天说明：定义是数据集的生命周期，实际指的是数据集的数据保存周期。比如默认7天的话，那么7天之前生成的数据都会被删除。
type	integer	数据集类型[常见的几种:0: ClickHouse表作为数据源生成的数据集、2: Hive表作为数据源生成的数据集、8: 自定义SQL生成的数据集、10: MySQL表作为数据源生成的数据集、22: Prep类型的数据集]
writePartition	integer	写入分区 [0为写入天分区; 1为写入天+小时分区]
sensitiveConf	string	数据集脱敏设置[ undef:未设置脱敏 sensitiveWithoutDe:涉敏未脱敏 sensitiveWithDe：涉敏已脱敏 unsensitive不涉敏]

返回示例

{
    "code": "aeolus/ok",
    "data": {
        "accessCount": 0,
        "appId": 77*****,
        "connectionMode": 0,
        "ctime": "2022-12-14 12:17:54",
        "dagTagConf": {
            "dimTbNodes": []
        },
        "dataSetLabelType": 0,
        "demoUrl": "http://xxx.com",
        "descr": "这是一段描述，描述数据集的作用",
        "disablePreview": 0,
        "doradoPriority": "normal",
        "driverName": "click_house",
        "editable": true,
        "frequency": "daily",
        "groupId": 193,
        "groupName": "test-no-multiple",
        "groupType": 0,
        "hot": 0,
        "id": {{dataSetId}},
        "isAppAdminView": 1,
        "lastSyncTime": "2022-12-14 12:38",
        "lineNum": "56",
        "mtime": "2022-12-14 12:18",
        "name": "测试open-api专用数据集1",
        "onPrivateCluster": 0,
        "ownerEmailPrefix": "userEmailPrefix",
        "parentId": 3075,
        "partitionRange": [
            {
                "id": 158**********,
                "max": "2022-12-13",
                "min": "2022-12-13",
                "name": "p_date"
            }
        ],
        "previewInfo": "",
        "retryNum": 0,
        "roleList": [
            {
                "action": "admin",
                "roleName": "所有者"
            },
            {
                "action": "view_only_role",
                "roleName": "仅阅览角色"
            },
            {
                "action": "write_role",
                "roleName": "写角色"
            },
            {
                "action": "read_role",
                "roleName": "读角色"
            }
        ],
        "size": "2.86KB",
        "slaStatus": 0,
        "sourceKey": "abi",
        "status": 0,
        "statusDesc": "正常",
        "syncMode": 2,
        "syncType": 1,
        "tagInfo": null,
        "thirdPartyConf": {},
        "ttl": 7,
        "type": 22,
        "uneditableReason": null,
        "writePartition": 0,
        "yarnName": "root.default_hrtech_da_pm"
    },
    "msg": "成功"
}

2.2 查看数据集完整信息-编辑页

权限需求
资源
权限
数据集
read
接口描述与说明获取数据集完整信息，对应前端的数据集编辑页

资源	权限
数据集	read

请求说明

请求地址：{{domain}}/aeolus/api/v4/open/dataset/{{dataSetId}}/info

请求示例

curl --location --request GET '{{domain}}/aeolus/api/v4/open/dataset/{{dataSetId}}/info' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{jwtToken}}'

请求参数

参数	类型	必选	示例值	描述
dataSetId	integer	是	123	数据集ID

返回参数

参数(jsonPath)	类型	描述
$.baseConf	object	数据集基础内容
$.baseConf.appId	integer	项目Id
$.baseConf.demoUrl	string	数据集使用说明
$.baseConf.name	string	数据集名称
$.baseConf.ownerEmailPrefix	string	数据集拥有者
$.baseConf.parentId	integer	数据集所在文件夹，0则代表在根目录
$.baseConf.syncMode	integer	同步模式 [1为手动;2为自动]
$.baseConf.type	integer	数据集类型[常见的几种:0: ClickHouse表作为数据源生成的数据集、2: Hive表作为数据源生成的数据集、8: 自定义SQL生成的数据集、10: MySQL表作为数据源生成的数据集、22: Prep类型的数据集]
$.dagTagConf.dimTbNodes	list	数据集维度表节点 nodeId
$.syncConf	object	数据集同步任务配置
$.whereConf	object	数据集模型数据源节点筛选条件及全局筛选条件

返回示例

{
    "code": "aeolus/ok",
    "data": {
        "baseConf": {
            "appId": 77*****,
            "confidentiality": "L3",
            "connectionMode": 0,
            "demoUrl": null,
            "descr": "这是一段描述，描述数据集的作用",
            "generalTags": [],
            "groupId": 19*,
            "groupName": "test-no-multiple",
            "groupType": 0,
            "id": {{dataSetId}},
            "isAuthEnabled": 1,
            "isIntelligentSyncEnable": 1,
            "lineOfBusiness": [],
            "name": "测试open-api专用数据集1",
            "ownerEmailPrefix": "userEmailPrefix",
            "parentId": 3075,
            "productName": "",
            "regionType": [],
            "syncMode": 2,
            "thirdPartyConf": null,
            "type": 22
        },
        "dagTagConf": {
            "dimTbNodes": []
        },
        "dimMetList": [
            {
                "calcType": null,
                "dataFormat": null,
                "dataTypeName": "date",
                "defaultDataTypeName": "date",
                "descr": "p_date",
                "dimMetCategoryId": null,
                "dimMetCategoryType": null,
                "dimMetMixOrder": 0,
                "dimMetOrder": 0,
                "dimMetThirdPartyConf": null,
                "dimMetVariety": 1,
                "editable": 0,
                "errCode": "ok",
                "expr": "p_date",
                "exprAsDim": null,
                "fieldList": "[\"p_date\"]",
                "fullExpr": "p_date",
                "groupType": 0,
                "hitFilterRuleList": [],
                "id": 158**********,
                "isDeletedField": 0,
                "isPartitionField": 1,
                "lodType": null,
                "mapType": 0,
                "name": "p_date",
                "operationCode": 0,
                "ownerEmailPrefix": "userEmailPrefix",
                "paramIdList": [],
                "showExpr": 1,
                "visible": 1
            },
            .........
        ],
        "labelConf": {
            "dataSetLabelType": 0,
            "labelParams": null,
            "subjectList": null
        },
        "linkConf": [],
        "nodeConf": [
            {
                "clusterName": "cn",
                "dataSourceId": 25***,
                "dataSourceType": "ch_excel",
                "dbName": "aeolus_excel_upload_aeolus_toy",
                "displayDbName": "配比四刷-v4",
                "fields": [
                    {
                        "alias": "`字段四`",
                        "comment": null,
                        "isDynamicPartition": false,
                        "isSelect": true,
                        "isSourceTableField": false,
                        "name": "字段四",
                        "prepType": "string",
                        "status": 0,
                        "type": "Nullable(String)"
                    },
                    {
                        "alias": "`字段一`",
                        "comment": null,
                        "isDynamicPartition": false,
                        "isSelect": true,
                        "isSourceTableField": false,
                        "name": "字段一",
                        "prepType": "string",
                        "status": 0,
                        "type": "Nullable(String)"
                    },
                    {
                        "alias": "`字段三`",
                        "comment": null,
                        "isDynamicPartition": false,
                        "isSelect": true,
                        "isSourceTableField": false,
                        "name": "字段三",
                        "prepType": "string",
                        "status": 0,
                        "type": "Nullable(String)"
                    },
                    {
                        "alias": "`字段二`",
                        "comment": null,
                        "isDynamicPartition": false,
                        "isSelect": true,
                        "isSourceTableField": false,
                        "name": "字段二",
                        "prepType": "string",
                        "status": 0,
                        "type": "Nullable(String)"
                    }
                ],
                "fileId": "13516",
                "fullOption": false,
                "hiveOwner": "userEmailPrefix",
                "lastDdlTime": "2022-12-13 12:49:00",
                "metadataLink": "https://data.bytedanc*.net/coral/datamap/detail/table_info/clickhouse/aeolus_excel_upload_aeolus_toy/table_4f0cc551_9dfa_****_****_**********#group=default",
                "nodeId": "77b3df39-834c-4da4-908e-4b54846bc599",
                "nodeType": "table",
                "params": {
                    "extractType": "{\"key\":\"full\"}"
                },
                "partitionConfList": [],
                "query": "",
                "schemaName": "Sheet1",
                "tableAlias": "table_4f0cc551_9dfa_4915_****_************",
                "tableRowFilter": {},
                "tbId": "cn//aeolus_excel_upload_aeolus_toy//table_4f0cc551_9dfa_4915_****_************",
                "tbName": "table_4f0cc551_9dfa_4915_****_************"
            }
        ],
        "parseEngine": 0,
        "syncConf": {
            "backtrackingConf": {
                "dateRange": {
                    "endDate": "2022-12-13",
                    "startDate": "2022-12-13"
                },
                "enable": 1
            },
            "doradoPriority": "normal",
            "frequency": "daily",
            "monitorConf": {
                "alarmRules": [
                    {
                        "failedAlarmItems": [
                            {
                                "item": "retry_failed"
                            }
                        ],
                        "id": 6826,
                        "name": "auto_aeolus_rule_{{dataSetId}}_167099*******_dev",
                        "normalNoticeConf": [
                            {
                                "dutySchedules": [],
                                "noticeChannel": "lark",
                                "users": [
                                    "userEmailPrefix"
                                ]
                            }
                        ],
                        "resultAlarmItems": [],
                        "timeoutAlarmItems": []
                    }
                ]
            },
            "paramsConfList": [
                {
                    "name": "tqs.query.auto.retry.enable",
                    "value": "true"
                }
            ],
            "performanceSettings": {
                "chQueryParams": {},
                "clusterName": "cnch_alpha_lq",
                "cnchVwDefault": "vw_default",
                "cnchVwWrite": "vw_write",
                "dataSourceId": 14*,
                "driverName": "click_house",
                "partitionKey": [
                    "p_date"
                ],
                "primaryKeyList": [],
                "sampleKey": null,
                "sampleRate": 1.0,
                "shardKey": null
            },
            "retryInterval": 5,
            "retryNum": 1,
            "scheduleDay": "0",
            "scheduleTime": "00:00",
            "scheduleTimeType": 0,
            "slaDaytime": null,
            "slaStatus": 0,
            "syncType": 1,
            "ttl": 7,
            "upstreamSettings": {
                "dynamicPartitionConfList": [],
                "dynamicPartitionMode": false,
                "partitionConfList": [],
                "uniqueIndexList": []
            },
            "writePartition": 0,
            "yarnName": "root.default_hrtech_da_pm"
        },
        "whereConf": {
            "nodeRowFilter": {},
            "requiredRowFilter": []
        }
    },
    "msg": "成功"
}

2.3 查看数据集基础信息

权限需求
资源
权限
数据集
read
接口描述与说明：获取数据集基础信息，可用于三方接入时粗略展示数据集的内容。

资源	权限
数据集	read

请求说明

请求地址：{{domain}}/aeolus/api/v4/open/dataset/{{dataSetId}}/digest

请求示例

curl --location --request GET '{{domain}}/aeolus/api/v4/open/dataset/{{dataSetId}}/digest' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{jwtToken}}'

请求参数

名称	类型	必选	示例值	描述
dataSetId	integer	是	123	数据集ID
folderPath	integer	否	[0,1]	是否需要完整的文件夹路径
confidentiality	integer	否	[0,1]	是否需要获取数据集的机密等级，部分环境不存在此概念，可以传0加快接口速度

返回参数

名称	类型	描述
id	integer	数据集ID
appID	integer	项目ID
appName	string	项目名称
detailUrl	string	数据集前端页面地址，可直接跳转
folderName	list	数据集文件夹路径 -> 根目录为默认值，代表该数据集没有存放在文件夹下如入参folderPath=0，则下面json示例中folderName只为 "folderName": [ "子文件夹-层级3" ]
name	string	数据集名称
ownerEmailPrefix	string	数据集拥有者
status	integer	数据集状态 -> 通常情况下status=0
type	integer	数据集类型[常见的几种:0: ClickHouse表作为数据源生成的数据集、2: Hive表作为数据源生成的数据集、8: 自定义SQL生成的数据集、10: MySQL表作为数据源生成的数据集、22: Prep类型的数据集]

{
    "code": "aeolus/ok",
    "data": {
        "appId": 7777947,
        "appName": "测试项目-名称",
        "confidentiality": "L3",
        "demoUrl": "http://xxx.com",
        "descr": "这是一段描述，描述数据集的作用",
        "detailUrl": "https://aeolus-release.fedev.bytedanc*.net/aeolus#/dataManage/detail/{{dataSetId}}?appId=77*****",
        "folderName": [
            "子文件夹-层级3",
            "子文件夹-层级2",
            "子文件夹-层级1",
            "模板数据集",
            "根目录"
        ],
        "id": {{dataSetId}},
        "name": "测试open-api专用数据集1",
        "ownerEmailPrefix": "userEmailPrefix",
        "status": 0,
        "type": 22
    },
    "msg": "成功"
}

2.4 更新数据集基础信息

权限需求
资源
权限
数据集
write
接口描述与说明：对应前端数据集基础描述信息的更新。

资源	权限
数据集	write

注意：此接口允许更新的信息内容与接口查看数据集基础信息有差异。

请求说明

请求地址：{{domain}}/aeolus/api/v4/open/dataset/{{dataSetId}}/digest
注意：这里是全量覆盖更新，即如果需要更新某个属性，则还需要将其他各个属性的原始内容全量传入，不然则视为使用空白值覆盖原有属性。

请求示例

curl --location --request PUT '{{domain}}/aeolus/api/v4/open/dataset/{{dataSetId}}/digest' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{jwtToken}}' \
--data-raw '{
    "dataSetName": "测试open-api专用数据集1",
    "dataSetDescr": "这是一段描述，描述数据集的作用",
    "confidentiality": "L3",
    "groupId": 193
}'

请求参数

参数	类型	描述
dataSetId	integer	数据集ID
dataSetName	integer	数据集名称
dataSetDescr	string	数据集描述

返回示例

{
    "code": "aeolus/ok",
    "data": {
        "affectedRows": 1
    },
    "msg": "成功"
}

2.5 设置数据集的标签

权限需求
资源
权限
数据集
write
接口描述与说明：设置数据集的标签信息，数据集标签本身附属于项目，需与「数据集标签-获取项目下数据集标签信息」接口配合使用

资源	权限
数据集	write

请求说明

请求地址：{{domain}}/aeolus/api/v4/open/dataset/{{dataSetId}}/dataSetTag

请求示例

curl --location --request POST '{{domain}}/aeolus/api/v4/open/dataset/{{dataSetId}}/dataSetTag' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{jwtToken}}' \
--data-raw '{
    "tagIdList": [
        153
    ]
}'

请求参数

名称	类型	必选	示例值	描述
dataSetId	integer	是	123	数据集ID
tagIdList	list < integer >	是	153	标签ID，一次可给数据集设置多个标签；前端表现为可勾选多个

返回示例

{
    "code": "aeolus/ok",
    "data": {},
    "msg": "成功"
}

2.6 获取项目下数据集文件夹列表

版本：V2.76.0 版本及以上

权限需求

资源	权限
项目	read

请求说明

获取项目下文件夹list

接口路径
{{domain}}/aeolus/api/v4/open/app/{{appId}}/dataSetFolderTreeV2

请求示例

cURL示例

curl --location --request GET '{{domain}}/aeolus/api/v4/open/app/{{appId}}/dataSetFolderTreeV2' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{jwtToken}}'

请求参数

名称	类型	含义说明	参数含义
official	list	官方目录	ctime：创建时间，mtime：最后修改时间，deleteTime：删除时间，status：状态[0是正常状态；2是回收站中，1是彻底删除]
private	list	个人目录	ctime：创建时间，mtime：最后修改时间，deleteTime：删除时间，status：状态[0是正常状态；2是回收站中，1是彻底删除]
public	list	公共目录	ctime：创建时间，mtime：最后修改时间，deleteTime：删除时间，status：状态[0是正常状态；2是回收站中，1是彻底删除]

返回示例

{
    "code": "aeolus/ok",
    "data": {
        "official": [
            {
              "appId": 7778517,  #项目id
              "belong": 1,     #归属 1是公共，2是个人
              "ctime": "2024-05-30 11:57",
              "deleteTime": null,
              "descr": null,
              "id": 12107,
              "mtime": "2024-05-30 11:57",
              "name": "测试",
              "ownerEmailPrefix": "guowenhao.591688",
              "parentId": 12101,  #父目录id
              "status": 0,   
              "childList": [],   #子目录list
            }
        ],
        "private": [],
        "public": [],
    }
    "msg": "成功"
}