数据集同步任务 API--智能数据洞察-火山引擎

文档中心

导航

数据集同步任务 API

最近更新时间：2024.06.26 14:57:17首次发布时间：2024.03.15 14:51:16

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 查看数据集同步任务设置

权限需求
资源
权限
数据集
read
接口描述与说明查看数据集的同步任务设置，包含同步模式，性能参数等等.

请求说明

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

请求示例

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

请求参数

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

返回参数

参数	类型	描述
$.backtrackingConf	object	数据集回溯配置
$.backtrackingConf.dateRange	object	数据集首次创建后的默认回溯周期
$.backtrackingConf.dateRange.endDate	string	回溯开始时间
$.backtrackingConf.dateRange.startDate	string	回溯结束时间
$.doradoPriority	string	同步任务优先级
$.monitorConf	object	数据集同步监控告警配置
$.paramsConfList	object	数据集同步高级参数
$.performanceSettings	object	同步性能设置
$.retryInterval	integer	数据集单次任务同步失败重试间隔
$.scheduleDay	string	同步定时-天
$.scheduleTime	string	同步定时-小时
$.retryNum	integer	数据集单次任务同步失败重试次数
$.syncType	integer	数据集任务同步类型 [手动,自动]
$.writePartition	integer	数据集同步数据写入分区
$.ttl	integer	数据集数据保存生命周期(天)

返回示例

{
    "code": "aeolus/ok",
    "data": {
        "backtrackingConf": {
            "dateRange": {
                "endDate": "2022-12-13",
                "startDate": "2022-12-13"
            },
            "enable": 1
        },
        "doradoPriority": "normal",
        "frequency": "daily",
        "monitorConf": {
            "alarmRules": [
                {
                    "failedAlarmItems": [
                        {
                            "item": "retry_failed"
                        }
                    ],
                    "id": 6***,
                    "name": "auto_aeolus_rule_{{dataSetId}}_16***********_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",
            "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"
    },
    "msg": "成功"
}

备注
无

3.2 更新数据集同步任务设置

权限需求
资源
权限
数据集
write
接口描述与说明此接口所更新的内容等价于数据集详情页前端的同步配置信息->同步频率内容的修改
本接口为全量更新接口，必须在请求时将所有的配置信息填写

资源	权限
数据集	write

请求说明

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

请求示例

curl --location --request PUT '{{domain}}/aeolus/api/v4/open/dataset/{{dataSetId}}/syncSettings' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{jwtToken}}' \
--data-raw '{
    "dataTableConf": {
        "ttl": 8
    },
    "syncConf": {
        "syncType": 1,
        "scheduleConf": {
            "frequency": "daily",
            "scheduleDay": "0",
            "scheduleTime": "00:00"
        }
    }
}'

请求参数

参数	类型	必选	示例值	描述
dataSetId	integer	是		数据集ID
$.dataTableConf.ttl	integer	是		数据集生命周期
$.syncConf.syncType	integer	是	1; 2	数据集同步调度模式 [1为自动, 2为手动]
$.syncConf.scheduleConf	object	是		同步调度conf
$.syncConf.scheduleConf.frequency	string	是	hourly daily weekly monthly every_ten_minutes	自动调度同步时，可分为天级、小时级、分钟级、月级、周级同步
$.syncConf.scheduleConf.scheduleDay	string	是		自动同步设定天数，第几天开始同步，daily下0代表每天都同步当frequency为小时级或分钟级时 scheduleDay则为小时级，即第几个小时开始同步
$.syncConf.scheduleConf.scheduleTime	string	是		自动同步设定小时，一天中第几个小时开始同步当frequency为小时级或分钟级时 scheduleTime则为分钟级，即第几分钟开始同步

返回示例

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

备注
无

3.3 更新数据集同步任务设置-高级设置

权限需求
资源
权限
数据集
write
接口描述与说明更新数据集同步设置中的高级设置，对应数据集前端的同步配置信息->高级配置.
本接口为全量更新接口，必须在请求时将所有的配置信息填写

资源	权限
数据集	write

请求说明

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

请求示例

curl --location --request PUT '{{domain}}/aeolus/api/v4/open/dataset/{{dataSetId}}/syncSettings/advanced' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{jwtToken}}' \
--data-raw '{
    "yarnName": "root.default_hrtech_da_pm",
    "doradoPriority": "normal",
    "retryNum": 3,
    "retryInterval": 5
}'

请求参数

参数	类型	必选	示例值	描述
dataSetId	integer	是		数据集ID
yarnName	string	否		数据集同步使用的队列(非TOB环境)
doradoPriority	integer	是	normal high super_high	数据集同步优先级
retryNum	integer	是		数据集同步失败重试次数
retryInterval	integer	是		数据集同步失败重试间隔时间

返回示例

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

备注
无

3.4 查看数据集同步任务状态信息

权限需求
资源
权限
数据集
read
接口描述与说明查看数据集的同步任务列表，包含业务日期，同步状态，同步时间等等。

请求说明

请求地址：

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

请求示例

curl --location --request GET '{{domain}}/aeolus/api/v4/open/dataset/{{dataSetId}}/syncJob?startDate=2022-12-13&endDate=2022-12-15&nodeId' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{jwtToken}}'

请求参数

参数	类型	必选	描述
dataSetId	integer	是	数据集ID
startDate	string	是	同步任务业务日期范围-开始时间
endDate	string	是	同步任务业务日期范围-截止时间
nodeId		否	维度表的同步任务列表

返回参数

参数	类型	描述
bizTime	string	数据集回溯配置
bizTimePage	string	数据集首次创建后的默认回溯周期
diagPageUrl	string	同步任务诊断页面URL
instanceDurationTime	string	同步任务实例同步持续时间
instanceId	integer	同步任务实例ID
logPageUrl	string	同步任务实例日志URL
scheduledStartTime	string	同步任务实例开始时间
syncEndTime	string	同步任务实例结束时间
tableSize	integer	同步任务实例同步数据尺寸
syncStatus	integer	同步任务实例状态

{
    "code": "aeolus/ok",
    "data": {
        "instanceList": [
            {
                "bizTime": "2022-12-15 00:00:00",
                "bizTimePage": "2022-12-15",
                "diagPageUrl": "https://data.bytedanc*.net/dorado/instance-detail/diagnosis?project=cn_756&id=108301911&schedule=2022-12-15%2000%3A00%3A00&pid=756&status=2&instanceId=1324365220&groupName=cn",
                "instanceDurationTime": null,
                "instanceId": 1324365220,
                "instanceSign": "8332ea1af3a3d960**************",
                "logPageUrl": "https://data.bytedanc*.net/dorado/instance-detail/log?project=cn_7**&id=1********&schedule=2022-12-15%2000%3A00%3A00&pid=7**&instanceId=1324365220&groupName=cn",
                "scheduledStartTime": "2022-12-16 00:00:00",
                "syncEndTime": null,
                "syncStartTime": null,
                "syncStatus": 2,
                "syncStatusDescCode": 3,
                "tableSize": "-",
                "taskId": 9178
            },
            {
                "bizTime": "2022-12-14 00:00:00",
                "bizTimePage": "2022-12-14",
                "diagPageUrl": "https://data.bytedanc*.net/dorado/instance-detail/diagnosis?project=cn_756&id=108******&schedule=2022-12-14%2000%3A00%3A00&pid=756&status=4&instanceId=132*******&groupName=cn",
                "instanceDurationTime": 501.0,
                "instanceId": 1322531180,
                "instanceSign": "b1285**************",
                "logPageUrl": "https://data.bytedanc*.net/dorado/instance-detail/log?project=cn_756&id=108******&schedule=2022-12-14%2000%3A00%3A00&pid=756&instanceId=132*******&groupName=cn",
                "scheduledStartTime": "2022-12-15 00:00:00",
                "syncEndTime": "2022-12-15 00:33:29",
                "syncStartTime": "2022-12-15 00:25:08",
                "syncStatus": 4,
                "syncStatusDescCode": 30,
                "tableSize": "56",
                "taskId": 9***
            },
            {
                "bizTime": "2022-12-13 00:00:00",
                "bizTimePage": "2022-12-13",
                "diagPageUrl": "https://data.bytedanc*.net/dorado/instance-detail/diagnosis?project=cn_756&id=108301911&schedule=2022-12-13%2000%3A00%3A00&pid=7**&status=4&instanceId=132*******&groupName=cn",
                "instanceDurationTime": 1197.0,
                "instanceId": 1322222925,
                "instanceSign": "af3a3d960**************",
                "logPageUrl": "https://data.bytedanc*.net/dorado/instance-detail/log?project=cn_756&id=108*******&schedule=2022-12-13%2000%3A00%3A00&pid=7**&instanceId=132*******&groupName=cn",
                "scheduledStartTime": "2022-12-14 00:00:00",
                "syncEndTime": "2022-12-14 12:38:57",
                "syncStartTime": "2022-12-14 12:19:00",
                "syncStatus": 4,
                "syncStatusDescCode": 30,
                "tableSize": "56",
                "taskId": 9178
            }
        ],
        "total": 3
    },
    "msg": "成功"
}

备注
- 数据集任务实例状态示例值定义
  syncStatus值
  实例状态
  1
  未就绪
  2
  等待执行
  3
  执行中
  4
  运行成功
  5
  运行失败
  6
  已终止

syncStatus值	实例状态
1	未就绪
2	等待执行
3	执行中
4	运行成功
5	运行失败
6	已终止

3.5 提交数据集同步任务回溯

权限需求
资源
权限
数据集
write
接口描述与说明批量提交同步任务实例，实现数据回溯。
注意回溯日期时间段可选择范围，应小于等于数据集的数据生命周期(ttl)

资源	权限
数据集	write

请求说明

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

请求示例

curl --location --request POST '{{domain}}/aeolus/api/v4/open/dataset/{{dataSetId}}/syncJob' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{jwtToken}}' \
--data-raw '{
    "nodeId": "",
    "startDate": "2022-12-07",
    "endDate": "2022-12-11",
    "checkMinMax": true,
    "skipCheck": true,
    "isSpecifyQueue": true,
    "queueName": "root.oryx_aeolus_vip",
    "maxParallelism": 10
}'

请求参数

参数	类型	必选	描述
dataSetId	integer	是	数据集ID
nodeId	string	否	如不指定则默认回溯主表的数据；如填入则回溯维度表的数据
startDate	string	是	同步任务业务日期范围-回溯开始时间
endDate	string	是	同步任务业务日期范围-回溯截止时间
checkMinMax	bool	否	检查同步分区范围是否超出限制
skipCheck	bool	否	跳过依赖检查
isSpecifyQueue	bool	否	是否制定队列回溯(非TOB环境)
queueName	string	否	指定的队列名称(非TOB环境)
maxParallelism	integer	否	当前同步任务的实例最大的行数，主要用于批量回溯时，防止所有回溯实例同一时刻被全部调起进入执行例：回溯了100个实例，设置最大并行数为50，则最多只会有50个实例在执行，其余50个会进入队列等待

返回示例

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

备注
无

3.6 终止数据集同步任务实例

权限需求
资源
权限
数据集
write
接口描述与说明批量终止任务实例，2.60.0版本可用

资源	权限
数据集	write

请求说明

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

请求示例

curl --location --request POST '{{domain}}/aeolus/api/v4/open/dataset/{{dataSetId}}/stopSyncJob' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{jwtToken}}' \
--data-raw '{
    "instanceList": [
        {
            "id": 226*******, 
            "taskTime": "2023-12-25 00:00:00",
            "sign": ""
        },
        {
            "id": 226*******, 
            "taskTime": "2023-12-24 00:00:00"
        }
     ],
    "nodeId": ""
}'

请求参数

参数	类型	必选	描述
$.nodeId	string	否	如不指定则默认终止主表任务实例；如填入则终止维度表任务实例
$.instanceList	object	是	终止实例范围
$.instanceList.id	string	是	终止任务实例的ID，可从查看数据集同步任务状态信息接口里的instanceId获取
$.instanceList.taskTime	string	是	终止任务实例的业务日期，可从查看数据集同步任务状态信息接口里的bizTime获取
$.instanceList.sign	string	是	同步任务实例签名，可从查看数据集同步任务状态信息接口里的instanceSign获取

返回示例

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

备注
无

3.7查看数据集同步任务实例详细信息

权限需求

资源	权限
数据集	read

接口描述与说明
根据数据集ID和实例ID查看任务实例详细信息，2.64.0版本可用

请求说明

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

请求示例

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

请求参数

参数	类型	必选	示例值	描述
instance_id_list	array	是		同步任务实例ID集合，实例ID可从查看数据集同步任务状态信息接口里的instanceId获取

返回参数

名称	类型	描述
id	integer	同步任务实例ID
scheduleTaskId	integer	同步任务ID
subTaskId	integer	同步任务输出节点ID
taskId	integer	同步任务PrepID
appExternalId	string	yarn任务ID
createTime	string	同步任务实例创建时间
taskTime	string	同步任务实例业务日期
startTime	string	同步任务实例开始时间
endTime	string	同步任务实例结束时间
scheduleTime	string	同步任务实例调度时间
status	string	同步任务实例状态
triggerType	string	同步任务实例触发类型，有SCHEDULED(例行)/BACKFILL(回溯)

返回示例

{
    "code": "aeolus/ok",
    "data": [
        "id": 94,
        "scheduleTaskId": 3,
        "subTaskId": 2,
        "taskId": 1,
        "appExternalId": "application_17***********_****",
        "createTime": "2024-02-23 23:00:00",
        "taskTime": "2024-02-23 20:00:00",
        "startTime": "2024-02-24 00:01:01",
        "endTime": "2024-02-24 00:02:01",
        "scheduleTime": "2024-02-24 00:00:00",
        "status": "SUCCEEDED",
        "triggerType": "BACKFILL"
    ]
    "msg": "成功"
}

备注

无