前提條件

基于服務單元生成，需先完成服務單元的創建。具體操作，請參見創建服務單元。

權限說明

支持服務的項目管理員和開發用戶生成API。

使用說明

• 使用API分頁查詢時，需要設置字段排序以確保返回結果的順序穩定，避免導致分頁查詢的部分結果重復及丟失；僅當使用API分頁查詢時，在API調試或測試頁面展示分頁參數（PageStart及PageSize）信息。

• 在API調用時，分頁查詢是否開啟，均可使用PageStart及PageSize設置分頁。

支持分頁、排序的數據源

Y表示支持；N表示不支持。

是否必須指定排序：如果數據源類型需要強制指定排序，則在分頁查詢時，需要在API中配置參數或在調用時設置OrderByList參數指定排序。

注意事項

API的請求參數和返回參數需從同一個服務單元（單物理表服務單元或多物理表服務單元）中獲取，否則后續無法正常調用該API。

步驟一：選擇生成API的方式

1. 在Dataphin首頁，在頂部菜單欄選擇服務 > 開發。

2. 選擇項目，單擊左側導航欄API，在API頁面，單擊+新建API。

3. 在API創建方式選擇對話框，選擇服務單元API-向導模式后，單擊確定。

步驟二：配置API參數信息

1. 在新建API頁面，配置API基本信息和參數配置。

   API基本信息配置

   參數	描述
   API名稱	填寫API的名稱。命名規則如下： 只能包含中文、字母、數字或下劃線（_）。 長度為4~42個字符。 以字母開頭。 全局唯一。
   請求方式	API請求方式包括GET和LIST： GET：請求服務器獲取指定的某個資源。 LIST：請求服務器獲取某一部分的資源。
   數據更新頻率	定義API返回數據的更新頻率，便于調用方了解數據的時效性，支持每天、每小時、每分鐘更新API返回的數據。
   API分組	選擇API需要歸屬的分組。如需創建，請參見創建服務分組。
   結果分頁	當請求方式為List時，支持設置結果分頁。開啟后，請務必指定排序字段，確保返回查詢結果的穩定，避免導致分頁查詢的部分結果重復及丟失；關閉后，API調試或測試頁面不展示分頁參數（PageStart及PageSize），您可以取消選中隱藏參數，展示分頁參數。
   描述	填寫對API的簡單描述。不超過128個字符。
   協議	當前，數據服務支持生成API接口協議，包括HTTP和HTTPS。 HTTP：即超文本傳輸協議（HyperText Transfer Protocol），是應用最為廣泛的網絡協議。 HTTPS：即HTTP的安全版。HTTPS的安全基礎是SSL，因此您需要配置獨立域名的SSL證書。同時需要確保獨立域名的SSL證書有效，避免無法正常調用。
   超時時間	超時時間用于監控API調用的時長。調用API過程中如果超過了設定的超時時間，則調用API時會報錯，便于您及時發現并處理調用API的異常情況。異常情況查看，詳情請參見查看及管理運維監控API。
   緩存設置	支持開啟或關閉。開啟后需配置緩存時長。默認300sec（秒），支持設置60秒~1000000秒（約277.78小時）之間的正整數。
   版本號	請填寫API的版本號，每份配置信息會有所屬版本號，以便于和上個版本信息對比。64字符以內。該API下版本號唯一。
   返回類型	默認JSON。

   API請求參數和返回參數配置

   在配置API請求參數和返回參數過程中，您需要先確定API的入參和出參的來源（服務或單元），再將入參和出參分別添加至請求參數和返回參數區域，最后配置請求參數和返回參數的基本信息。

   1. 在參數配置區域，選擇模式和服務單元后，頁面下方會為您展示已選擇的服務單元中所有的字段。

      參數	描述
      模式	支持Basic或Dev_Prod兩種模式。 Basic模式下開發時、提交及發布線上均讀取生產庫。 Dev-Prod模式下開發及提交讀取開發庫，發布線上讀取生產庫。
      服務單元字段	支持復制全表字段或單個字段。異常字段用告警圖標標識，您需要查看該字段所屬的服務單元是否已發布至生成環境或該服務單元是否存在。

   2. 在雙列表框的左側列表中選擇一個或多個字段后，單擊圖標，將已選擇API的字段添加至右側的請求參數列中，再配置請求參數的基本信息。

      

      參數	描述
      參數名	對外開放的參數，即用戶訪問API時直接使用的參數。命名規則如下： 包含字母、數字或下劃線（_）。 以字母開頭。 長度為1~64個字符。
      綁定字段	對外不可見的參數，API調用時實際訪問的參數。
      參數類型	參數類型包括Double、Float、String、Date、Boolean、Int、Long、Short、Byte、Bigdecimal、Binary。您需要根據服務單元中字段的類型選擇對應的參數類型。 服務單元字段類型與請求參數字段類型保持一致，您選擇對應的字段類型即可。
      操作符	調用API時對請求參數的處理方式。當前支持的操作符及含義請參見附錄：支持的操作符。
      示例	填寫請求參數值的示例，便于開發者理解。例如：參數名稱為ID，參數類型為Int，操作符為=，則示例處可以配置為5。
      描述	填寫對請求參數的簡單描述。
      是否必填	請求參數是否為調用API時的必填參數。 選擇為否：調用API的語句中沒有該參數也可以執行調用API的SQL語句。 選擇為是：調用API的語句中沒有該參數無法執行調用API的SQL語句。 例如，請求參數為id，請求參數為必填參數，返回參數為name；則執行以下語句會有不同的返回： select name from tableA,where id=5；：則返回對應的name字段及數據。 select name from tableA;：則SQL語句執行報錯。

   3. 在雙列表框的左側列表中選擇一個或多個字段后，單擊圖標，將已選擇API的字段添加至右側的返回參數列中，再配置返回參數的基本信息。

      

      參數	描述
      參數名	對外開放的參數，API返回時最終展示給用戶的參數名稱。命名規則如下： 包含字母、數字或下劃線（_）。 以字母開頭。 長度為1~64字符。
      綁定字段	對外不可見的參數，API調用時實際訪問的參數。
      參數類型	調用API時的數據格式。參數類型包括Double、Float、String、Date、Boolean、Int、Long、Short、Byte、Bigdecimal、Binary。您需要根據服務單元中字段的類型選擇對應的參數類型。 服務單元字段類型與請求參數字段類型保持一致，您選擇對應的字段類型即可。
      示例	填寫返回參數值的示例，便于開發者理解。
      描述	填寫對返回參數的簡單描述。

   4. 在雙列表框的左側列表中選擇一個或多個字段后，單擊圖標，將已選擇API的字段添加至右側的排序設置列中，將需要排序的字段添加至排序設置區域。

      排序字段非必填，若開啟分頁查詢，請務必指定排序字段，確保返回查詢結果的穩定，避免導致分頁查詢的部分結果重復及丟失；若在請求中指定了排序參數，則以參數中設置的排序為準。

      

      參數	描述
      排序字段	選擇服務單元中需要排序的字段。
      排序方式	支持升序、降序。
      操作	支持選中字段名稱前的圖標進行拖拽排序或選擇操作列下的圖標進行上下移動，圖標從左到右依次為：上移、下移、刪除。 說明 排序結果根據排序順序從上往下優先級依次降低。 若API的請求方式為GET，排序后返回第一條結果數據。

2. 單擊提交，校驗API引用的字段在所屬的服務單元中是否存在，校驗通過后，完成API的生成。

附錄：支持的操作符