1. 概述
1.1 版本
| FineDataLink版本 | 功能變動 |
|---|---|
| 4.0.20.1 | 支援的API發布的資料庫版本：MySQL、Oracle、PostgreSQL、SQLServer、Greenplum（包含並行裝載） |
| 4.2.9.1 | 1）資料源為 Doris、StarRocks、Impala 時，若開啟了分頁取數，會提示：為確定正常分頁，請指定有效的排序欄位 2）資料源為 GreenPlum、YMatrix、GaussDB 200、TiDB、AnalyticDB MySQL、TRANSWARP INCEPTOR、KingbaseES（MySQL）、KingbaseES（Oracle）、Cache 時，若開啟了分頁取數，必須配置回傳值排序 |
| 4.2.12.2 | 支援 Informix 資料源 支援呼叫資料庫中的儲存程式進行取數 |
1.2 歷史版本
| FineDataLink 版本 | 功能變動 |
|---|---|
| 4.0.26 | 非超級管理者支援使用資料服務 |
| 4.1 |
|
| 4.1.2 | 支援 StarRocks、GaussDB、MaxCompute 資料源 注：StarRocks 在作為資料源時，需要使用 ORDER BY 語句指定有效的排序欄位，否則將無法正常分頁，影響後續使用API取數 |
| 4.1.3 | 支援直接選表同步數據 支援 DB2 資料源 |
| 4.1.5.4 | 「發布內容及參數」步驟中，配置方式選擇「選表」時，顯示表備注 |
| 4.1.6.1 | API管理、呼叫記錄Tab，被挪到「任務維運>資料服務」下 |
| 4.1.6.3 | 支援 GBase8s、KingbaseES、ClickHouse、HANA、達夢、Vertica 資料源 API任務、資料服務應用禁止被多人同時編輯 |
| 4.1.6.4 | |
| 4.1.8.2 | 資料服務支援讀取神通資料庫 |
| 4.1.11.5 | 配置方式選擇「選表」時，若選擇了指定資料表，介面展示表所在資料庫或者模式 |
| 4.1.13.2 | 配置方式為「選表」時，支援選欄位 |
| 4.2.0.3 | 1）「發布內容及參數」步驟中，獲取回傳值後：
2）配置方式為 SQL 時，Greenplum、YMatrix、GaussDB 資料源，支援指定欄位排序 3）配置方式為選表時，所有資料源均支援指定欄位排序 |
| 4.2.4.3 | 建立資料服務與建立定時任務的交互統一 |
| 4.2.6.1 | AnalyticDB MySQL 資料源適配回傳值排序功能 |
| 4.2.6.2 | 1）「API列表」Tab名稱變更為「服務列表」；建立「API」變更為建立「API服務」 2）建立 API 步驟更新為 2 個：服務內容（資料查詢）、APIAPI配置 3）支援控制單次請求資料量 4）支援自訂開啟查詢分頁及對應的參數 5）支援自訂請求參數和傳回資料的資料結構 6）去掉「回傳值配置」設定項 7）只要 API 配置完整，上線狀態和下線狀態都支援除錯 8）配置方式為選表和 SQL ，所有資料庫都支援回傳值排序功能 |
| 4.2.8.4 | output 陣列支援為展開的內部欄位新增備注 API 詳情頁，支援查看陣列內部欄位名稱、欄位類型和欄位描述 「回傳值排序配置」設定項改名為「回傳值排序」 「流程變數」改名為「傳回變數」 APIAPI配置步驟中新增「HTTP狀態碼」設定項 |
1.3 應用場景
使用者需要把上游資料獲取、加工好以後，存到指定資料庫，希望將這些資料封閉性成 API API，供下游系統呼叫。
1.4 功能說明
FineDataLink 支援將處理好的資料庫中的資料透過 API 形式發佈出去，供其他工具使用。
2. 約束限制
1）使用「資料服務」的前提條件和其他約束限制請參見：資料服務概述
2）若使用 Doris、StarRocks、impala 作為發布的資料源，需要指定有效的排序欄位，否則將無法正常分頁，影響後續使用API取數。
| 方案 | 步驟 |
|---|---|
方案一：使用 ORDER BY 語句指定有效的排序欄位 4.2.6.2 及之後版本，若開啟「分頁查詢」按鈕（傳回資料實現分頁效果），需要做此操作 |
|
方案二：4.2.0.3 及之後版本，可設定回傳值排序 4.2.6.2 及之後版本，若開啟「分頁查詢」按鈕（傳回資料實現分頁效果），需要做此操作 |  |
3. 操作步驟
建立一個 API 後，需要 3 步完成該 API 的設計：API 資訊、發佈內容及參數、預覽測試。
3.1 建立 API
進入 FDL 工程，點選「資料服務」，在有權限的路徑下建立 API，設定 API 所在路徑及名稱後，點選「確定」按鈕。如下圖所示：
名稱不能重名，不能為空。
支援修改所屬目錄；描述可為空。
3.2 API 資訊
API的請求路徑、請求格式、傳回格式等基本資訊說明如下所示：
注：支援內容未配置完成時點選「儲存」按鈕。
配置項 | 說明 | |
|---|---|---|
| 名稱 | 配置API名稱。 API名稱不允許重複。 預設為空，最大長度50字元，必填。 | |
| 描述 | 配置API描述。 預設為空，最大長度100字元，非必填。 | |
| 請求方法 | 請求方法。 當前支援 POST、GET 。 POST透過BODY傳入參數，GET透過URL傳入參數（QueryParam） 傳入參數 QueryParam 時的參數說明如下：
| |
| 請求Body格式 | 請求方式選擇POST時展示 選擇請求的Body格式（其實就是請求Content-Type）：
預設選擇「application/json」。 | |
| 路徑 | 配置要發佈的API路徑。 API路徑不允許重複。 預設為空，支援指定英文、數字、底線（_）、連字元（-）、正斜槓（/）。 例如以下完整的API請求路徑範例： http://192.168.5.175:8089/webroot/service/publish/應用ID/demo 注1：service前的部分為發佈API所在的當前 FineDataLink 伺服器地址。 注2：應用ID是API被綁定應用的ID，詳情參見綁定API至應用。 | |
| 逾時時間 | 填寫回應逾時時間，如果在指定時間後仍沒有傳回查詢結果，則API傳回逾時錯誤。 預設10000ms，必填。 | |
| 已授權應用 | 使用者可在建立API時將其新增至授權應用，同時在API測試階段可直接測試API呼叫情況。 同時可以將 API 任務批量新增至多個有權限的應用下。 詳情請參見：綁定API至應用 API 若想被呼叫必須綁定應用 | |
3.3 發佈內容及參數
3.3.1 配置方式
「配置方式」設定項中可選擇SQL、選表。
注：4.1.3 及之後版本，新增「選表」功能，支援直接選表同步資料。
1）SQL
透過 SQL 語句從源資料庫的表中查詢取數，且支援引用參數，參數的具體介紹請參見：參數概述
使用者可選擇指定的資料庫，並在該資料庫下搜尋需要的資料表，然後寫入右側 SQL 輸入框，如下圖所示：
2）選表
| 設定項 | 說明 |
|---|---|
| 來源表 | 選擇來源表，不能為空 4.1.11.5 及之後的版本配置方式選擇「選表」時，若選擇了指定資料表，介面展示表所在資料庫或者模式 |
| 選部分欄位 | 4.1.13.2 及之後版本，支援選擇部分欄位： 1）選欄位時若全選欄位，後續該表新增的欄位，不會被當成選中的狀態 2）未選的表欄位，在「資料過濾」功能中，可被聯想出來 3）已被選擇的欄位，若希望取消選擇，有兩種方案：
4）「回傳值配置」中，僅展示已選的欄位 |
| 表描述 | 顯示表備注 不支援該功能的資料庫： ClickHouse、Hive、Impala、TRANSWARP INCEPTOR、Informix、MaxCompute、SQLite、StarRocks |
| 資料過濾 |
|
3.3.2 請求參數配置
請求參數配置說明如下：
列表專案 | 說明 |
|---|---|
| 參數名 | 請求參數名。 參數名稱不可重名。 預設為空，必填。 |
| 參數類型 | 請求參數類型。
注：對於日期類型參數標識為字串，使用字串形式傳入，格式舉例：【yyyy-MM-dd HH:mm:ss】 |
| 參數必填 | 配置當前參數是否必填。 如果沒有勾選必填，則要求預設值配置項不能為空。 |
| 預設值 | 參數非必填時做非空校驗 配置當前參數的預設值，參數配置為「非必填」時需要填寫預設值。 當參數配置非必填，沒有傳參的情況下：取預設值作為參數值，預設值可以是對應類型的任何值，預設值可以為NULL。 注：參數是否必填，是針對實際API呼叫傳參程式的，在進行預覽和測試時，參數還是必須填完整。 |
| 描述 | 為參數新增描述。 預設為空。 |
3.3.3 回傳值配置
注1：4.1.6.4 及之後版本，「查詢預覽」按鈕更新為「回傳值配置」。
注2：可不點選「獲取」按鈕獲取回傳值，不影響 API 的正常使用；但若不獲取，匯出的 API 文檔中，該 API 的傳回內容不完整。
若 SQL 語句中配置了參數：
1）「請求參數配置」中自動獲取參數，回傳值配置中點選「獲取」按鈕，獲取傳回參數。如下圖所示：
獲取的回傳值如下圖所示：
說明如下：
不允許修改欄位名和類型；支援為欄位新增描述。
欄位名支援搜尋。
點選「重新整理並預覽」按鈕，可重新獲取回傳值。
4.2.0.3 及之後版本：右鍵點選欄位值，出現複製按鈕，可複製欄位值；若欄位值過長，支援拖曳調整列寬；滑鼠懸浮欄位值上，顯示完整欄位值。
若 SQL 語句中未配置參數：
「請求參數配置」中提示：根據查詢SQL自動獲取；回傳值配置中點選「獲取」按鈕，獲取傳回參數。
3.3.4 回傳值排序
4.2.0.3 及之後版本，回傳值配置中點選「獲取」按鈕後，支援指定排序欄位和排序規則。
說明如下：
1）應用場景：
資料服務 API 發佈的API，使用者呼叫時（比如分頁取數時），希望取出或預覽的資料根據某個欄位有序排列。
2）配置方式為 SQL 時，Greenplum、YMatrix、GaussDB 資料源，支援指定欄位排序；配置方式為選表時，所有資料源均支援指定欄位排序。
3）可指定單個欄位作為排序欄位；也可指定多個欄位作為組合排序欄位（需要區分排序優先）。
4）排序規則可選擇：升冪、降冪，預設為升冪。
5）生效方式：排序欄位勾選後，點選「重新整理並預覽」/「下一步」即觸發生效。若修改後，也是「重新整理並預覽」/「下一步」重新生效。
3.4 預覽測試
可點選「儲存」按鈕或者「儲存聯集線」按鈕。
注：若配置不完整，點選「儲存聯集線」按鈕將報錯，但可以點選「儲存」按鈕儲存已有配置。
| 專案列表 | 說明 |
|---|---|
| 測試應用 | 選擇測試API呼叫時使用的應用 如果沒有綁定應用，則此配置灰化不可選 |
| 測試呼叫 | 輸入 Body 測試值或者 Params 測試值進行API除錯，測試呼叫情況 |
3.5 綁定 API 至應用
API 若想被呼叫必須綁定應用。
使用者可在本文 3.2 節步驟中給 API 綁定應用，或者 3.4 節結束後，參考 綁定API至應用 給 API 綁定應用。
3.6 API 上線
API 列表展示所有 API資訊，選擇指定的 API ，可查看基本資訊和 API 的內容以及參數。
在右上角點選「上線」，即可發佈 API，如下圖所示：
4. 擴展閱讀
| 分類 | 說明 | 參考文檔 |
|---|---|---|
發佈 API 注：4.1.6.3 及之後版本，API任務、資料服務應用禁止被多人同時編輯。詳情請參見：任務禁止被多人同時編輯 | 資料服務支援使用簡單身分認證及加密身分認證呼叫資料服務API，可根據需要選擇 | 摘要簽章認證方式 |
| 外部系統呼叫時開通黑白名單，可保證發佈的 API API在被外部系統呼叫時更安全 | 配置API黑白名單 | |
| 發佈包含參數的 API | ||
| 使用發佈的 API | API 發佈後，使用範例 | |
| 對已經發布的 API 進行管理 | 對發佈的 API 進行任務管理、運作監視和任務監視，查看呼叫情況、批量上下線 API 等 | 資料服務維運 |
| 資料服務最佳實踐 | 某公司旗下各個地區有多個分公司和分店，且使用的同一套業務系統 業務資料會全部匯總到總部的資料庫內，分店只能在業務系統上看到特定的分析和資料，無法實現自訂分析 總部希望對資料進行分權限管控：總部按照地區提供資料，一個地區分店和分公司只能看到自己地區的資料，不允許看到其他地區的資料，各地區自行獲取資料後在不同工具中進行資料分析和使用 | 使用資料服務對資料進行分發管控 |
| 使用者希望將 FineBI 中的資料發佈為 API ，供其他系統使用 | 使用FineBI公共資料發佈API |
