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

1.1 版本

1.2 应用场景

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

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

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

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

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

1.3 功能简介

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

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

2.1 安装插件

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

2.1.1 FR 中调用接口

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

若 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 种备选认证方式。使用者也可根据需求，自行增加新的认证方式。若采用开放平台提供的 client_id 和 secret 的方式认证，默认为超管用户。详情请参见：开放平台插件

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

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

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

3.1.2 示例一：AkSk直接认证

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

1）进入 FDL 工程，点击「管理系统>开放平台>应用管理>增加」，新建应用，备选认证选择「AkSk认证」。如下图所示：

注：FR、FDL为独立部署时，推荐使用AkSk直接认证、摘要签名认证。

2）点击新建应用右侧的编辑按钮，记住「应用ID」与「密钥」的值。如下图所示：

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

4）添加 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）进入 FDL 工程，点击「管理系统>开放平台>应用管理>增加」，新建应用，备选认证选择「摘要签名认证」。如下图所示：

注：FR、FDL为独立部署时，推荐使用AkSk直接认证、摘要签名认证。

2）点击新建应用右侧的编辑按钮，记住「应用ID」与「密钥」的值。如下图所示：

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

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

• 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 位的值。

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

5）添加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 语句调用接口。

FR 与 FDL 独立部署时，调用定时任务接口的 JS 语句示例说明可参见本章内容。

4.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.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));
        }
    }
);

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）点击「发送请求」按钮，可查看响应结果。