项目内数据集 API--智能数据洞察-火山引擎

文档中心

导航

项目内数据集 API

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

1. 概述

本文为您介绍的是“项目内数据集类的 Open API”，主要包含项目数据集标签与文件夹 API、项目数据集 API、项目集群配置 API。您将了解到用户可以通过 API 进行获取、创建、更新项目下相关数据集信息和文件夹信息，获取、新增、删除私有集群写入用户列表等操作。
注意：在您使用本文所述的 API 前，还需完成接入 JWT-Token 和申请 Token 的前置操作，请先了解调用方式，详情可阅读调用方式。

2. 数据集标签

2.1 获取项目下数据集标签信息

权限需求
资源
权限
项目
read
接口描述与说明：获取项目下已创建的数据集标签信息。

资源	权限
项目	read

请求说明

请求地址：{{domain}}/aeolus/api/v4/open/app/{{appId}}/dataSetTag

请求示例

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

请求参数

参数	类型	必选	描述	示例值
appId	integer	是	项目 ID	123

返回参数

参数	类型	描述
appId	integer	项目 ID
colour	string	数据集标签颜色
ctime	string	数据集标签创建时间
dataSetInfos	object	数据集标签的数据集应用情况
dataSetInfos.id	integer	数据集 ID
dataSetInfos.name	string	数据集名称
id	integer	数据集标签 Id
mtime	string	数据集标签修改时间
name	string	数据集标签名称
reportEnable	integer	图表标题是否继承此标签
status	integer	数据集标签状态

返回示例

{
    "code": "aeolus/ok",
    "data": [
        {
            "appId": 7******,
            "colour": "purple",
            "ctime": "2022-12-13 16:48",
            "dataSetInfos": [
                {
                    "id": 19****,
                    "name": "v4专用测试数据集"
                },
                {
                    "id": {{dataSetId}},
                    "name": "测试open-api专用数据集1"
                }
            ],
            "id": 153,
            "mtime": "2022-12-13 16:48",
            "name": "test用",
            "reportEnable": 0,
            "status": 0
        }
    ],
    "msg": "成功"
}

2.2 创建项目下数据集标签

权限需求
资源
权限
项目
admin
接口描述与说明：创建项目下的数据集标签。

资源	权限
项目	admin

请求说明

请求地址：{{domain}}/aeolus/api/v4/open/app/{{appId}}/dataSetTag

请求示例

curl --location --request POST '{{domain}}/aeolus/api/v4/open/app/{{appId}}/dataSetTag' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{jwtToken}}' \
--data-raw '{
    "name": "test用",
    "colour": "purple",
    "reportEnable": 0
}'

请求参数

参数	类型	必选	示例值	描述
appId	integer	是	123	项目 ID
name	string	是	test用	数据集标签名称
colour	string	是	blue green lightGreen lightYellow orange purple red yellow	数据集标签颜色
reportEnable	integer	否		图表是否继承此数据集标签

返回参数

出参说明：$.data.id为新建的数据集标签 ID

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

2.3 更新项目下数据集标签信息

权限需求
资源
权限

请求说明

请求地址：{{domain}}/aeolus/api/v4/open/app/{{appId}}/dataSetTag/{{tagId}}

请求示例

curl --location --request PUT '{{domain}}/aeolus/api/v4/open/app/{{appId}}/dataSetTag/{{tagId}}' \
--header 'Content-Type: application/json' \
--header 'app-id: 77*****' \
--header 'Authorization: Bearer {{jwtToken}}' \
--data-raw '{
    "colour": "purple",
    "name": "12",
    "reportEnable": 0
}'

请求参数

参数	类型	必选	示例值	描述
appId	integer	是	123	项目 ID
tagId	integer	是	123	数据集标签 ID
name	string	是	test用	数据集标签名称
colour	string	是	blue green lightGreen lightYellow orange purple red yellow	数据集标签颜色
reportEnable	integer	否	0	图表是否继承此数据集标签

返回示例

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

2.4 删除项目下数据集标签

权限需求
资源
权限
项目
admin
接口描述与说明：删除项目下数据集标签信息。

资源	权限
项目	admin

请求说明

请求地址：{{domain}}/aeolus/api/v4/open/app/{{appId}}/dataSetTag/{{tagId}}

请求示例

curl --location --request DELETE '{{domain}}/aeolus/api/v4/open/app/{{appId}}/dataSetTag/{{tagId}}' \
--header 'Content-Type: application/json' \
--header 'app-id: 7777947' \
--header 'Authorization: Bearer {{jwtToken}}'

请求参数

名称	类型	必选	示例值	描述
appId	integer	是	123	项目 ID
tagId	integer	是	123	数据集标签 ID

返回参数

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

3. 数据集文件夹

3.1 获取项目下数据集文件夹信息

权限需求
资源
权限
项目
read
接口描述与说明：删除项目下数据集标签信息。

资源	权限
项目	read

请求说明

请求地址：{{domain}}/aeolus/api/v4/open/app/{{appId}}/dataSetFolder

请求示例

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

请求参数

参数	类型	必选	示例值	描述
appId	integer	是	123	项目 ID

返回参数

参数	类型	描述
appId	integer	项目 ID
ctime	string	数据集文件夹创建时间
deleteTime	string	数据集文件夹删除时间
descr	string	数据集文件夹描述
id	integer	数据集文件夹 ID
mtime	string	数据集文件夹修改时间
name	string	数据集文件夹名称
ownerEmailPrefix	string	数据集文件夹拥有者
parentId	integer	数据集文件夹父文件夹，为 0 则代表没有父文件夹，已在根目录
status	integer	数据集文件夹状态
childList	list	数据集文件夹子文件夹列表

返回示例

{
    "code": "aeolus/ok",
    "data": [
        {
            "appId": *******,
            "ctime": "2022-04-02 11:52",
            "deleteTime": null,
            "descr": "",
            "id": 2320,
            "mtime": "2022-04-02 11:52",
            "name": "test1",
            "ownerEmailPrefix": "userEmailPrefix",
            "parentId": 0,
            "status": 0
        },
        {
            "appId": *******,
            "childList": [
                {
                    "appId": *******,
                    "childList": [
                        {
                            "appId": *******,
                            "childList": [
                                {
                                    "appId":*******,
                                    "ctime": "2022-12-14 12:14",
                                    "deleteTime": null,
                                    "descr": "",
                                    "id": 3075,
                                    "mtime": "2022-12-14 12:14",
                                    "name": "子文件夹-层级3",
                                    "ownerEmailPrefix": "userEmailPrefix",
                                    "parentId": 2706,
                                    "status": 0
                                }
                            ],
                            "ctime": "2022-09-29 16:30",
                            "deleteTime": null,
                            "descr": "",
                            "id": 2706,
                            "mtime": "2022-12-14 12:13",
                            "name": "子文件夹-层级2",
                            "ownerEmailPrefix": "userEmailPrefix",
                            "parentId": 2704,
                            "status": 0
                        }
                    ],
                    "ctime": "2022-09-29 16:29",
                    "deleteTime": null,
                    "descr": "111",
                    "id": 2704,
                    "mtime": "2022-12-14 12:13",
                    "name": "子文件夹-层级1",
                    "ownerEmailPrefix": "userEmailPrefix",
                    "parentId": 2321,
                    "status": 0
                }
            ],
            "ctime": "2022-04-02 11:53",
            "deleteTime": null,
            "descr": "",
            "id": 2321,
            "mtime": "2022-05-04 11:24",
            "name": "模板数据集",
            "ownerEmailPrefix": "userEmailPrefix",
            "parentId": 0,
            "status": 0
        },
        {
            "appId": *******,
            "ctime": "2022-12-14 12:14",
            "deleteTime": null,
            "descr": "",
            "id": 3076,
            "mtime": "2022-12-14 12:14",
            "name": "测试文件夹1",
            "ownerEmailPrefix": "userEmailPrefix",
            "parentId": 0,
            "status": 0
        }
    ],
    "msg": "成功"
}

3.2 创建项目下数据集文件夹

权限需求
资源
权限
父文件夹
write
项目(parentId=0 时）
write
如是在根目录创建文件夹则等同于需要项目的 write 权限。
接口描述与说明：在根目录或某个文件夹下创建文件夹。

资源	权限
父文件夹	write
项目(parentId=0 时）	write

请求说明

请求地址：{{domain}}/aeolus/api/v4/open/app/{{appId}}/dataSetFolder

请求示例

curl --location --request POST '{{domain}}/aeolus/api/v4/open/app/{{appId}}/dataSetFolder' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{jwtToken}}' \
--data-raw '{
    "name": "子文件夹1111",
    "descr": "666",
    "confidentiality": "L3",
    "isPersonalDataRelated": true,
    "dataRegion": [
        "CN"，
        "US"
    ],
    "parentId": 0
}'

请求参数

参数	类型	必选	示例值	描述
appId	integer	是	123	项目 ID
name	string	是	子文件夹1	文件夹名称
descr	string	否	666	文件夹描述；不填则为空
parentId	integer	是	0	父文件夹 ID，parentId 为 0 则视为在根目录创建一个文件夹
confidentiality	string	否	L3	数据集文件夹机密等级（非 TOB 环境）

返回示例

出参说明folderId为新文件夹的 ID。

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

3.3 更新项目下数据集文件夹信息

权限需求
资源
权限
数据集文件夹
write
接口描述与说明

资源	权限
数据集文件夹	write

请求说明

请求地址：{{domain}}/aeolus/api/v4/open/app/{{appId}}/dataSetFolder/{{dataSetFolderId}}

请求示例

curl --location --request PUT '{{domain}}/aeolus/api/v4/open/app/{{appId}}/dataSetFolder/{{dataSetFolderId}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{jwtToken}}' \
--data-raw '{
    "name": "测试文件夹1",
    "descr": "111",
    "isPersonalDataRelated": true,
    "dataRegion": [
        "CN"，
        "US"
    ],
    "confidentiality": "L2"
}'

请求参数

参数	类型	必选	示例值	描述
appId	integer	是	123	项目 ID
dataSetFolderId	integer	是	3079	数据集文件夹 ID
name	string	是	测试文件夹1	数据集文件夹名称
descr	string	否	111	数据集文件夹描述

返回示例

出参说明返回folderId代表该文件夹信息更新成功。

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

4. 数据集

4.1 获取项目下数据集信息列表

权限需求
资源
权限
数据集文件夹
read
接口描述与说明：获取项目下当前所有数据集的信息列表。

资源	权限
数据集文件夹	read

请求说明

请求地址：{{domain}}/aeolus/api/v4/open/app/{{appId}}/dataSetList

请求示例

curl --location --request GET '{{domain}}/aeolus/api/v4/open/app/{{appId}}/dataSetList?needSyncInfo=0&needUpstreamInfo=0&dataSetIdList=186583,186600' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{jwtToken}}'

请求参数

参数	类型	必选	示例值	描述
appId	integer	是	123	项目 ID
needSyncInfo	integer	否	0,1	数据集信息中是否要包含上数据集同步信息为 0 则可以加快接口速度
needUpstreamInfo	integer	否	0,1	数据集信息中是否要包含上游数据源信息为 0 则可以加快接口速度
dataSetIdList	list	否	186583,186600	数据集 ID 列表，不传则默认为查全项目，否则只返回该参数指定的数据集信息；多个数据集 ID 以逗号分割

返回参数

参数	类型	描述
ctime	integer	数据集创建日期
elapsedTimeForLastSuccessTaskTime	integer	最近同步成功的同步任务持续时间
frequency	string	数据集同步任务频率
id	integer	数据集 ID
lastSuccessTaskTime	string	最近同步成功的业务日期
lastSyncTime	string	最近同步时间
mtime	string	数据集最近修改时间
name	string	数据集名称
owner	string	数据集拥有者
rowsForLastSuccessTaskTime	integer	最近同步成功的同步任务数据行数
scheduleDay	string	数据集自动同步天级定时当 frequency 为小时级或分钟级时 scheduleDay 则为小时级，即第几个小时开始同步
scheduleTime	string	数据集自动同步小时级定时当 frequency 为小时级或分钟级时 scheduleTime 则为分钟级，即第几分钟开始同步
status	integer	数据集状态
syncType	integer	数据集同步类型
ttl	integer	数据集数据生命周期
type.name	string	数据集类型名称
upstreamInfo.dbName	string	数据集使用的上游数据源 DBName
upstreamInfo.tableName	string	数据集使用的上游数据源 tableName
url	string	数据集详情页 URL

{
    "code": "aeolus/ok",
    "data": [
        {
            "ctime": "2022-12-14 12:17:54",
            "elapsedTimeForLastSuccessTaskTime": 501,
            "frequency": "daily",
            "hivePartitionSpecified": false,
            "hiveTableUsed": false,
            "hsqlList": [],
            "hsqlUsed": false,
            "id": {{dataSetId}},
            "lastSuccessTaskTime": "2022-12-14 00:00:00",
            "lastSyncTime": "2022-12-15 18:19:19",
            "mtime": "2022-12-15 19:37:31",
            "name": "测试open-api专用数据集1",
            "owner": "userEmailPrefix",
            "rowsForLastSuccessTaskTime": 56,
            "scheduleDay": "0",
            "scheduleTime": "00:00",
            "status": 0,
            "syncType": 2,
            "ttl": 8,
            "type": {
                "code": 22,
                "name": "prep 数据集"
            },
            "upstreamInfo": [
                {
                    "dbName": "aeolus_excel_upload_aeolus_toy",
                    "tableName": "table_4f0cc551_9dfa_4915_a38f_737c716591a8"
                }
            ],
            "url": "https://aeolus-release.fedev.bytedanc*.net/aeolus#/dataManage/detail/{{dataSetId}}?appId=7777947"
        }
    ],
    "msg": "成功"
}

4.2 获取项目下数据集简略信息列表

最小支持版本 2.58.1。
权限需求
资源
权限
数据集
read
接口描述与说明获取项目下当前所有数据集的信息列表。

资源	权限
数据集	read

请求说明

请求地址：{{domain}}/aeolus/api/v4/open/app/{{appId}}/dataSetSimpleList

请求示例

curl --location --request GET '{{domain}}/aeolus/api/v4/open/app/{{appId}}/dataSetSimpleList?page=1&perPage=2&kw=测试' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{jwtToken}}'

请求参数

参数	类型	必选	示例值	描述
appId	integer	是	123	项目 ID
kw	string	否	测试	数据集名称，模糊匹配
page	integer	否	1	分页-页数需要与 perPage 一起使用
perPage	integer	否	2	分页-每页数量需要与 page 一起使用

返回参数

参数	类型	描述
appId	integer	项目名称
belong	integer	公共数据集 or 个人数据集
ctime	string	数据集创建时间
mtime	string	数据集最近修改时间
name	string	数据集名称
ownerEmailPrefix	string	数据集所有人
status	integer	数据集状态
type	integer	数据集类型
totalSize	integer	有权限看到的数据集总个数（配合分页使用）

返回示例

{
    "code": "aeolus/ok",
    "data": {
        "dataSetList": [
            {
                "appId": 1,
                "belong": 1,
                "ctime": "2023-10-16 19:51",
                "id": 1,
                "mtime": "2023-10-16 19:51",
                "name": "data_set_name",
                "ownerEmailPrefix": "user",
                "status": 0,
                "type": 22
            }
        ],
        "totalSize": 1
    },
    "msg": "成功"
}

4.3 获取项目下上游为某数据源的数据集信息

首次支持版本 2.51。
权限需求
资源
权限
项目
read
接口描述与说明通过指定dataSourceType(数据源类型）, dbName(数据源的库名，对部分数据源无意义）, tableName(数据源的表名称），进而查询所有使用此数据源为上游的数据集的基础信息。
注：当前查询范围未包括自定义 sql 类型的数据集。

资源	权限
项目	read

请求说明

请求地址：{{domain}}/aeolus/api/v4/open/app/{{appId}}/dataSourceLineage

请求示例

curl --location --request POST '{{domain}}/aeolus/api/v4/open/app/{{appId}}/dataSourceLineage' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{jwtToken}}'
--data '{
    "dataSourceType": "click_house",
    "dbName": "aeolus_excel_upload_aeolus_toy",
    "tableName": "table_35b15b69_2ea5_****_****_*********",
    "authOnly": false
}'

请求参数

参数	类型	必选	示例值	描述
appId	integer	是	123	项目 ID
dataSourceType	string	是	hive click_house	数据源类型
dbName	string	否	aeolus_excel_upload_aeolus_toy	数据源-库名称
tableName	string	否	table_35b15b69_2ea5___*********	数据源-表名称
authOnly	boolean	否	false	是否仅返回当前 token 对应用户［有仅阅览及以上权限］的数据集的信息，默认值为false

返回参数

出参说明dataSetList下的出参字段具体说明可见。
［接口-查看数据集基础信息］

参数	类型	描述
dataSetList	list	结果内容
dataSourceType	string	查询所用的 dataSourceType
dbName	string	查询所用的 dbName
tableName	string	查询所用的 tableName
listSize	integer	查询到的数据集信息的数量

返回示例

{
    "code": "aeolus/ok",
    "data": {
        "dataSetList": [
            {
                "appId": "*******",
                "appName": "hsm",
                "demoUrl": "",
                "descr": null,
                "detailUrl": "https://aeolus-integration.bytedanc*.net/aeolus#/dataManage/detail/193016?appId=7778352",
                "folderName": [
                    "根目录"
                ],
                "id": ******,
                "name": "good_hive_data_set",
                "ownerEmailPrefix": "husimin.xcl",
                "status": 0,
                "type": 2
            },
            {
                "appId": "*******",
                "appName": "hsm",
                "demoUrl": "",
                "descr": null,
                "detailUrl": "https://aeolus-integration.bytedanc*.net/aeolus#/dataManage/detail/196003?appId=7778352",
                "folderName": [
                    "原始内容保留",
                    "根目录"
                ],
                "id": 196003,
                "name": "测试tableSchema权限",
                "ownerEmailPrefix": "husimin.xcl",
                "status": 0,
                "type": 2
            }
        ],
        "dataSourceType": "hive",
        "dbName": null,
        "listSize": 2,
        "tableName": "hsm_own_metrics"
    },
    "msg": "成功"
}

5. 集群配置

5.1 获取私有集群写入用户列表

权限需求：用户为私有集群的所有者、负责人，且为项目管理员。
接口描述与说明：获取项目下某集群准入用户列表。

请求说明

请求地址：{{domain}}/aeolus/api/v4/open/app/{{appId}}/clusterWriteUserList

请求示例

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

请求参数

参数	类型	必选	示例值	描述
appId	integer	是	123	项目 ID
clusterId	integer	是	1	集群 id

返回参数

参数	类型	描述
userList	array	准入用户 list

返回示例

{
    "code": "aeolus/ok",
    "data": [
        "luowenlei",
        "chenweichen.six"
    ],
    "msg": "成功"
}

5.2 新增私有集群写入用户列表

权限需求：用户为私有集群的所有者、负责人，且为项目管理员。
接口描述与说明：在项目下某集群准入用户列表新增某些用户。
备注：如果原本该集群的权限已经是全项目可用了，这个操作的结果不会改表全项目可用的现状，添加的用户权限是冗余存在的，在全集群权限去除后起效。批量写入时如遇到报错可以重试写入，接口成功结果幂等。

请求说明

请求地址：{{domain}}/aeolus/api/v4/open/app/{{appId}}/clusterWriteUserList

请求示例

curl --location --request POST '{{domain}}/aeolus/api/v4/open/app/{{appId}}/clusterWriteUserList' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{jwtToken}}'\
--data-raw '{
    "userList": ["******.****"],
    "clusterId": 1
}'

请求参数

参数	类型	必选	示例值	描述
appId	integer	是	123	项目 ID
userList	list	是	["**."]	新增的用户名（幂等，已存在的不会重复添加）
clusterId	integer	是	1	集群 id

返回示例

$.data.id为集群 id。

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

5.3 删除私有集群写入用户列表

权限需求：用户为私有集群的所有者、负责人，且为项目管理员。
接口描述与说明：从项目下某集群准入用户列表删除部分用户。
备注：批量删除时如遇到报错可以重试写入，接口成功结果幂等无。

请求说明

请求地址：{{domain}}/aeolus/api/v4/open/app/{{appId}}/clusterWriteUserList

请求示例

curl --location --request DELETE '{{domain}}/aeolus/api/v4/open/app/{{appId}}/clusterWriteUserList' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{jwtToken}}'\
--data-raw '{
    "userList": ["*******.****"],
    "clusterId": 1
}'

请求参数

参数	类型	必选	示例值	描述
appId	integer	是	123	项目 ID
userList	list	是	["**."]	删除的用户名（幂等，若传入的用户本来就不具有权限，接口不报错）
clusterId	integer	是	1	集群 id

返回示例

$.data.id为集群 id。

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