1. 概述
1.1 版本
| FineDataLink版本 | 功能變動 |
|---|---|
| 4.0.20.1 | 支援的API發布的資料庫版本：MySQL、Oracle、PostgreSQL、SQLServer、Greenplum（包含並行裝載） |
| 4.2.16.2 |
|
| 4.2.16.4 | 背景說明： 舊版本升級到 4.2.6.2-4.2.16.3 版本，若升級前API為 POST 請求方式&& Body 格式為 application/json&&自訂參數為多個，升級後若再編輯儲存該API，呼叫該API時傳參的順序不能變，否則參數傳入會錯位 本版本優化點：
|
查看曆史版本更新：曆史版本
1.2 應用場景
企業安全規範要求，不允許直連業務庫，程式碼開發API效率低，人工傳輸易出錯。
缺乏安全的資料共享機制，隨着資料消費端增加，IT 出現重複造輪子的傾向。
1.3 功能說明
FineDataLink 支援將資料庫資料、儲存程式以 API API形式發布，便於其他系統或工具呼叫。
2. 約束限制
1）使用「資料服務」的前提條件和其他約束限制請參見：資料服務概述
2）若使用 Doris、StarRocks、impala 作為發布的資料源，需要指定有效的排序欄位，否則將無法正常分頁，影響後續使用API取數。
| 方案 | 步驟 |
|---|---|
方案一：使用 ORDER BY 語句指定有效的排序欄位 4.2.6.2 及之後版本，若開啟「分頁查詢」按鈕（傳回資料實現分頁效果），需要做此操作 |
|
方案二：4.2.0.3 及之後版本，可設定回傳值排序 4.2.6.2 及之後版本，若開啟「分頁查詢」按鈕（傳回資料實現分頁效果），需要做此操作 |  |
3. 操作步驟
建立一個 API 後，需要 2 步完成該 API 的設計：服務內容（資料查詢）、APIAPI配置。
3.1 建立 API
進入 FDL 工程，點選「資料服務」，在有權限的路徑下建立API服務，設定 API 所在路徑及名稱後，點選「確定」按鈕。如下圖所示：
各設定項介紹如下表所示：
| 設定項 | 說明 |
|---|---|
| 所屬目錄 | 支援修改 |
| 名稱 | 配置 API 名稱 API 名稱不能重名，不能為空 預設為空，最大長度 50 字元，必填 |
| 描述 | 配置 API 描述 預設為空，最大長度 100 字元，非必填 |
3.2 服務內容（資料查詢）
3.2.1 配置方式
「配置方式」設定項中可選擇SQL、選表（4.1.3 版本新增）、存儲程式（4.2.12.2 版本新增）。
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 |
| 資料過濾 |
|
| 設定項 | 說明 |
|---|---|
| 資料連結 | 當資料庫類型為 MySQL、Oracle、SQLServe 時，配置方式支援選擇儲存過程 注：資料連結使用者需要有待呼叫儲存程式的查詢、執行權限，不同資料庫設定方法可能不同，具體可自行百度 |
| 選擇儲存程式 | 單選已存在的儲存程式；所選擇的儲存程式，需要有傳回結果集 |
| SQL語句預覽 | 點選後，可查看儲存程式的SQL語句，僅支援預覽，不支援修改 |
| 參數名稱、參數類型、參數方向 | 1）可預覽儲存程式中存在的輸入參數，參數名稱、參數類型、參數方向不支援修改 2）修改參數除錯值入口（下面兩處任一一端數值改變，另一端保持同步）：
參數除錯值不支援引用參數 |
| 傳回結果集&指定結果集 | 1）選擇儲存程式後，「傳回結果集」中自動展示結果集類型：查詢結果集、游標結果集 2）當結果集類型為「查詢結果集」時，可在「指定結果集」中點選「選擇」按鈕，預覽結果集資料並選中結果集 注：若某個結果集預覽失敗，禁止選中
2）當結果集類型為「游標結果集」時，須「選擇游標」。游標預設選擇儲存程式中的第一個游標 3）MySQL、SQLServer 只支援查詢結果集；Oracle 只支援游標結果集，限制為 out 中的 resultset 類型的結果集 |
3.3.2 回傳值排序
回傳值配置中點選「配置」按鈕後，支援指定排序欄位和排序規則。
說明如下：
1）應用場景：
資料服務 API 發布的API，使用者呼叫時（比如分頁取數時），希望取出或預覽的資料根據某個欄位有序排列。
2）功能疊代說明：
| 版本 | 說明 |
|---|---|
| 4.2.0.3 | 1）配置方式為 SQL 時，Greenplum、YMatrix、GaussDB 資料源，支援指定欄位排序 2）配置方式為選表時，所有資料源均支援指定欄位排序 |
| 4.2.6.1 | 配置方式為 SQL 時，AnalyticDB MySQL 支援欄位排序功能 |
| 4.2.6.2 | 配置方式為 SQL、選表：任意資料庫都支援欄位排序功能 |
| 4.2.9.1 | 1）資料源為 Doris、StarRocks、Impala 時，若開啟了分頁取數，會提示：為確定正常分頁，請指定有效的排序欄位 2）資料源為 GreenPlum、YMatrix、GaussDB 200、TiDB、AnalyticDB MySQL、TRANSWARP INCEPTOR、KingbaseES（MySQL）、KingbaseES（Oracle）、Cache 時，若開啟了分頁取數，必須配置回傳值排序 |
3）可指定單個欄位作為排序欄位；也可指定多個欄位作為組合排序欄位（需要區分排序優先）。
4）排序規則可選擇：升冪、降冪，預設為升冪。
5）生效方式：排序欄位勾選後，點選「重新整理並預覽」/「下一步」即觸發生效。若修改後，也是「重新整理並預覽」/「下一步」重新生效。
3.2.3 單次請求量
4.2.6.2 及之後版本支援該功能。
可控制單次請求資料量。
預設值為 10000，可修改，上限為100000 條；範例：單次請求量設定為 10 ，實際取數單次有 12 條，呼叫 API 後，只能取出 10 條。
3.2.4 分頁查詢
4.2.6.2 及之後版本支援該功能。
1）預設開啟，可以關閉：
| 按鈕是否開啟 | 應用場景 | 效果 |
|---|---|---|
| 開啟 | 在查詢傳回的資料總量比較大的情況下，建議分頁（多次取完所有資料）；可以提高資料庫查詢效率、降低資料服務記憶體佔用、確定傳回 Body 大小在安全範圍內 | 呼叫生成的 API 後傳回資料可實現分頁的效果 |
| 不開啟 | 在查詢傳回的資料總量比較小的情況下，可以不分頁（一次取完所有資料），這樣可以減少取數次數，比較簡單 | 呼叫生成的 API 後，傳回資料不分頁 |
2）開啟「分頁查詢」按鈕後，會自動生成 3 個參數：pageNum、pageSize、returnTotalNum，自動匯出 4 個傳回變數：totalNum、pageSize、pageNum、rowCount。
參數說明如下表所示：
若「分頁查詢」按鈕開啟&參數設定為必填，其他系統或工具呼叫生成的 API 時，需要填入這些參數。
呼叫 API 時使用參數範例：
| 參數 | 類型 | 參數必填按鈕 | 預設值 |
|---|---|---|---|
| pageNum（頁編號） | 數值 | 預設開啟 | 當「參數必填按鈕」關閉時，可配置預設值
|
| pageSize（單頁大小） | 數值 | 預設開啟 | 當「參數必填按鈕」關閉時，可配置預設值 |
| returnTotalNum（是否傳回總數） | 布爾 | 預設關閉（可開啟） | 預設值為 true 當「參數必填按鈕」關閉時，可配置預設值 |
傳回變數說明如下表所示：
其他系統或工具呼叫生成的 API 時，傳回的資料中會包含傳回變數資料。
呼叫 API 後參數傳回範例：
| 參數 | 類型 | 說明 |
|---|---|---|
| totalNum | 數值 | 傳回取出資料的總資料條數，當請求參數 returnTotalNum 的值為ture時傳回資料，否則值為空 |
| pageSize | 數值 | 傳回取出資料的每頁資料條數 |
| pageNum | 數值 | 資料頁數，即從第幾頁開始取 |
| rowCount | 數值 | 當前頁數包含的資料條數 與 pageNum 頁數有關。比如一共12筆資料，傳入的pageNum是2，pageSize是10。實際會查詢第二頁的資料，實際傳回2 |
3.2.5 參數和變數
若「配置方式」（本文 3.2.1 節）步驟中，設定了參數，「服務入參」中自動顯示設定的參數。如下圖所示：
| 設定項 | 說明 |
|---|---|
| 參數名 | 請求參數名 參數名稱不可重名 預設為空，必填 |
| 參數類型 | 請求參數類型。
注：對於日期類型參數標識為字串，使用字串形式傳入，格式舉例：【yyyy-MM-dd HH:mm:ss】 |
| 除錯值 | 點選「資料預覽」時填入的參數值 4.2.16.1 及之後版本，除錯值可選擇：自訂、NULL值
|
| 參數必填 | 配置當前參數是否必填 如果沒有勾選必填，則要求預設值配置項不能為空 |
| 預設值 | 參數非必填時做非空校驗 配置當前參數的預設值，參數配置為「非必填」時需要填寫預設值 當參數配置非必填，沒有傳參的情況下：取預設值作為參數值，預設值可以是對應類型的任何值，預設值可以為NULL 注：參數是否必填，是針對實際API呼叫傳參程式的，在進行預覽和測試時，參數還是必須填完整 |
| 描述 | 為參數新增描述 預設為空 |
3.2.6 傳回變數
其他系統或工具呼叫生成的 API 時，傳回的資料中會包含傳回變數資料。
| 參數 | 說明 | 範例 |
|---|---|---|
| code | 流程運作結果的程式碼 | |
| message | 流程運作結果的資訊匯出 | |
| output | 其他系統或工具呼叫生成的 API 後，取出的資料（建議勾選「對外匯出」按鈕） | |
| 配置按鈕 | 4.2.8.4 及之後版本，output 陣列支援為展開的內部欄位新增備注 點選「配置」按鈕，可展開陣列內部欄位，為欄位新增備注。如下圖所示： 注：會預設讀取欄位的已有注釋；新增的注釋將隨「匯出API文檔」一同匯出。
| |
3.3 API API配置
3.3.1 基礎屬性
各設定項說明如下表所示：
| 設定項 | 說明 |
|---|---|
| 請求方式 | 當前支援 POST、GET POST 透過 Body 傳入參數，GET 透過 URL 傳入參數（QueryParam） 傳入參數 QueryParam 時的參數說明如下：
|
| API路徑 | 配置要發布的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 若想被呼叫必須綁定應用 1）使用者可在建立API時將其新增到某個應用上 點選「新增」按鈕，可將 API 綁定到已有應用上；4.2.16.2 及之後版本，點選「新增」按鈕後，可再點選「去建立」按鈕建立應用，將該 API 綁定在建立應用上
2）或者建立 API 後，在應用列表Tab下，將 API 綁定在應用上 具體說明請參見：綁定API至應用 3）4.2.16.2 及之後版本，綁定應用後，新增「存取路徑」欄位，可複制完整存取路徑
|
3.3.2 請求參數
1）請求 Body 格式說明：
請求方式選擇 POST 時展示。
選擇請求的 Body 格式（其實就是請求Content-Type）：
application/json 不能處理帶有編碼格式的Content-Type，例如application/json; charset=UTF-8
application/x-www-form-urlencoded
預設選擇「application/json」。
2）不同場景說明：
其他系統或工具呼叫生成的 API 時，需要輸入請求參數；請求參數根據 3.2.5 節中「服務入參」的變動而變動。
對於必填的「服務入參」（3.2.5 節）中的參數，若不被綁定，則除錯和運作時報錯。
| 場景 | 說明 | |
|---|---|---|
| 請求方式為POST | 請求Body格式為 application/x-www-form-urlencoded |
支援修改參數名 |
| 請求Body格式為 application/json |
1）自動生成 JSON 格式，允許使用者調整（邏輯參考JSON生成，允許新增多個子陣列） 2）點選「快捷生成」按鈕，下拉框中可選擇自動生成、按JSON範本生成，詳細說明請參見：JSON生成 文檔 3）4.2.16.4 及之後版本，新增「自訂JSONPath」按鈕
應用場景：詳情請參見本文第四章內容說明 | |
| 請求方式為GET | - |
支援修改參數名 |
3.3.3 API回應
1）展示呼叫 API 後傳回的資料格式（JSON 格式）。
2）反映異常資訊按鈕（4.2.8.4 版本新增）：
勾選：API異常資訊將反映在 HTTP 狀態碼上。
不勾選：HTTP 狀態碼僅傳回 200 或 404。
3）支援使用者自動調整傳回的資料格式；點選「快捷生成」按鈕，下拉框中可選擇自動生成、按JSON範本生成，詳細說明請參見：JSON生成 文檔。
4）輸入 Body 測試值或者 Params 測試值進行API除錯，測試呼叫情況。如下圖所示：
5）4.2.8.4 及之後版本，陣列類型的變數，新增「詳情」按鈕，可查看陣列所包含欄位的注釋。如下圖所示：
3.4 API 上線
點選「儲存」按鈕或者「儲存聯集線」按鈕生成 API。
若配置不完整，點選「儲存聯集線」按鈕將報錯，但可以點選「儲存」按鈕儲存已有配置。
4.2.6.2 及之後版本，新增「測試呼叫」按鈕，無論 API 是否上下線，都支援除錯操作；若 API 配置不完整，該按鈕不可用。
4.2.16.2 及之後版本，綁定應用處，可：將 API 綁定到其他應用上、顯示且可複制完整存取路徑、解綁應用、修改授權有效期；同時，顯示最近編輯時間。
3.5 綁定 API 至應用
API 若想被呼叫必須綁定應用。
使用者可在本文 3.2 節步驟中給 API 綁定應用，或者 3.4 節結束後，參考 綁定API至應用 給 API 綁定應用。
3.6 呼叫 API
1）API 發布後，呼叫說明文檔請參見：
使用資料服務發布的API（POST application/json請求）
使用資料服務發布的API（POST x-www-form-urlencoded請求）
2）完整的 API 路徑獲取方式：
4. 擴展閱讀
| 分類 | 說明 | 參考文檔 |
|---|---|---|
發佈 API 注：4.1.6.3 及之後版本，API任務、資料服務應用禁止被多人同時編輯。詳情請參見：任務禁止被多人同時編輯 | 資料服務支援使用簡單身分認證及加密身分認證呼叫資料服務API，可根據需要選擇 | 摘要簽章認證方式 |
| 外部系統呼叫時開通黑白名單，可保證發佈的 API API在被外部系統呼叫時更安全 | 配置API黑白名單 | |
| 發佈包含參數的 API | ||
| 使用發佈的 API | API 發佈後，使用範例 | |
| 對已經發布的 API 進行管理 | 對發佈的 API 進行任務管理、運作監視和任務監視，查看呼叫情況、批量上下線 API 等 | 資料服務維運 |
| 資料服務最佳實踐 | 某公司旗下各個地區有多個分公司和分店，且使用的同一套業務系統 業務資料會全部匯總到總部的資料庫內，分店只能在業務系統上看到特定的分析和資料，無法實現自訂分析 總部希望對資料進行分權限管控：總部按照地區提供資料，一個地區分店和分公司只能看到自己地區的資料，不允許看到其他地區的資料，各地區自行獲取資料後在不同工具中進行資料分析和使用 | 使用資料服務對資料進行分發管控 |
| 使用者希望將 FineBI 中的資料發佈為 API ，供其他系統使用 | 使用FineBI公共資料發佈API |
上一篇：資料查詢API概述
