文档中心

项目内数据集 API

最近更新时间：2024.03.15 15:27:03

首次发布时间：2024.03.15 14:51:44

1. 概述

数据集 Open API 包含了：数据集操作 API、数据集信息 API、数据集维度指标与血缘关系 API、数据集同步任务 API、数据集可视化查询参数与开放查询 API、数据集模型画布与运维类工具 API、项目内数据集 API。
本文为您介绍的是“项目内数据集类的 Open API”，主要包含项目数据集标签与文件夹 API、项目数据集 API、项目集群配置 API。您将了解到用户可以通过 API 进行获取、创建、更新项目下相关数据集信息和文件夹信息，获取、新增、删除私有集群写入用户列表等操作。
注意：在您使用本文所述的 API 前，还需完成接入 JWT-Token 和申请 Token 的前置操作，详情可阅读数据集 Open API 概述。

2. 接口说明

新接口 V4 版本采用标准的 restful 接口命名方式，即资源+行为的命名方式。
针对每个接口提供直接可以导入 postMan 的 cURL 示例，方便客户体验，由于各环境 DataWind 域名和各个请求中都含有通用含义的变量，因此各接口的 cURL 实例中均采用{{}}包裹变量，{{变量}}格式可直接被 postMan 识别。
变量对照含义表：
jwtToken -> {{jwtToken}}
aeolus 域名 -> {{domain}} 
项目 ID -> {{appId}} 
数据集 ID -> {{dataSetId}} 
数据集标签 Id {{tagId}}
数据集文件夹 Id {{dataSetFolderId}}
本功能适用的版本: 2.48.0及以上

3. 数据集标签

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

权限需求
资源权限
项目 read
接口描述与说明获取项目下已创建的数据集标签信息
接口路径{{domain}}/aeolus/api/v4/open/app/{{appId}}/dataSetTag

资源	权限
项目	read

cURL示例

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

入参说明
名称类型必选含义说明
appId integer 是项目ID

名称	类型	必选	含义说明
appId	integer	是	项目ID

出参说明

名称	类型	含义说明
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": 7777947,
            "colour": "purple",
            "ctime": "2022-12-13 16:48",
            "dataSetInfos": [
                {
                    "id": 192151,
                    "name": "v4专用测试数据集"
                },
                {
                    "id": {{dataSetId}},
                    "name": "测试open-api专用数据集1"
                }
            ],
            "id": 153,
            "mtime": "2022-12-13 16:48",
            "name": "test用",
            "reportEnable": 0,
            "status": 0
        }
    ],
    "msg": "成功"
}

备注
无

3.2 创建项目下数据集标签

权限需求
资源权限
项目 admin
接口描述与说明创建项目下的数据集标签
接口路径{{domain}}/aeolus/api/v4/open/app/{{appId}}/dataSetTag

资源	权限
项目	admin

cURL示例

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	是		项目ID
name	string			数据集标签名称
colour	string		blue green lightGreen lightYellow orange purple red yellow	数据集标签颜色
reportEnable	integer			图表是否继承此数据集标签

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

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

备注
无

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

权限需求
资源权限
接口路径{{domain}}/aeolus/api/v4/open/app/{{appId}}/dataSetTag/{{tagId}}

cURL示例

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

入参说明

名称	类型	必选	枚举值	含义说明
appId	integer	是		项目ID
tagId	integer	是		数据集标签ID
name	string			数据集标签名称
colour	string		blue green lightGreen lightYellow orange purple red yellow	数据集标签颜色
reportEnable	integer			图表是否继承此数据集标签

出参说明

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

备注
无

3.4 删除项目下数据集标签

权限需求
资源权限
项目 admin
接口描述与说明删除项目下数据集标签信息
接口路径{{domain}}/aeolus/api/v4/open/app/{{appId}}/dataSetTag/{{tagId}}

资源	权限
项目	admin

cURL示例

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 是项目ID
tagId integer 是数据集标签ID

出参说明

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

备注
无

4. 数据集文件夹

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

权限需求
资源权限
项目 read
接口描述与说明删除项目下数据集标签信息
接口路径{{domain}}/aeolus/api/v4/open/app/{{appId}}/dataSetFolder

资源	权限
项目	read

cURL示例

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

入参说明
名称类型必选枚举值含义说明
appId integer 是项目ID

出参说明

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

{
    "code": "aeolus/ok",
    "data": [
        {
            "appId": 7777947,
            "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": 7777947,
            "childList": [
                {
                    "appId": 7777947,
                    "childList": [
                        {
                            "appId": 7777947,
                            "childList": [
                                {
                                    "appId": 7777947,
                                    "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": 7777947,
            "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": "成功"
}

备注
无

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

权限需求
资源权限
父文件夹 write
项目(parentId=0时) write
如是在根目录创建文件夹则等同于需要项目的write权限
接口描述与说明在根目录或某个文件夹下创建文件夹
接口路径{{domain}}/aeolus/api/v4/open/app/{{appId}}/dataSetFolder

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

cURL示例

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	是	项目ID
name	string	是	文件夹名称
descr	string	否	文件夹描述；不填则为空
parentId	integer	是	父文件夹ID，parentId为0则视为在根目录创建一个文件夹
confidentiality	string	否	数据集文件夹机密等级(非TOB环境)

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

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

备注
无

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

权限需求
资源权限
数据集文件夹 write
接口描述与说明
接口路径{{domain}}/aeolus/api/v4/open/app/{{appId}}/dataSetFolder/{{dataSetFolderId}}

资源	权限
数据集文件夹	write

cURL示例

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	是	项目ID
dataSetFolderId	integer	是	数据集文件夹ID
name	string	是	数据集文件夹名称
descr	string	否	数据集文件夹描述
confidentiality	integer	否	数据集文件夹机密等级(非ToB环境)

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

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

备注
无

5. 数据集

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

权限需求
资源权限
数据集文件夹 read
接口描述与说明获取项目下当前所有数据集的信息列表
接口路径{{domain}}/aeolus/api/v4/open/app/{{appId}}/dataSetList

资源	权限
数据集文件夹	read

cURL示例

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	是		项目ID
needSyncInfo	integer	否	0,1	数据集信息中是否要包含上数据集同步信息为0则可以加快接口速度
needUpstreamInfo	integer	否	0,1	数据集信息中是否要包含上游数据源信息为0则可以加快接口速度
dataSetIdList	list	否		数据集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": "成功"
}

备注
无

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

最小支持版本 2.58.1
权限需求
资源权限
数据集 read
接口描述与说明获取项目下当前所有数据集的信息列表
接口路径{{domain}}/aeolus/api/v4/open/app/{{appId}}/dataSetSimpleList

资源	权限
数据集	read

cURL示例

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	是	项目ID
kw	string	否	数据集名称，模糊匹配
page	integer	否	分页-页数需要与perPage一起使用
perPage	integer	否	分页-每页数量需要与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": "成功"
}

备注
无

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

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

注: 当前查询范围未包括自定义sql类型的数据集
接口路径{{domain}}/aeolus/api/v4/open/app/{{appId}}/dataSourceLineage

资源	权限
项目	read

cURL示例

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_42b6_b22b_a2e3d066eb93",
    "authOnly": false
}'

入参说明

名称	类型	必选	默认值	枚举值	含义说明
appId	integer	是		无	项目ID
dataSourceType	string	是	空	hive click_house	数据源类型
dbName	string	否	空		数据源-库名称
tableName	string	否	空		数据源-表名称
authOnly	boolean	否	false		是否仅返回当前token对应用户[有仅阅览及以上权限]的数据集的信息

出参说明dataSetList下的出参字段具体说明可见

接口-查看数据集基础信息\
名称	类型	含义说明
dataSetList	list	结果内容
dataSourceType	string	查询所用的dataSourceType
dbName	string	查询所用的dbName
tableName	string	查询所用的tableName
listSize	integer	查询到的数据集信息的数量

{
    "code": "aeolus/ok",
    "data": {
        "dataSetList": [
            {
                "appId": "7778352",
                "appName": "hsm",
                "demoUrl": "",
                "descr": null,
                "detailUrl": "https://aeolus-integration.bytedanc*.net/aeolus#/dataManage/detail/193016?appId=7778352",
                "folderName": [
                    "根目录"
                ],
                "id": 193016,
                "name": "good_hive_data_set",
                "ownerEmailPrefix": "husimin.xcl",
                "status": 0,
                "type": 2
            },
            {
                "appId": "7778352",
                "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": "成功"
}

备注
无

6. 集群配置

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

权限需求

用户为私有集群的所有者、负责人, 且为项目管理员

接口描述与说明获取项目下某集群准入用户列表
接口路径{{domain}}/aeolus/api/v4/open/app/{{appId}}/clusterWriteUserList

cURL示例

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 是项目ID
clusterId integer 是集群id

出参说明

名称	类型	含义说明
userList	array	准入用户list

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

备注
无

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

权限需求

用户为私有集群的所有者、负责人, 且为项目管理员

接口描述与说明在项目下某集群准入用户列表新增某些用户
接口路径{{domain}}/aeolus/api/v4/open/app/{{appId}}/clusterWriteUserList

cURL示例

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

入参说明
名称类型必选枚举值含义说明
appId integer 是项目ID
userList list 是新增的用户名（幂等，已存在的不会重复添加）
clusterId integer 是集群id

出参说明

$.data.id为集群id

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

备注
如果原本该集群的权限已经是全项目可用了，这个操作的结果不会改表全项目可用的现状，添加的用户权限是冗余存在的，在全集群权限去除后起效。
批量写入时如遇到报错可以重试写入，接口成功结果幂等。

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

权限需求

用户为私有集群的所有者、负责人, 且为项目管理员

接口描述与说明从项目下某集群准入用户列表删除部分用户
接口路径{{domain}}/aeolus/api/v4/open/app/{{appId}}/clusterWriteUserList

cURL示例

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

入参说明
名称类型必选枚举值含义说明
appId integer 是项目ID
userList list 是删除的用户名（幂等，若传入的用户本来就不具有权限，接口不报错）
clusterId integer 是集群id

出参说明

$.data.id为集群id

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

备注
批量删除时如遇到报错可以重试写入，接口成功结果幂等无

1. 概述

2. 接口说明

3. 数据集标签

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

3.2 创建项目下数据集标签

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

3.4 删除项目下数据集标签

4. 数据集文件夹

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

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

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

5. 数据集

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

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

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

6. 集群配置

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

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

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

智能数据洞察

项目内数据集 API

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

3.2 创建项目下数据集标签

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

3.4 删除项目下数据集标签

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

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

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

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

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

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

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

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

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