历史版本14 :定时任务相关接口介绍 返回文档
编辑时间: 内容长度:图片数:目录数: 修改原因:

目录:

1. 概述编辑

1.1 版本

FineDataLink 版本开放平台-FineDataLink接口插件功能变动
4.0.281.0.1

1.2 应用场景

用户希望能够按需触发\执行定时任务,以提高数据时效性,场景如下所示:

  • 业务人员在 FR 填报页面录入数据后,数据需要经 FDL 的定时任务计算形成结果数据,期望能够及时看到最新的数据。

  • 业务人员期望能够在报表上看到实时的数据,或者有个按钮能够触发数据更新。

  • 企业自建或采购的业务系统,期望能够在某些动作完成后触发定时任务执行,使数据的更新时效性更高。

  • 业务人员在简道云录入数据后,数据需要经 FDL 的定时任务做同步或处理,期望能够及时看到最新的数据。

1.3 功能简介

使用「开放平台-FineDataLink接口」插件,可提供 FineDataLink 相关接口,满足用户按需触发\执行定时任务的需求。

2. 插件介绍编辑

注:API 管理更多介绍请参见文档:开放平台插件

2.1 安装插件

1)用户需要先注册    功能点,才能正常使用该插件。

2)需要先安装「开放平台」插件,再安装「开放平台-FineDataLink接口」插件

注:FineReport11.0 中已内置「开放平台」插件,只需安装「开放平台-FineDataLink接口」插件即可。

点击下载插件:开放平台插件

安装插件方法请参见:服务器插件管理

2.2 安装成功后界面介绍

2.2.1 任务id

插件安装成功后,「数据开发」处展示的定时任务新增「任务ID」信息,且支持复制。如下图所示:

2.png

2.2.2 运行记录ID

点击「管理系统>任务运维>运行记录」,可查看记录ID,鼠标悬停支持复制。如下图所示:

2.png

3. 接口认证模式说明编辑

接口触发的任务,被定义为手动触发,操作用户和认证方式有关。

3.1 开放平台认证模式

3.1.1 说明

注:适用于独立部署工程,建议使用AkSk直接认证、摘要签名认证。

1)平台内置了 3 种备选认证方式。使用者也可根据需求,自行增加新的认证方式。若采用开放平台提供的 cliend_id 和 secret 的方式认证,默认为超管用户。详情请参见:开放平台插件

3.png

2)接口认证逻辑由「开放平台>应用」管控,可参见 开放平台插件 认证方式介绍。例如选择 aksk 认证模式,在接口请求时需传递 clientld 和 secret 参数。具体使用示例请参见:开放平台API接口调用示例

3)通过开放平台认证后,接口的操作用户默认为超管用户

4)当需要修改操作用户时,可在 header 或 query 中添加 decUser 参数,参数值为用户名或用户id。

3.1.2 示例

注:本示例使用的是基于任务ID运行任务接口(本文 4.4 节)。

1)点击「应用管理」,新建应用,需记住「应用ID」与「密钥」的值,如下图所示:

9.png

2)点击「权限管理>API」,本次示例选定API为「基于任务ID运行任务」,为其开放上面新建应用的权限。如下图所示:

10.png

3)添加 clientld 和 secret 参数。接口最终为:http://localhost:8068/webroot/decision/sp/client/api/fdl/work/9cd75924-f2dc-4fb9-9ca0-441c1943157d/execute?clientId=fe45a247c7e54078babddb230128816b&secret=f3ea557912804f79838f1d1329712992

1692694878253484.png

响应结果如下图所示:

1692694900482847.png

3.2 fine_auth_token 认证模式

注:适用于集成部署工程,为产品内置的登录认证。

3.2.1 说明

若采用和平台一样的 fine_oauth_token 的认证方式,采用的就是生成 token 的用户去操作。详情请参见:开放平台子插件

1)在请求地址中添加上module/路径时(例如,原始为 /sp/client/api/*,添加后变为/sp/client/api/module/*),接口认证逻辑不再由「开放平台>应用」来管控,而是需要携带帆软平台的认证登录标识 fine_oauth_token,未携带或携带无效 token 时接口认证失败。

2)token 携带方式:和产品用户 token 传递方式一致。

3)该认证模式下,接口操作用户为 fine_oauth_token 中映射的用户,无法通过 decUser 参数修改。

3.2.2 示例

1)接口说明

本文 4.4 节,基于任务ID运行任务接口为:http://localhost:8080/webroot/decision/sp/client/api/fdl/work/{workId}/execute,要使用  fine_oauth_token 的认证方式,需要加上module/路径,为:http://localhost:8080/webroot/decision/sp/client/api/module/fdl/work/{workId}/execute

2)获取 fine_auth_token

用户登录 FineDataLink 系统,F12,在「Network>Headers」下,获取fine_auth_token的值。如下图所示:

4.png

放在请求的queryString中,以?fine_auth_token=token的参数形式拼接到url上。如下图所示:

1692688486531964.png

3)具体示例

设置界面如下图所示:

注:本示例使用的是基于任务ID运行任务接口(本文 4.4 节),由于该接口body内参数都为非必填,此处填{}。

1692694740776204.png

响应结果如下图所示:

1692688971270370.png

4. 接口介绍编辑

注:实例ID即为运行记录ID,运行记录ID在「任务运维>定时任务>运行记录」中查看。

4.1 根据任务ID查询实例列表

基本信息:

接口URL:http://localhost:8080/webroot/decision/sp/client/api/fdl/work/{workId}/records

Content-Type:application/json

认证方式:无需认证

请求类型:POST

请求参数:

1)路径参数及说明:

参数名
参数值是否必填参数类型描述说明
workId868478d9-a36d-481f-b42d-6074310c2829222
String【必填】任务ID

2)body请求参数:

{
"latest": false, //【非必填】仅查询最近一次:是、否  /*不填则为否*/
"startTime": "", //【非必填】开始时间  /*不填则为无限*/
"finishTime": "", //【非必填】结束时间  /*不填则为无限*/
"taskStatus": "SUCCESS", //【非必填】运行状态:成功、失败、中断、运行中  /*不填则返回所有*/ 枚举值: INITIAL  SUCCESS  FAIL  RUNNING  DUPLICATE  INVALID  ERROR  INTERRUPT
"triggerMethod": "MANUAL" //【非必填】触发方式:手动、定时  /*不填则返回所有*/ 枚举:MANUAL   FIX_TIME
}
参数名
参数值是否必填参数类型描述说明
latestfalseBoolean【非必填】仅查询最近一次:是、否,不填则为否
startTime
String【非必填】开始时间 ,不填则为无限
finishTime
String【非必填】结束时间,不填则为无限
taskStatus
String【非必填】运行状态:成功、失败、中断、运行中,不填则返回所有,枚举值: INITIAL SUCCESS FAIL RUNNING DUPLICATE INVALID ERROR INTERRUPT
triggerMethodMANUALString【非必填】触发方式:手动、定时,不填则返回所有,枚举:MANUAL FIX_TIME

响应示例:

成功

{
"status": 200,
"data": {
"executeIds": [
"7d5a4b14-f0de-47b8-91ad-a8777b76236c",
"0d20a589-e66f-4b47-8256-e40e0252eea2",
"24c6d78a-2d4f-40b5-b9fb-08eef1133612",
"9fa0d375-89f4-425f-8e39-0c6de623637a",
]
}
}
参数名
参数值参数类型描述说明
status200Integer
data
Object
data.executeIds7d5a4b14-f0de-47b8-91ad-a8777b76236cArray

实例ID列表

实例ID即为运行记录ID

4.2 根据任务名查询实例列表

基本信息:

接口URL:http://localhost:8080/webroot/decision/sp/client/api/fdl/work/records

Content-Type:application/json

认证方式:无需认证

请求类型:POST

请求参数:

body 请求参数:

{
"workName": "fdlDemo", //【必填】任务名称
"latest": true, //【非必填】仅查询最近一次:是、否  /*不填则为否*/
"startTime": "", //【非必填】开始时间  /*不填则为无限*/
"finishTime": "", //【非必填】结束时间  /*不填则为无限*/
"taskStatus": "SUCCESS", //【非必填】运行状态:成功、失败、中断、运行中  /*不填则返回所有*/ 枚举值: INITIAL  SUCCESS  FAIL  RUNNING  DUPLICATE  INVALID  ERROR  INTERRUPT
"triggerMethod": "FIX_TIME" //【非必填】触发方式:手动、定时  /*不填则返回所有*/ 枚举:MANUAL   FIX_TIME
}
参数名
参数值是否必填参数类型描述说明
workNamefdlDemoString【必填】任务名称
latesttrueBoolean【非必填】仅查询最近一次:是、否,不填则为否
startTime
String【非必填】开始时间,不填则为无限
finishTime
String【非必填】结束时间,不填则为无限
taskStatusSUCCESSString【非必填】运行状态:成功、失败、中断、运行中,不填则返回所有,枚举值: INITIAL SUCCESS FAIL RUNNING DUPLICATE INVALID ERROR INTERRUPT
triggerMethodFIX_TIMEString【非必填】触发方式:手动、定时,不填则返回所有,枚举:MANUAL FIX_TIME

响应示例:

1)成功

{
"status": 200,
"data": {
"executeIds": [
"40fc80c6-ac03-4943-b6d7-e79ff5cca581"
]
}
}
参数名
参数值参数类型描述说明
status200Integer
data
Object
data.executeIds40fc80c6-ac03-4943-b6d7-e79ff5cca581Array实例ID列表

2)失败

{
"status": 200,
"errorCode": "E8130031",
"errorMsg": "任务不存在,无法获取文件"
}
参数名
参数值参数类型描述说明
status200Integer
errorCodeE8130031String
errorMsg任务不存在,无法获取文件String

4.3 根据示例ID查询实例信息

基本信息:

接口URL:http://localhost:8080/webroot/decision/sp/client/api/fdl/record/{recordId}

认证方式:无需认证

请求类型:GET

请求参数:

路径参数及说明:

参数名
参数值是否必填
参数类型描述说明
recordId16f7f568-767f-4786-bb2c-5dbc64cfbcadString

响应示例:

1)成功:

{
"status": 200, //【非必填】运行状态:成功、失败、中断、运行中  /*不填则返回所有*/
"data": {
"recordId": "16f7f568-767f-4786-bb2c-5dbc64cfbcad", //实例ID
"taskId": "868478d9-a36d-481f-b42d-6074310c2829", //任务ID
"taskName": "fdlDemo", //任务名称
"taskPath": "任务列表/一级目录/fdlDemo", //任务目录
"status": "INTERRUPT", //实例运行状态
"startTime": 1690786927020, //实例运行开始时间
"finishTime": 1690786944299, //实例运行结束时间
"triggerMethod": "MANUAL", //实例触发方式
"triggerBy": "root" //实例触发人
}
}
参数名
参数值参数类型描述说明
status200Integer【非必填】运行状态:成功、失败、中断、运行中,不填则返回所有
data
Object
data.recordId16f7f568-767f-4786-bb2c-5dbc64cfbcadString

实例ID

实例ID即为运行记录ID

data.taskId868478d9-a36d-481f-b42d-6074310c2829String任务ID
data.taskNamefdlDemoString任务名称
data.taskPath任务列表/一级目录/fdlDemoString任务目录
data.statusINTERRUPTString实例运行状态
data.startTime1690786927020Integer实例运行开始时间
data.finishTime1690786944299Integer实例运行结束时间
data.triggerMethodMANUALString实例触发方式
data.triggerByrootString实例触发人

2)失败

{
"status": 200,
"errorCode": "E8130012",
"errorMsg": "can not find record by recordId"
}
参数名
参数值参数类型描述说明
status200Integer
errorCodeE8130011String
errorMsg用户没有权限String

3)无权限

{
"status": 200,
"errorCode": "E8130011",
"errorMsg": "用户没有权限"
}
参数名
参数值是否必填参数类型描述说明
status200Integer
errorCodeE8130011String
errorMsg用户没有权限String

4.4 基于任务ID运行任务

基本信息:

接口URL:http://localhost:8080/webroot/decision/sp/client/api/fdl/work/{workId}/execute

Content-Type:application/json

认证方式:无需认证

请求类型:POST

请求参数:

路径参数及说明:

参数名
参数值是否必填参数类型描述说明
workId868478d9-a36d-481f-b42d-6074310c2829String【必填】任务ID

Body 请求参数:

{
"params": {
"paramName": "paramValue" //【非必填】执行参数
}, //【非必填】执行参数
"waitForResponse": "true", //【非必填】等待任务运行完成再返回内容
"waitTime": 10000 //【非必填】等待时间 单位毫秒 缺省值 60000毫秒
}
参数名
参数值是否必填参数类型描述说明
params
Object【非必填】执行参数
params.paramNameparamValueString【非必填】执行参数
waitForResponsetrueString【非必填】等待任务运行完成再返回内容
waitTime10000String【非必填】等待时间 单位毫秒 缺省值 60000毫秒

响应示例:

1)成功

{
"status": 200,
"data": {
"recordId": "70aa0661-c626-4c55-bbba-e392624945fa", //运行实例ID
"status": "SUCCESS" //运行实例状态
}
}
参数名
参数值参数类型描述说明
status200Integer
data
Object
data.recordId70aa0661-c626-4c55-bbba-e392624945faString

运行实例ID

实例ID即为运行记录ID

data.statusSUCCESSString运行实例状态

2)失败

{
"status": 200,
"errorCode": "E8130051",
"errorMsg": "任务不存在,无法获取文件"
}
参数名
参数值参数类型描述说明
status200Integer
errorCodeE8130051String
errorMsg任务不存在,无法获取文件String

4.5 基于任务名运行任务

基本信息:

接口URL:http://localhost:8080/webroot/decision/sp/client/api/fdl/work/execute

Content-Type:application/json

认证方式:无需认证

请求类型:POST

请求参数:

Body请求参数:

{
"workName": "fdlDemo", //【必填】任务名称
"params": {
"paramName": "paramValue" //【非必填】执行参数
}, //【非必填】执行参数
"waitForResponse": "true", //【非必填】等待任务运行完成再返回内容
"waitTime": 10000 
}
参数名
参数值是否必填参数类型描述说明
workNamefdlDemoString【必填】任务名称
params
Object【非必填】执行参数
params.paramNameparamValueString【非必填】执行参数
waitForResponsetrueString【非必填】等待任务运行完成再返回内容
timeout10000String【非必填】等待时间 单位毫秒 缺省值 60000毫秒

响应示例:

1)成功

{
"status": 200, 
"data": {
"recordId": "e14169b9-328c-4b62-8a75-abc546f61d38", 
"status": "SUCCESS" 

}
参数名
参数值参数类型描述说明
status200Integer
data
Object
data.recordIde14169b9-328c-4b62-8a75-abc546f61d38String运行实例ID
data.statusSUCCESSString状态

2)失败

{
"status": 200, 
"errorCode": "E8130061", 
"errorMsg": "任务不存在,无法获取文件" 
}
参数名
参数值参数类型描述说明
status200Integer
errorCodeE8130061String
errorMsg任务不存在,无法获取文件String

4.6 基于任务ID终止运行中实例

  • 不会检查实例是否处于运行状态。

  • 请求成功不代表终止成功,终止有一定的延迟。

基本信息:

接口URL:http://localhost:8080/webroot/decision/sp/client/api/fdl/work/{workId}/terminate

认证方式:无需认证

请求类型:POST

请求参数:

路径参数及说明:

参数名
参数值是否必填参数类型描述说明
workId868478d9-a36d-481f-b42d-6074310c2829String【必填】任务ID

响应示例:

成功

{
"code": "200",
"message": "success"
}
参数名
参数值参数类型描述说明
code200String
messagesuccessString

4.7 基于任务名终止运行中实例

  • 不会检查实例是否处于运行状态。

  • 请求成功不代表终止成功,终止有一定的延迟。

基本信息:

接口URL:http://localhost:8080/webroot/decision/sp/client/api/fdl/work/terminate?workName=fdlDemo222

认证方式:无需认证

请求类型:POST

请求参数:

Query 请求参数:

参数名
参数值是否必填参数类型描述说明
workNamefdlDemo222String【必填】任务名称

响应示例:

1)成功

{
"code": "200",
"message": "success"
}
参数名
参数值参数类型描述说明
code200String
messagesuccessString

2)失败

{
"status": 200, 
"errorCode": "E8130089", 
"errorMsg": "任务不存在,无法获取文件" 
}
参数名
参数值参数类型描述说明
status200Integer
errorCodeE8130089String
errorMsg任务不存在,无法获取文件String

4.8 基于实例ID终止运行中实例

  • 不会检查实例是否处于运行状态。

  • 请求成功不代表终止成功,终止有一定的延迟。

基本信息:

接口URL:http://localhost:8080/webroot/decision/sp/client/api/fdl/records/terminate

Content-Type:application/json

认证方式:无需认证

请求类型:POST

请求参数:

Body 请求参数:

{
"executeIds": [
"16f7f568-767f-4786-bb2c-5dbc64cfbcad222"
] //【必填】运行实例ID
}
参数名
参数值是否必填参数类型描述说明
executeIds16f7f568-767f-4786-bb2c-5dbc64cfbcadArray【必填】运行实例ID