调用定时任务相关接口说明

1.1 版本

1.2 应用场景

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

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

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

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

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

1.3 功能简介

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

注：FDL 中支持被调用的接口说明请参见：定时任务相关接口介绍

2.1 安装插件

注：「开放平台-FineDataLink接口」插件、「FDL接口转发_EK」插件需要联系技术支持获取；「开放平台」插件在平台「插件管理」处搜索下载安装即可。

2.1.1 FR 中调用接口

FR 模板中若想调用定时任务的相关接口：

1）若 FR 与 FDL 集成部署，需要依次安装开放平台插件、开放平台-FineDataLink接口插件。

注：FineReport11.0 中已内置「开放平台」插件。

2）若 FR 与 FDL 为独立部署，存在跨域时，FDL 工程需要依次安装开放平台插件、开放平台-FineDataLink接口插件；FR 工程安装FDL接口转发_EK插件。

安装插件步骤请参见：安装插件

使用示例请参见：FR模板调用定时任务接口示例

注：更新「开放平台」插件时，要先禁用「开放平台-FineDataLink接口」插件。

2.1.2 其他情况

简道云或者其他外部系统调用接口时，FDL 工程需要依次安装开放平台插件、开放平台-FineDataLink接口插件。

2.2 插件注册

插件需要注册，具体步骤请参见：插件注册

2.3 插件安装成功后界面介绍

2.3.1 任务ID

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

2.3.2 实例ID

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

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

3.1 开放平台认证模式

3.1.1 说明

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

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

2）接口认证逻辑由「开放平台>应用」管控，可参见 开放平台插件 认证方式介绍。例如选择 aksk 认证模式，在接口请求时需传递 client_id 和 secret 参数。具体使用示例请参见：FR模板调用定时任务接口示例

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

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

3.1.2 示例一：AkSk直接认证

展示在 postman 中如何调用 基于任务ID运行任务接口 

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

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

3）添加 client_id 和 secret 参数。接口最终为：

http://localhost:8068/webroot/decision/sp/client/api/fdl/workId/execute?client_id=fe45a247c7e54078babddb230128816b&secret=f3ea557912804f79838f1d1329712992

注1：请将上面接口中的「localhost:8068」替换成实际 FDL 工程的 IP 和端口；client_id 和 secret 的值根据实际情况填写。

注2：若接口中 body 内参数都为非必填，用户想设置 body 内容为空时，body 处填{}

响应结果如下图所示：

3.1.3 示例二：摘要签名认证

展示在 postman 中如何调用 基于任务ID运行任务接口 

摘要签名认证详细说明请参见：开放平台插件 3.3.2 节内容。

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

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

3）摘要签名认证需要两个参数：

• client_id={应用ID}。

• _sign_=摘要算法(应用ID+密钥+时间戳)+时间戳（毫秒）；可使用摘要演算法（比如 SM3/MD5/ SHA256），对应用ID、密钥以及时间戳进行签名。

本节示例摘要算法选择MD5，所以设置 method=MD5，timeout=300，timeout 为超时时间，单位是秒。如下图所示：

若选择其他算法，需修改 method 值。

使用 MD5 算法加密应用ID+密钥+时间戳，时间戳为当前时间，只要调用接口时的时间，在时间戳+timeout内就行。

示例：_sign_=摘要算法(应用ID+密钥+时间戳)+时间戳（毫秒）=MD5（9473abade431474ea8caddd3f5a4fa86367e893574ed4a7990bcfbf4cda945711701760916282）+1701760916282=B61199EDE3A28DE94ACF488CAED5B89B1701760916282

MD5 结果为 32 位的值。

注：可在百度搜索在线加密工具。

4）添加client_id、_sign_参数。接口最终为：http://localhost:8068/webroot/decision/sp/client/api/fdl/workId/execute?client_id=9473abade431474ea8caddd3f5a4fa86&_sign_=B61199EDE3A28DE94ACF488CAED5B89B1701760916282注1：请将上面接口中的「localhost:8068」替换成实际 FDL 工程的 IP 和端口；client_id 和 _sign_ 的值根据实际情况填写。

注2：若接口中 body 内参数都为非必填，用户想设置 body 内容为空时，body 处填{}

响应结果如下图所示：

3.2 fine_auth_token 认证模式

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

3.2.1 说明

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

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

2）该认证模式下，接口操作用户为 fine_auth_token 中映射的用户，无法通过 decUser 参数修改。

3.2.2 示例

展示在 postman 中如何调用 基于任务ID运行任务接口 

1）接口说明

基于任务ID运行任务接口为：http://localhost:8080/webroot/decision/sp/client/api/fdl/workId/execute，要使用  fine_auth_token 的认证方式，需要加上module/路径，为：

http://localhost:8080/webroot/decision/sp/client/api/module/fdl/workId/execute

注：请将上面接口中的「localhost:8080」替换成实际集成部署工程的 IP 和端口。

2）获取 fine_auth_token

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

3）postman 中设置界面如下图所示：

注：若接口中 body 内参数都为非必填，用户想设置 body 内容为空时，body 处填{}

响应结果如下图所示：

FR 模板调用定时任务接口的示例请参见：FR模板调用定时任务接口示例

FR 中，通过在报表模板中添加 JS 语句调用接口。

4.1 FR与FDL独立部署

FR 与 FDL 独立部署时，调用定时任务接口的 JS 语句示例说明如下：

4.1.1 POST 请求

JS 代码示例：根据任务ID查询实例列表：

FR.GetWorkRecordsByWorkId(
    {
        workId: "e10f1f1a-d567-4058-98bb-b71204154f8b",
        latest: false,
        startTime: "",
        finishTime: "",
        taskStatus: "SUCCESS",
        triggerMethod: "MANUAL",
    },
    function (error, response) {
        if (error) {
            console.error("请求失败：" + error);
        } else {
            console.log("请求成功，响应数据：" + JSON.stringify(response));
        }
    }
);

不同调用接口对应的 JS 说明如下：

JS 调用不同的接口时，上述 JS 示例代码如何修改说明如下：

注1：下图绿色部分的内容为 被调用定时任务接口 中的「body 请求参数」或「Query 请求参数」（「Query 请求参数」内容需要加双引号""）；紫色内容在不同定时任务的调用接口中不用修改。

注2：下图绿色部分为「Query 请求参数」示例："01数据同步"，与下图紫色部分用,隔开。

4.1.2 GET 请求

JS 示例：根据实例ID查询实例信息

FR.GetRecordInfoByRecordId(
    "3c73b3a0-30ba-4044-984e-6b61e5c3b638",
    function (error, response) {
        if (error) {
            console.error("请求失败：" + error);
        } else {
            console.log("请求成功，响应数据：" + JSON.stringify(response));
        }
    }
);

4.2 FR 与 FDL 集成部署

4.2.1 POST 请求

JS 示例：基于任务名运行任务：

function getCookie(name) {
let arr, reg = new RegExp("(^| )" + name + "=([^;]*)(;|$)");
if (arr = document.cookie.match(reg)) {
return decodeURI(arr[2]);
}
return null;
}
// 定义API的URL和access_token
 
var server = 'http://localhost:8075/webroot/decision';
var apiUrl = server+'/sp/client/api/module/fdl/workName/execute';
var accesstoken = getCookie('fine_auth_token'); // 获取令牌
// 构建请求数据
const requestData = {
"workName": "test",
"params": {
"paramName": ""
},
"waitForResponse": "true",
"waitTime": 10000
};
 
// 发起POST请求
fetch(apiUrl, {
method: 'POST',
headers: {
Authorization: 'Bearer '+accesstoken,
'Content-Type': 'application/json',
},
body: JSON.stringify(requestData),
})
.then(function(response) {
if (response.ok) {
return response.json();
} else {
throw new Error(`请求失败：${response.status}`);
}
})
.then(function(data) {
console.log(data); // 在控制台中输出响应数据
})
.catch(function(error) {
console.log(`请求失败：${error}`);
});

不同调用接口对应的 JS 说明如下：

JS 调用不同的接口时，上述 JS 示例代码如何修改说明如下：

1）若 定时任务接口 包含「body 请求参数」，根据本节「基于任务名运行任务」的 JS 示例代码，不同定时任务接口按照下图所示修改代码即可。

2）若定时任务接口包含「Query 请求参数」，根据本节「基于任务名运行任务」的 JS 示例代码，不同定时任务接口按照下图所示修改代码即可。

上图绿色部分代码修改为：

先初始化「Query 请求参数」的值，接口再调用该值。

例如「基于任务名终止运行中实例」，绿色部分修改为：

var workName = '任务'
var apiUrl = server+'/sp/client/api/module/fdl/workName/terminate?workName='+workName;

4.2.2 GET 请求

JS 示例：根据实例ID查询实例信息

function getCookie(name) {
let arr, reg = new RegExp("(^| )" + name + "=([^;]*)(;|$)");
if (arr = document.cookie.match(reg)) {
return decodeURI(arr[2]);
}
return null;
}
// 定义API的URL和access_token
 
var recordId = 'ae5c1ca8-3293-41cc-846b-c51951104b6b';
var server = 'http://localhost:8075/webroot/decision';
var apiUrl = server+'/sp/client/api/module/fdl/record/'+recordId;
var accesstoken = getCookie('fine_auth_token'); // 获取令牌
  
// 发起GET请求
fetch(apiUrl, {
    method: 'GET',
    headers: {
        Authorization: 'Bearer '+accesstoken,
        'Content-Type': 'application/json',
    },
})
.then(function (response) {
    if (response.ok) {
        return response.json();
    } else {
        throw new Error(`请求失败：${response.status}`);
    }
})
.then(function (data) {
    console.log(data); // 在控制台中输出响应数据
})
.catch(function (error) {
    console.log(`请求失败：${error}`);
});

5.1 使用须知

1）简道云支持调用以下接口：

2）需使用开放平台认证模式，请参见本文 3.1 节内容。

3）需要依次安装开放平台插件、开放平台-FineDataLink接口插件。

4）上述接口一般在 简道云前端事件 中调用。

5.2 调用示例

本节示例：简道云调用 根据任务ID查询实例列表 接口。

1）在 FDL 工程中新建应用、为新建应用开放权限。请参见 FR模板调用定时任务接口示例 文档的 2.2、2.3节内容。

2）进入简道云表单的编辑界面，添加前端事件。如下图所示：

3）对前端事件进行设置，填写或编辑「课时金额」时，调用接口，最后点击「执行动作」。如下图所示：

4）设置接口信息。本节示例被调用的接口请求类型为 POST，接口信息可在 根据任务ID查询实例列表 中查看。Header/Body 中添加client_id、secret参数。该接口的 Body 请求参数中，workId 参数为必填，本节示例只填 workId 参数。

如下图所示：

5）点击「发送请求」按钮，可查看响应结果。