1. 概述
1.1 版本
| FineDataLink 版本 | 功能變動 |
|---|---|
| 4.2.8.4 | 支持發布數據接收 API ，供業務系統調用，向其他系統/數據庫寫入/更新數據 |
| 4.2.9.4 | 數據接收支持寫入 GaussDB 100 |
| 4.2.11.2 | 可以不部署 Kafka、配置傳輸隊列，提供内存隊列 |
| 4.2.12.2 | 支持爲解析後的字段設置字段類型 |
1.2 應用場景
使用者希望 FineDataLink 提供一個API，支援業務系統呼叫，向其他系統/資料庫寫入/更新資料。
1.3 功能簡介
資料服務模組支援發佈資料接收 API，可接收上游下發的資料，解析後寫入資料庫。如下圖所示：
注1：可呼叫資料接收 API 插入/更新資料，暫不支援刪除資料。
注2：支援寫入的資料庫類型：Oracle 、MySQL 、SQL Server 、PostgreSQL、達夢資料庫。
2. 前提條件
資料接收功能初版要求部署 Kafka、配置傳輸佇列，增加了使用成本。4.2.11.2 及之後版本，資料接收功能可對接記憶體佇列，無需部署 Kafka。
因此使用資料接收功能的使用者可根據實際情況，選擇是否部署 Kafka、配置傳輸佇列。詳細說明見下方表格：
| 傳輸佇列類型 | 說明 |
|---|---|
記憶體佇列（無需部署 Kafka、配置傳輸佇列） 4.2.11.2 及之後版本，才支援選擇 | 應用場景： 試用資料接收功能，驗證整體的接收寫入主流程能否滿足自己的訴求 優勢：
劣勢：
|
訊息佇列中間軟體（需部署 Kafka、配置傳輸佇列） 4.2.11.2 之前版本，必須部署 Kafka、配置傳輸佇列 | 應用場景： 使用者使用量上升，對於資料安全性，效能有了更高的要求，希望能夠追溯異常資料，並能夠在接收到資料後非同步處理寫入以提升API效能 優勢：
劣勢：
|
2.1 使用記憶體佇列
資料服務模組中，點選「服務設定」按鈕，關閉「訊息佇列中間軟體」按鈕。如下圖所示：
下載 4.2.11.2 及之後版本的安裝包，新部署的 FDL 工程，該按鈕預設關閉。
若工程之前未配置過傳輸佇列，升級到 4.2.11.2 及之後版本，該按鈕預設關閉。
使用者開啟「訊息佇列中間軟體」按鈕，安裝 Kafka 配置傳輸佇列後，需要重啟 FineDataLink 工程。
2.2 使用訊息佇列中間軟體
1）需要部署 Kafka。詳情請參見：部署Kafka：ZooKeeper模式、部署Kafka：KRaft模式
2）超管需要配置 傳輸佇列 。如下圖所示：
若工程之前配置過傳輸佇列，升級到 4.2.11.2 及之後版本，該按鈕預設開啟。
若關閉「訊息佇列中間軟體」按鈕，需要重啟 FineDataLink 工程。
3. 操作步驟
3.1 建立資料接收API
1）進入 FDL 工程，點選「資料服務」，建立一個資料接收 API 。如下圖所示：
2）接收方式預設為「通用API請求體」。如下圖所示：
3.2 服務內容（資料接收）
3.2.1 設定資料來源
需要將待提交的業務資料轉換為API所需的 JSON 格式參數，後續呼叫該API時，會將這段 JSON 填入 Body 內。
1）點選「來源請求體解析」右側的「配置」按鈕，輸入 JSON 結構的資料。如下圖所示：
勾選「將範本資料作為服務入參除錯值」按鈕效果：將使用者輸入 JSON 格式資料填入服務入參的除錯值。如下圖所示：
2）選擇要解析的節點。如下圖所示：
注：不支援跨路徑解析陣列。
3）可查看解析後的欄位名、欄位路徑，支援刪除欄位。如下圖所示：
注：刪除欄位時，若只剩最後一個欄位，「刪除」按鈕禁用。
點選「解析預覽」按鈕，支援查看解析後的資料：
注：欄位類型根據本次 JSON 範本資料中解析出的類型固定。
4）配置完成後，最終介面如下圖所示：
點選「編輯」按鈕，可對資料來源配置進行修改。
3.2.2 設定資料去向
接下來需要設定目標表及欄位映射。如下圖所示：
注：支援寫入的資料庫類型：Oracle 、MySQL 、SQL Server 、PostgreSQL、達夢資料庫。
資料操作：
固定為：資料插入更新，暫不支援資料刪除。
目標表類型：
預設需要選擇已存在表；可點選「建立目標表」按鈕，在目標資料庫中自動建表（資料連結使用者需要有當前庫的執行權限）。
1）點選「建立目標表」按鈕後，輸入目標表名稱（支援輸入表描述），將自動獲取來源表的欄位名和類型填入：
支援新增欄位。
2）點選「下一步」按鈕後，再點選「執行建表」按鈕，將在目標資料庫中建立表：
3）建表成功後，欄位映射中自動選擇建立的表，根據建立表欄位自動生成映射。
注：若建表時未設定主鍵，支援在「主鍵映射」中設定邏輯主鍵。
欄位映射方式：
可選擇同名映射、同行映射，詳情請參見：資料同步-資料去向與映射
欄位映射：
1）來源表的欄位類型根據配置解析時的範本資料生成，實際資料類型不一致時，將報錯。
2）支援取消某個欄位的映射關係，支援調整目標表中欄位的前後順序。
主鍵映射：
1）目標表未配置主鍵時，可在此處配置主鍵；目標表已有主鍵時，直接顯示主鍵。
2）目標表存在主鍵後，支援配置主鍵衝突策略：
3.2.3 進階配置
資料寫入有兩個程式：接收到資料後先把資料存入到 Kafka，再把 Kafka 中的資料進行寫入。
| 按鈕狀態 | 說明 |
|---|---|
| 開啟 | 呼叫發佈的 API 時，監視資料是否透過該API入庫成功： API API將先進行資料快取，等待資料入庫操作完成後，傳回入庫結果 |
| 關閉 | 接收到資料且資料快取進 Kafka 後進行通知，監視資料是否透過該API推播成功：
|
3.2.4 參數和變數
| 參數和變數 | 說明 |
|---|---|
| 預定義參數 | 該 API 發佈後，呼叫該 API 時需要填入的 Body 值；若在 3.1 節勾選了「將範本資料作為服務入參除錯值」按鈕，3.1 節輸入 JSON 資料為此處的除錯值
|
| 傳回變數 | 呼叫該 API 後，傳回的參數
|
3.3 API配置
3.3.1 基礎屬性
| 設定項 | 說明 |
|---|---|
| 請求方式 | 只支援選擇 POST |
| 路徑 | 配置要發佈的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.2 API請求
注：Query 禁用。
| 設定項 | 說明 |
|---|---|
| 請求 Body 格式 | 只支援 application/json |
| Body 整體綁定 | 預設開啟且禁止關閉 |
| 除錯值 | 與「資料服務（資料接收）」步驟中預定義參數的除錯值相同，詳情請參見本文 3.2.4.節內容 |
3.3.3 API回應
1）展示呼叫 API 後傳回的資料格式（JSON 格式）。
2）反映異常資訊按鈕：
勾選：API異常資訊將反映在 HTTP 狀態碼上。
不勾選：HTTP 狀態碼僅傳回 200 或 404。
3）支援使用者自動調整傳回的資料格式；點選「快捷生成」按鈕，下拉框中可選擇自動生成、按JSON範本生成，詳細說明請參見：JSON生成 文檔。
4）點選「測試呼叫」按鈕，調整 Body 值，會觸發資料庫實際執行操作；測試呼叫時，會校驗傳輸佇列是否配置成功，若未配置，無法使用測試呼叫功能。
此時，查看目標表，發現目標表填入資料：
3.4 API 上線
點選「儲存」按鈕或者「儲存聯集線」按鈕生成 API。
若配置不完整，點選「儲存聯集線」按鈕將報錯，但可以點選「儲存」按鈕儲存已有配置。
3.5 綁定 API 至應用
API 若想被呼叫必須綁定應用。
使用者可在本文 3.3 節步驟中給 API 綁定應用，或者 3.4 節結束後，參考 綁定API至應用 給 API 綁定應用。
3.6 呼叫 API
1）完整的 API 路徑獲取方式：
4.2.8.4 及之後版本，使用者也可 匯出 API 文檔 查看 API 完整路徑。
2）若 API 綁定的應用無認證，呼叫已發佈的 API 範例：
呼叫成功後，可到目標表中查看寫入的資料。
3）若應用認證方式為 AppCode，呼叫 API 時，需要再填入 Authorization 。如下圖所示：
Authorization 值來源：