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

1.1 版本

FDL 與相關插件最新的版本適配要求：

注：登入 FDL 工程，點選「管理系統>註冊管理」，可在「版本資訊」Tab 中查看平台模組版本。

1.2 應用場景

使用者希望能夠按需觸發/執行定時任務，以提高資料時效性，場景如下所示：

• 業務人員在 FR 填報頁面錄入資料後，資料需要經 FDL 的定時任務計算形成結果資料，期望能夠即時看到最新的資料。

• 業務人員期望能夠在報表上看到即時資料，或者有個按鈕能夠觸發資料更新。

• 企業自建或採購的業務系統，期望能夠在某些動作完成後觸發定時任務執行，使資料的更新時效性更高。

• 業務人員在簡道雲錄入資料後，資料需要經 FDL 的定時任務做同步或處理，期望能夠即時看到最新的資料。

1.3 功能簡介

使用「開放平台-FineDataLinkAPI」插件，可提供 FineDataLink 相關API，滿足使用者按需觸發/執行定時任務的需求。

注：FDL 中支援被呼叫的API說明請參見：定時任務相關API介紹

2.1 安裝插件

注：「開放平台-FineDataLinkAPI」插件、「FDLAPI轉發_EK」插件需要聯絡技術支援獲取；「開放平台」插件在平台「插件管理」處搜尋下載安裝即可。

2.1.1 FR 中呼叫API

FR 範本中若想呼叫定時任務的相關API：

若 FR 與 FDL 為獨立部署，存在跨域時，FDL 工程需要依次安裝開放平台插件、開放平台-FineDataLinkAPI插件；FR 工程安裝FDLAPI轉發_EK插件。

安裝插件步驟請參見：安裝插件

使用範例請參見：FR範本呼叫定時任務API範例

注：更新「開放平台」插件時，要先禁用「開放平台-FineDataLinkAPI」插件。

2.1.2 其他情況

簡道雲或者其他外部系統呼叫API時，FDL 工程需要依次安裝開放平台插件、開放平台-FineDataLinkAPI插件。

提示:

若出現重裝/升級/順序裝反了/重新註冊等情況，將導致插件類載入順序出錯，插件將無法正常使用，此時建議重啟 FineDataLink 工程，若仍無法正常使用插件功能，建議卸載插件，再按照順序重新安裝。

2.2 插件註冊

插件需要註冊，具體步驟請聯絡技術支援。

2.3 插件安裝成功後介面介紹

2.3.1 任務ID

插件安裝成功後，「資料開發」處展示的定時任務新增「任務ID」資訊，且支援複製。如下圖所示：

2.3.2 實體ID

點選「管理系統>任務維運>運作記錄」，可查看運作記錄ID（實體ID），滑鼠懸停支援複製。如下圖所示：

2.3.3 API管理

點選「管理系統>開放平台>API管理」，介面如下圖所示：

FDL擴展API和FDL擴展API（平台登入認證）Tab包含的API相同，差別是呼叫時 API 路徑不同。

這兩個Tab使用者無需特別關心，API的認證及使用步驟已在本文第三章說明，查看本文第三章即可。

• FDL擴展API：認證可選擇國密SM2簽章認證、AKSK直接認證、摘要簽章認證，使用方法請參見本文 3.1 節內容。

• FDL擴展API（平台登入認證）：為平台登入認證（fine_auth_token 認證方式），本文 3.2 節已說明使用方法

API觸發的任務，被定義為手動觸發，操作使用者和認證方式有關。

3.1 開放平台認證模式

3.1.1 說明

注：適用於獨立部署工程，建議使用AkSk直接認證、摘要簽章認證。

1）平台內建了 3 種備選認證方式。使用者也可根據需求，自行增加新的認證方式。若採用開放平台提供的 client_id 和 secret 的方式認證，預設為超管使用者。詳情請參見：開放平台插件

2）API認證邏輯由「開放平台>應用」管控，可參見 開放平台插件 認證方式介紹。例如選擇 aksk 認證模式，在API請求時需傳遞 client_id 和 secret 參數。具體使用範例請參見：

FR範本呼叫定時任務API範例

3）透過開放平台認證後，API的操作使用者預設為超管使用者。

4）當需要修改操作使用者時，可在 header 或 query 中新增 decUser 參數，參數值為帳號或使用者id。

3.1.2 範例一：AkSk直接認證

展示在 postman 中如何呼叫 基於任務ID運作任務API 

1）進入 FDL 工程，點選「管理系統>開放平台>應用管理>增加」，建立應用，備選認證選擇「AkSk認證」。如下圖所示：

注：FR、FDL為獨立部署時，推薦使用AkSk直接認證、摘要簽章認證。

2）點選建立應用右側的編輯按鈕，記住「應用ID」與「金鑰」的值。如下圖所示：

3）點選「權限管理>API」，本次範例選定API為「基於任務ID運作任務」，為其開放上面建立應用的權限。如下圖所示：

4）新增 client_id 和 secret 參數。API最終為：

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

注1：請將上面API中的「localhost:8068」取代成實際 FDL 工程的 IP 和埠；client_id 和 secret 的值根據實際情況填寫。

注2：若API中 body 內參數都為非必填，使用者想設定 body 內容為空時，body 處填{}

回應結果如下圖所示：

3.1.3 範例二：摘要簽章認證

展示在 postman 中如何呼叫 基於任務ID運作任務API 

摘要簽章認證詳細說明請參見：開放平台插件 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+金鑰+時間戳，時間戳為當前時間，只要呼叫API時的時間，在時間戳+timeout內就行。

範例：_sign_=摘要算法(應用ID+金鑰+時間戳)+時間戳（毫秒）=MD5（9473abade431474ea8caddd3f5a4fa86367e893574ed4a7990bcfbf4cda945711701760916282）+1701760916282=B61199EDE3A28DE94ACF488CAED5B89B1701760916282

MD5 結果為 32 位的值。

注：可在百度搜尋線上加密工具。

5）新增client_id、_sign_參數。API最終為：http://localhost:8068/webroot/decision/sp/client/api/fdl/workId/execute?client_id=9473abade431474ea8caddd3f5a4fa86&_sign_=B61199EDE3A28DE94ACF488CAED5B89B1701760916282注1：請將上面API中的「localhost:8068」取代成實際 FDL 工程的 IP 和埠；client_id 和 _sign_ 的值根據實際情況填寫。

注2：若API中 body 內參數都為非必填，使用者想設定 body 內容為空時，body 處填{}

回應結果如下圖所示：

3.2 fine_auth_token 認證模式

注：適用於整合部署工程，為產品內建登入認證。

3.2.1 說明

若採用和平台一樣的 fine_auth_token 的認證方式，採用的就是生成 token 的使用者去操作。詳情請參見：開放平台子插件

1）在請求地址中新增上module/路徑時（例如，原始為 /sp/client/api/*，新增後變為/sp/client/api/module/*），API認證邏輯不再由「開放平台>應用」來管控，而是需要攜帶帆軟平台的認證登入標識 fine_auth_token，未攜帶或攜帶無效 token 時API認證失敗。

2）該認證模式下，API操作使用者為 fine_auth_token 中映射的使用者，無法透過 decUser 參數修改。

3.2.2 範例

展示在 postman 中如何呼叫 基於任務ID運作任務API 

1）API說明

基於任務ID運作任務API為：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

注：請將上面API中的「localhost:8080」取代成實際整合部署工程的 IP 和埠。

2）獲取 fine_auth_token

使用者登入 FineDataLink 系統，F12，在「Network>Headers」下，獲取fine_auth_token的值。如下圖所示：

注：下圖給出的方法獲取的 fine_auth_token 值，存在有效期；使用者可呼叫 前台單點登入API API（API傳回結果中 accessToken 值為 fine_auth_token 值），每次獲取最新的 fine_auth_token 值。

3）postman 中設定介面如下圖所示：

注：若API中 body 內參數都為非必填，使用者想設定 body 內容為空時，body 處填{}

回應結果如下圖所示：

FR 範本呼叫定時任務API的範例請參見：FR範本呼叫定時任務API範例

FR 中，透過在報表範本中新增 JS 語句呼叫API。

FR 與 FDL 獨立部署時，呼叫定時任務API的 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));
        }
    }
);
顯示程式碼

不同呼叫API對應的 JS 說明如下：

JS 呼叫不同的API時，上述 JS 範例程式碼如何修改說明如下：

注1：下圖綠色部分的內容為 被呼叫定時任務API 中的「body 請求參數」或「Query 請求參數」（「Query 請求參數」內容需要加雙引號""）；紫色內容在不同定時任務的呼叫API中不用修改。

注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）簡道雲支援呼叫以下API：

2）需使用開放平台認證模式，請參見本文 3.1 節內容。

3）需要依次安裝開放平台插件、開放平台-FineDataLinkAPI插件。

4）上述API一般在 簡道雲前端事件 中呼叫。

5.2 呼叫範例

請參見文檔：簡道雲表單呼叫定時任務API範例