提示:4.2.18.1 之前工程，請參考：歷史文檔
目錄:
1. 概述编辑
1.1 版本
| FineDataLink 版本 | 功能變動 |
|---|---|
| 5.0.11.1 | 發佈和呼叫通用 API 接收API時，流程重構 |
1.2 應用場景
使用者希望 FineDataLink 提供一個API，業務系統呼叫後將資料實時地新增/更新到目標端，且資料寫入前可對資料進行處理 。
1.3 功能簡介
1）資料服務功能中，發佈一個 API：
2）與實時任務中的「Webhook輸入」算子聯合使用，實現呼叫API後對資料進行處理再輸出的效果。如下圖所示：
注：可呼叫資料接收 API 插入/更新資料，暫不支援刪除資料。
1.4 前提條件
需要註冊API協定（實時）功能點、資料服務基礎包功能點、實時任務相關功能點。
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：KRaft模式
2）資料服務模組中，點選「服務設定」按鈕，開啟「訊息佇列中間軟體」按鈕，配置 傳輸佇列。如下圖所示：
注：下圖和 快取配置 文檔中修改的是同一份配置，只不過 FineDataLink 提供了兩個入口（任選一個入口修改即可）。
若工程之前配置過傳輸佇列，升級到 4.2.11.2 及之後版本，該按鈕預設開啟。
若關閉「訊息佇列中間軟體」按鈕，需要重啟 FineDataLink 工程。
若後面切換 Kafka，需要手動處理 offset 。具體步驟請參見：切換 Kafka
3. 操作步驟编辑
3.1 場景模擬
使用者需要接收外部 SaaS 應用的資料，將資料寫入資料庫中存檔，且上游無刪除事件 。
3.2 建立資料接收API
進入 FDL 工程，點選「資料服務」，建立一個資料接收 API 。如下圖所示：
3.3 配置資料接收 API
3.3.1 基礎屬性
| 設定項 | 說明 |
|---|---|
| 請求方式 | 只支援選擇 POST |
| 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 綁定到已有應用上；點選「新增」按鈕後，可再點選「去建立」按鈕建立應用，將該 API 綁定在建立應用上
2）或者建立 API 後，在應用列表Tab下，將 API 綁定在應用上，具體說明請參見：綁定API至應用 綁定應用後，可複製完整存取路徑
|
3.3.2 API請求
注：Query 禁用。
| 設定項 | 說明 |
|---|---|
| 請求 Body 格式 | 只支援 application/json |
| Body 整體綁定 | 預設開啟且禁止關閉 |
3.3.3 API回應
1）展示呼叫 API 後傳回的資料格式（JSON 格式）。
2）反映異常資訊按鈕：
勾選：API異常資訊將反映在 HTTP 狀態碼上。
不勾選：HTTP 狀態碼僅傳回 200 或 404。
3）支援使用者自動調整傳回的資料格式；點選「快捷生成」按鈕，下拉框中可選擇自動生成、按JSON範本生成，詳細說明請參見：JSON生成 文檔。
4）點選「測試呼叫」按鈕，調整 Body 值，會觸發資料庫實際執行操作；測試呼叫時，會校驗傳輸佇列是否配置成功，若未配置，無法使用測試呼叫功能。
3.3.4 進階配置
資料寫入有兩個程式：接收到資料後先把資料存入到 Kafka，再把 Kafka 中的資料進行寫入。
注：「訊息佇列中間軟體」按鈕關閉時，不支援該功能。
| 按鈕狀態 | 說明 |
|---|---|
| 開啟 | 呼叫發佈的 API 時，監視資料是否透過該API入庫成功： API API將先進行資料快取，等待資料入庫操作完成後，傳回入庫結果 注：簡道雲逾時時間很短僅有 5 秒，該按鈕開啟後會等待較長時間，一般情況下建議關閉該按鈕 |
| 關閉 | 接收到資料且資料快取進 Kafka 後進行通知，監視資料是否透過該API推播成功：
|
3.4 API 詳情頁
點選「儲存」按鈕後進入 API 詳情頁。
該API在實時任務的「Webhook輸入」算子中用到後，API狀態自動更改為上線；實時任務運作失敗，API狀態自動更改為未上線。
3.5 綁定 API 至應用
API 若想被呼叫必須綁定應用。
使用者可在本文 3.3 節步驟中給 API 綁定應用，或者 3.4 節結束後，參考 綁定API至應用 給 API 綁定應用。
3.6 建立實時任務
提示:資料接收 API 與實時任務配合使用時，僅支援資料的新增和更新（若想實現更新，寫入時需要配置主鍵）。
1）建立一個實時任務。
2）實時任務中拖入「Webhook輸入」算子，呼叫 2.2 節發佈的 API，樣本設定處填寫API的JSON請求體（便於在後續節點中查看效果），如下圖所示：
| 設定項 | 說明 |
|---|---|
| 服務名稱 | 下拉框中顯示有權限的，服務接收方式為「僅配置地址」的 API |
| 樣本設定 | 可填寫呼叫該 API 時的 JSON 請求體，便於繼續後續的資料處理流程以及在後續節點中預覽處理效果 |
| 測試服務 | 功能同 資料接收 中的測試呼叫效果 可填入API請求，呼叫API；此處會實際呼叫API寫入資料 |
點選「資料預覽」，如下圖所示：
3）拖入「JSON解析」算子，對呼叫 API 後獲取的資料進行解析。如下圖所示：
點選「資料預覽」，如下圖所示：
4）拖入「資料過濾」算子，對資料進行過濾。如下圖所示：
5）拖入一個匯出算子，將資料匯出，啟動該實時任務。
注：如果需要實現資料的更新，需要在目標端設定主鍵。
3.7 效果查看
本文的場景是：使用者需要接收外部 SaaS 應用的資料，將資料寫入資料庫中存檔，且上游無刪除事件。
所以需要將 API 地址複製到 SaaS 應用的 URL 地址框中，便於接收上游新增和更新的資料。
1）本文用 Postman 模擬 SaaS 應用。Postman 中寫入資料：
2）發現實時任務的目標表中資料變動。
3.8 知識擴展
4.2.17.5 及之後版本，支援查看 API 的呼叫詳情，比如呼叫 API 時的請求內容、傳回內容，具體說明可參見：顯示資料服務API呼叫詳情
