You need to enable JavaScript to run this app.
导航

数据集操作 API

最近更新时间2024.03.15 15:31:43

首次发布时间2024.03.15 14:50:49

1. 概述

数据集 Open API 包含了:数据集操作 API、数据集信息 API、数据集维度指标与血缘关系 API、数据集同步任务 API、数据集可视化查询参数与开放查询 API、数据集模型画布与运维类工具 API、项目内数据集 API。
本文为您介绍的是“数据集操作类的 Open 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 创建数据集

  • 权限需求

    资源权限
    项目write
    文件夹write
  • 接口描述与说明

创建数据集,建议现阶段用户使用时先在前端使用 chrome 开发者工具抓取较贴切的数据集创建 payload,随后进行部分修改。

不建议从零构建 payload,如有相关疑问,可咨询运维人员。

  • 接口路径

  • cURL示例注:创建数据集更新数据集需要额外在headers中带上app-id: xxx

    curl --location --request POST '{{domain}}/aeolus/api/v4/open/dataset' \
    --header 'Content-Type: application/json' \
    --header 'app-id: {{appId}}' \
    --header 'Authorization: Bearer {{jwtToken}}' \
    --data-raw '{
        "baseConf": {
            "dataSetName": "新版Open-Api测试用数据集-1",
            "descr": "这是一段数据集使用描述",
            "appId": 7777947,
            "dataSetType": 22,
            "ownerEmailPrefix": "husimin.xcl",
            "demoUrl": "http://demoUrl.com",
            "isAuthEnable": 0,
            "isIntelligentSyncEnable": 1,
            "connectionMode": 0,
            "syncMode": 2,
            "parentId": 0,
            "confidentiality": "L3",
            "groupId": 193,
            "groupName": "test-no-multiple",
            "groupType": 0
        },
        "nodeConf": [
            {
                "tbId": "cn//aeolus_excel_upload_aeolus_toy//table_4f0cc551_9dfa_4915_a38f_737c716591a8",
                "nodeType": "table",
                "dataSourceType": "ch_excel",
                "dataSourceId": 25958,
                "clusterName": "cn",
                "dbName": "aeolus_excel_upload_aeolus_toy",
                "tbName": "table_4f0cc551_9dfa_4915_a38f_737c716591a8",
                "tableAlias": "table_4f0cc551_9dfa_4915_a38f_737c716591a8",
                "displayDbName": "测试用excel表",
                "schemaName": "Sheet1",
                "fileId": "13516",
                "query": "",
                "fullOption": false,
                "fields": [
                     {
                        "name": "字段一",
                        "alias": "`字段一`",
                        "type": "Nullable(String)",
                        "prepType": "string",
                        "comment": null,
                        "isSourceTableField": false,
                        "is_select": true,
                        "isDynamicPartition": false
                    },
                    {
                        "name": "字段二",
                        "alias": "`字段二`",
                        "type": "Nullable(Int64)",
                        "prepType": "int",
                        "comment": null,
                        "isSourceTableField": false,
                        "is_select": true,
                        "isDynamicPartition": false
                    },
                ],
                "params": {
                    "extractType": "{\"key\":\"full\"}"
                },
                "partitionConfList": [],
                "tableRowFilter": {},
                "nodeId": "c3963aa8-ddc6-4995-b17e-9662a220e335"
            }
        ],
        "linkConf": [],
        "dimMetList": [
            {
                "name": "p_date",
                "displayName": "p_date",
                "expr": "p_date",
                "descr": "p_date",
                "defaultType": "date",
                "castDataTypeName": null,
                "dimMetCategoryId": null,
                "editable": 0,
                "dimMetMixOrder": 0,
                "geoInfo": null,
                "visible": 1,
                "dimMetVariety": 1,
                "showExpr": 1,
                "isAutoAdd": 1,
                "mapType": 0,
                "dimMetOrder": 0,
                "groupType": 0
            },
            {
                "name": "字段二",
                "expr": "`字段二`",
                "descr": null,
                "defaultType": "int",
                "castDataTypeName": null,
                "dimMetCategoryId": null,
                "editable": 1,
                "dimMetMixOrder": 1,
                "geoInfo": null,
                "visible": 1,
                "dimMetVariety": 2,
                "showExpr": 1,
                "mapType": 0,
                "dimMetOrder": 1,
                "groupType": 0
            },
            {
                "name": "字段一",
                "expr": "`字段一`",
                "descr": null,
                "defaultType": "string",
                "castDataTypeName": null,
                "dimMetCategoryId": null,
                "editable": 1,
                "dimMetMixOrder": 2,
                "geoInfo": null,
                "visible": 1,
                "dimMetVariety": 2,
                "showExpr": 1,
                "mapType": 0,
                "dimMetOrder": 2,
                "groupType": 0
            }
        ],
        "dimMetCategoryList": [],
        "dataTableConf": {
            "ttl": 7,
            "dataSourceId": 0,
            "driverName": "click_house",
            "createConf": {},
            "sampleRate": 1,
            "partitionFieldList": [
                {
                    "name": "p_date",
                    "valueList": null
                }
            ],
            "chQueryParams": {
                "openStrongConsistencyCheck": false
            },
            "clusterName": "cn",
            "kafkaCluster": "cn"
        },
        "syncConf": {
            "syncType": 1,
            "scheduleConf": {
                "frequency": "daily",
                "scheduleDay": "0",
                "scheduleTime": "00:00"
            },
            "writePartition": 0,
            "backtrackingConf": {
                "enable": 1,
                "dateRange": {
                    "startDate": "2022-12-19",
                    "endDate": "2022-12-19"
                }
            },
            "uniqueIndexList": [],
            "doradoAutoDdl": 0,
            "yarnName": "root.default_hrtech_da_pm",
            "doradoPriority": "normal",
            "dynamicPartitionMode": false,
            "paramsConfList": [
                {
                    "name": "tqs.query.auto.retry.enable",
                    "value": "true"
                }
            ],
            "monitorConf": {
                "alarmRules": [
                    {
                        "failedAlarmItems": [
                            {
                                "item": "retry_failed"
                            }
                        ],
                        "timeoutAlarmItems": [],
                        "resultAlarmItems": [],
                        "normalNoticeConf": [
                            {
                                "noticeChannel": "lark",
                                "users": [
                                    "husimin.xcl"
                                ],
                                "dutySchedules": []
                            }
                        ]
                    }
                ]
            },
            "retryNum": 1,
            "retryInterval": 5
        },
        "whereConf": {
            "requiredRowFilter": [],
            "nodeRowFilter": {}
        },
        "labelConf": {},
        "dependencyConf": {
            "dependencies": [],
            "dependencyMethod": 0,
            "earliestBackTime": null,
            "filterUnCompleteSensor": null,
            "isSelfDepend": false,
            "nodeDepStatus": 1,
            "nodeKey": "Load_6ce7d3121671521535200",
            "nodeName": "输出_db_name.table_name"
        },
        "dagTagConf": {
            "dimTbNodes": []
        }
    }'
    
  • 入参说明

    📌 标注该 icon 的入参,其值多是由前端有多重逻辑判而决定的,其本身对您而言存在一定的理解成本,因此不建议您从零构造 payload,如您有相关疑问,可咨询运维人员。

    名称类型枚举值含义说明
    $.baseConfobject数据集-基础信息
    $.baseConf.dataSetNamestring数据集-名称
    $.baseConf.descrstring数据集-描述
    $.baseConf.appIdinteger数据集-所在项目的Id
    $.baseConf.dataSetType📌integer数据集-类型
    $.baseConf.ownerEmailPrefixstring数据集-拥有人
    $.baseConf.demoUrlstring数据集-使用示例

    $.baseConf.connectionMode

    integer

    0:抽取
    1:直连

    数据集-连接模式

    $.baseConf.syncMode

    integer

    [0, 1, 2]
    # 同步模式
    # dorado各种toCH通道任务
    SYNC_MODE_DORADO = 0
    # prepare任务
    SYNC_MODE_PREPARE = 1
    # dorado hsql任务,利用tqs执行导入
    SYNC_MODE_HSQL = 2

    数据集-同步模式

    $.baseConf.parentIdinteger数据集-文件夹路径;0代表根目录
    $.baseConf.confidentialitystring(非TOB环境)数据集-数据集风险等级
    $.baseConf.groupIdinteger(非TOB环境)数据集-资源组ID
    $.baseConf.groupNamestring(非TOB环境)数据集-资源组名称

    $.nodeConf📌

    list

    数据集-画布模型

    $.nodeConf[i].tbIdstring画布模型-数据源-节点Id
    $.nodeConf[i].nodeTypestring画布模型-数据源-节点类型
    $.nodeConf[i].dataSourceTypestring画布模型-数据源类型
    $.nodeConf[i].dataSourceIdinteger画布模型-数据源-数据源ID
    $.nodeConf[i].clusterNamestring画布模型-数据源-集群名称(如hive或ch类型数据源该字段有意义,其他情况下该字段值为region,如cn)
    $.nodeConf[i].dbNamestring画布模型-数据源-db名称
    $.nodeConf[i].tbNamestring画布模型-数据源-表名称
    $.nodeConf[i].tableAliasstring画布模型-数据源-表别称,当画布上多次拉取一个数据源时,需要采用别称来区别
    $.nodeConf[i].displayDbNamestring画布模型-数据源-db的展示名称
    $.nodeConf[i].schemaNamestring画布模型-数据源-schema名称,对于excel表则是表内的sheet名称
    $.nodeConf[i].tableAliasstring画布模型-数据源-表别称
    $.nodeConf[i].fields[i].prepTypestring画布模型-数据源字段-字段prep类型
    $.nodeConf[i].fields[i].is_selectbool画布模型-数据源字段-字段是否已勾选
    $.nodeConf[i].fields[i].namestring画布模型-数据源字段-名称
    $.nodeConf[i].fields[i].isDynamicPartitionbool画布模型-数据源字段-是否是动态分区

    $.nodeConf[i].params

    object

    画布模型-数据源节点-抽取参数设置

    $.linkConf

    list

    画布模型-数据源节点-join关系

    $.dimMetList

    list

    数据集-维度指标字段信息列表

    $.dimMetList[i].displayName

    string

    数据集-维度指标字段-字段名称

    $.dimMetList[i].editableinteger数据集-维度指标字段-是否可编辑
    $.dimMetList[i].mapTypeinteger数据集-维度指标字段-字段类型

    $.dimMetList[i].dimMetCategoryId

    integer

    数据集-维度指标字段-所属字段分类ID

    $.dimMetList[i].defaultTypestring数据集-维度指标字段-解析出的默认类型
    $.dimMetList[i].descrstring数据集-维度指标字段-字段描述

    $.dimMetList[i].dimMetOrder

    integer

    数据集-维度指标字段-排序

    $.dimMetList[i].namestring数据集-维度指标字段-字段名称
    $.dimMetList[i].exprstring数据集-维度指标字段-字段表达式
    $.dataTableConfobject数据集-抽取类型底表配置
    $.dataTableConf.dataSourceId 📌integer数据集-底表写入存储引擎-数据源ID
    $.dataTableConf.chQueryParams.openStrongConsistencyCheck📌bool
    $.dataTableConf.clusterName📌string数据集-底表写入存储引擎-集群名称
    $.dataTableConf.driverName📌stringclick_house数据集-底表写入存储引擎-存储引擎类型
    $.dataTableConf.partitionFieldList[0].name📌string数据集-底表写入存储引擎-底表分区名称
    $.dataTableConf.ttl📌integer数据集-底表写入存储引擎-底表ttl(数据集生命周期)
    $.dataTableConf.sampleRate📌integer数据集-底表写入存储引擎-底表采样比例
    $.dataTableConf.kafkaCluster📌string数据集-底表写入存储引擎-kafka类型数据集集群
    $.syncConfobject数据集-同步任务配置
    $.syncConf.monitorConf📌object数据集-同步任务配置-同步任务状态监控配置
    $.syncConf.scheduleConf📌object数据集-同步任务配置-定时调度配置;下属字段含义详情可见本文档 2.2.5 数据集同步任务-查看数据集同步任务设置
    $.whereConfobject数据集-筛选配置

    $.whereConf.nodeRowFilter

    object

    数据集-同步任务-非分区筛选条件

    $.whereConf.extractCondition

    数据集-同步任务-数据筛选Tab

    $.whereConf.requiredRowFilter

    数据集-同步任务-分区筛选条件

  • 出参说明

    {
        "code": "aeolus/ok",
        "data": {
            "dataSetId": {{dataSetId}}
        },
        "msg": "成功"
    }
    
  • 备注

3.2. 更新数据集

  • 权限需求

    资源权限
    项目write
    文件夹write
  • 接口描述与说明更新数据集,payload 与新建接口略有不同,但是含义基本相同。

  • 接口路径

{{domain}}/aeolus/api/v4/open/datase/{{dataSetId}}

  • cURL 示例

    curl --location --request PUT '{{domain}}/aeolus/api/v4/open/dataset/{{dataSetId}}' \
    --header 'Content-Type: application/json' \
    --header 'app-id: {{appId}}' \
    --header 'Authorization: Bearer {{jwtToken}}' \
    --data-raw '{
        "baseConf": {
            "dataSetName": "新版Open-Api测试用数据集",
            "descr": "这是一段数据集使用描述",
            "appId": 7777947,
            "dataSetType": 22,
            "ownerEmailPrefix": "husimin.xcl",
            "demoUrl": "http://demoUrl.com",
            "isAuthEnable": 1,
            "isIntelligentSyncEnable": 1,
            "connectionMode": 0,
            "syncMode": 2,
            "parentId": 0,
            "confidentiality": "L3",
            "generalTags": [],
            "groupId": 193,
            "groupName": "test-no-multiple",
            "groupType": 0,
            "lineOfBusiness": [],
            "productName": "",
            "regionType": [],
            "thirdPartyConf": null,
            "dataSetId": 192298
        },
        "nodeConf": [
            {
                "tbId": "cn//aeolus_excel_upload_aeolus_toy//table_4f0cc551_9dfa_4915_a38f_737c716591a8",
                "nodeType": "table",
                "dataSourceType": "ch_excel",
                "dataSourceId": 25958,
                "clusterName": "cn",
                "dbName": "aeolus_excel_upload_aeolus_toy",
                "tbName": "table_4f0cc551_9dfa_4915_a38f_737c716591a8",
                "tableAlias": "table_4f0cc551_9dfa_4915_a38f_737c716591a8",
                "displayDbName": "配比四刷-v4",
                "schemaName": "Sheet1",
                "fileId": "13516",
                "query": "",
                "fullOption": false,
                "fields": [
                    {
                        "name": "字段一",
                        "alias": "`字段一`",
                        "type": "Nullable(String)",
                        "prepType": "string",
                        "comment": null,
                        "isSourceTableField": false,
                        "is_select": true,
                        "isDynamicPartition": false
                    },
                    {
                        "name": "字段二",
                        "alias": "`字段二`",
                        "type": "Nullable(String)",
                        "prepType": "string",
                        "comment": null,
                        "isSourceTableField": false,
                        "is_select": true,
                        "isDynamicPartition": false
                    }
                ],
                "params": {
                    "extractType": "{\"key\":\"full\"}"
                },
                "advanceSettings": [],
                "partitionConfList": [],
                "tableRowFilter": {},
                "nodeId": "c3963aa8-ddc6-4995-b17e-9662a220e335"
            }
        ],
        "linkConf": [],
        "dimMetList": [
            {
                "id": 1586869950219,
                "name": "p_date",
                "displayName": "p_date",
                "expr": "p_date",
                "descr": "p_date",
                "defaultType": "date",
                "castDataTypeName": null,
                "dimMetCategoryId": null,
                "editable": 0,
                "dimMetMixOrder": 0,
                "geoInfo": null,
                "visible": 1,
                "dimMetVariety": 1,
                "showExpr": 1,
                "isAutoAdd": 1,
                "mapType": 0,
                "dimMetOrder": 0,
                "groupType": 0
            },
            {
                "id": 1586869950220,
                "name": "字段二",
                "expr": "`字段二`",
                "descr": null,
                "defaultType": null,
                "castDataTypeName": null,
                "dimMetCategoryId": null,
                "dimMetCategoryType": null,
                "editable": 1,
                "dimMetMixOrder": 1,
                "dataFormat": null,
                "isDeletedField": 0,
                "visible": 1,
                "dimMetVariety": 2,
                "showExpr": 1,
                "mapType": 0,
                "dimMetOrder": 1,
                "groupType": 0
            },
            {
                "id": 1586869950221,
                "name": "字段一",
                "expr": "`字段一`",
                "descr": null,
                "defaultType": null,
                "castDataTypeName": null,
                "dimMetCategoryId": null,
                "dimMetCategoryType": null,
                "editable": 1,
                "dimMetMixOrder": 2,
                "dataFormat": null,
                "isDeletedField": 0,
                "visible": 1,
                "dimMetVariety": 2,
                "showExpr": 1,
                "mapType": 0,
                "dimMetOrder": 2,
                "groupType": 0
            }
        ],
        "dataTableConf": {
            "ttl": 7,
            "dataSourceId": 10002,
            "driverName": "click_house",
            "createConf": {
                "primaryKeyList": []
            },
            "sampleRate": 1,
            "partitionFieldList": [
                {
                    "name": "p_date",
                    "valueList": null
                }
            ],
            "chQueryParams": {
                "openStrongConsistencyCheck": false
            },
            "clusterName": "cn",
            "kafkaCluster": "cn"
        },
        "syncConf": {
            "syncType": 1,
            "scheduleConf": {
                "frequency": "daily",
                "scheduleDay": "0",
                "scheduleTime": "00:00"
            },
            "writePartition": 0,
            "backtrackingConf": {
                "enable": 0,
                "dateRange": {}
            },
            "uniqueIndexList": [],
            "doradoAutoDdl": 0,
            "yarnName": "root.default_hrtech_da_pm",
            "doradoPriority": "normal",
            "dynamicPartitionMode": false,
            "paramsConfList": [
                {
                    "name": "tqs.query.auto.retry.enable",
                    "value": "true"
                }
            ],
            "monitorConf": {
                "alarmRules": [
                    {
                        "id": 6859,
                        "failedAlarmItems": [
                            {
                                "item": "retry_failed"
                            }
                        ],
                        "timeoutAlarmItems": [],
                        "resultAlarmItems": [],
                        "normalNoticeConf": [
                            {
                                "noticeChannel": "lark",
                                "users": [
                                    "husimin.xcl"
                                ],
                                "dutySchedules": []
                            }
                        ]
                    }
                ]
            },
            "retryNum": 1,
            "retryInterval": 5
        },
        "whereConf": {
            "requiredRowFilter": [],
            "nodeRowFilter": {}
        },
        "labelConf": {},
        "dependencyConf": {
            "dependencies": [],
            "dependencyMethod": 0,
            "earliestBackTime": null,
            "filterUnCompleteSensor": null,
            "isSelfDepend": false,
            "nodeDepStatus": 1,
            "nodeKey": "Load_8b5b78ee1671521586290",
            "nodeName": "输出_db_name.table_name"
        },
        "dagTagConf": {
            "dimTbNodes": []
        }
    }'
    
  • 入参说明入参参考本文档 2.2.1 操作数据集-创建数据集接口。

  • 出参说明

    {
        "code": "aeolus/ok",
        "data": {
            "dataSetId": {{dataSetId}}
        },
        "msg": "成功"
    }
    
  • 备注

3.3. 检查数据集是否可被移入回收站

  • 权限需求

    资源权限
    数据集admin
  • 接口描述与说明检查当前数据集是否存在血缘关联及其他问题,如无问题则返回空列表,表示当前可以直接删除,否则按照接口返回内容进行血缘解绑。

  • 接口路径{{domain}}/aeolus/api/v4/open/dataset/{{dataSetId}}/recyclable

  • cURL示例

    curl --location --request GET '{{domain}}/aeolus/api/v4/open/dataset/{{dataSetId}}/recyclable' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer {{jwtToken}}'
    
  • 入参说明

    名称类型必选枚举值含义说明
    dataSetIdinteger数据集ID
  • 出参说明正常情况,可直接删除

    {
        "code": "aeolus/ok",
        "data": [],
        "msg": "成功"
    }
    
  • 备注

    应与移入数据集到回收站接口联动使用

3.4. 移入数据集到回收站

  • 权限需求

    资源权限
    数据集admin
  • 接口描述与说明将数据集移入回收站,非彻底删除。

  • 接口路径{{domain}}/aeolus/api/v4/open/dataset/{{dataSetId}}/recycle

  • cURL示例

    curl --location --request DELETE '{{domain}}/aeolus/api/v4/open/dataset/{{dataSetId}}/recycle' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer {{jwtToken}}'
    
  • 入参说明

    名称类型必选枚举值含义说明
    dataSetIdinteger数据集ID
  • 出参说明

    {
        "code": "aeolus/ok",
        "data": [],
        "msg": "成功"
    }
    
  • 备注

    应与检查数据集是否可被移入回收站接口联动使用

3.5 从回收站恢复数据集

  • 权限需求

    资源权限
    数据集admin
  • 接口描述与说明从回收站将数据集移出。

  • 接口路径{{domain}}/aeolus/api/v4/open/dataset/{{dataSetId}}/restore

  • cURL示例

    curl --location --request PUT '{{domain}}/aeolus/api/v4/open/dataset/{{dataSetId}}/restore' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer {{jwtToken}}'
    
  • 入参说明

    名称类型必选枚举值含义说明
    dataSetIdinteger数据集ID
  • 出参说明fails为空列表则代表恢复数据集成功

    {
        "code": "aeolus/ok",
        "data": {
            "fails": []
        },
        "msg": "成功"
    }
    
  • 备注

3.6 彻底删除数据集

  • 权限需求

    资源权限
    数据集admin
  • 接口描述与说明彻底删除数据集,清空数据集的数据、底表,关闭同步任务等;仅保留数据集本身的元信息。

  • 接口路径{{domain}}/aeolus/api/v4/open/dataset/{{dataSetId}}

  • cURL示例

    curl --location --request DELETE '{{domain}}/aeolus/api/v4/open/dataset/{{dataSetId}}' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer {{jwtToken}}'
    
  • 入参说明

    名称类型必选枚举值含义说明
    dataSetIdinteger数据集ID
  • 出参说明删除成功则返回数据集ID

    {
        "code": "aeolus/ok",
        "data": [
            "180664"
        ],
        "msg": "成功"
    }
    
  • 备注

3.7 移动数据集位置(更新文件夹路径)

  • 权限需求

    资源权限
    数据集write
    新路径文件夹write
  • 接口描述与说明将指定数据集移动到特定的文件夹下,可与本文档 2.3.2 数据集文件夹-获取项目下数据集文件夹信息接口配合使用。

  • 接口路径~~{{domain}}/aeolus/api/v4/open/dataset/{{dataSetId}}/folder/move~~

    # "move" operation is all about replacing the folder of the dataSet.

    {{domain}}/aeolus/api/v4/open/dataset/{{dataSetId}}/folder

  • cURL 示例

    curl --location --request PUT '{{domain}}/aeolus/api/v4/open/dataset/{{dataSetId}}/folder' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer {{jwtToken}}' \
    --data-raw '{
        "folderId": 2706
    }'
    
  • 入参说明

    名称类型必选枚举值含义说明
    dataSetIdinteger数据集 ID
    folderIdinteger待移动到的目标文件夹 ID
  • 出参说明

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