通過SQL直接從資料來源建立API查詢資料。本文為您介紹如何使用直連資料來源模式產生API。
使用限制
需購買行級許可權功能後才可使用行級許可權功能。
在API調用時，若資料來源本身支援分頁，且AP操作方式為List，則無論是否開啟分頁查詢，均可使用PageStart及PageSize設定分頁。
當使用進階SQL模式建立API時，若在SQL指令碼中使用Limit限制返回查詢的結果條數，則在API調用時，參數中指定的OrderByList僅針對Limit返回的資料進行排序，即Limit優先順序高於OrderByList。例如：將phone_no排名前10的資料再根據paper_no排序。
SELECT * FROM ( select paper_no,phone_no,vip_no from aaaa order by phone_no limit 1,10 ) T0 --即API中的SQL指令碼 ORDER BY paper_no ASC--調用時添加OrderByList的執行語句當使用基礎SQL建立API時，SQL指令碼中使用LIMIT限制返回查詢的結果條數，則不支援使用分頁查詢。
支援通過SQL直連資料來源建立API、關聯線級許可權以及分頁查詢的資料來源，請參見資料服務支援的資料來源。
許可權說明
支援服務的專案系統管理員和開發使用者可以產生API。
非同步呼叫流程說明
下方流程圖為您介紹使用非同步呼叫進行資料查詢的整個生命週期管理，包括擷取任務的ID、狀態、結果、關閉查詢任務各個流程之間的流轉，詳情如下：
非同步呼叫查詢流程：
GetJobStatus：擷取API調用的執行狀態。
GetJobResult：返回請求的結果，僅當Job的狀態為Success時可調用成功，否則則調用失敗，僅支援順序擷取查詢結果。
GetJobExecutionLog：擷取API執行的日誌。
CloseJob：完成該請求，釋放所有Job佔用的資源，包括資料庫連接、緩衝等。Failed的狀態也調用該介面釋放資源。
非同步呼叫取消查詢流程：
CancelJob：取消查詢請求。若有執行中的資料庫查詢請求，將同步取消查詢；若未開始或已經完成資料庫的查詢，則不可取消對資料庫的查詢。
步驟一：選擇產生API的方式
在Dataphin首頁的頂部功能表列，選擇服務 > API開發。
在左上方選擇專案，單擊左側導覽列API服務，然後在API頁面，單擊+建立API。
在建立API對話方塊中，選擇直連資料來源-SQL模式。
步驟二：配置API參數資訊
在建立API頁面，配置API基本資料和參數配置。
API基本資料配置
參數
描述
API名稱
填寫API的名稱。命名規則如下：
支援中文、字母、數字或底線（_）。
長度為4~100個字元。
必須以中文、英文開頭。
全域唯一。
操作類型
GET：請求伺服器擷取指定的某個資源。
LIST：請求伺服器擷取某一部分的資源。
資料更新頻率
定義API返回資料的更新頻率，便於調用方瞭解資料的時效性，支援的更新頻率為每天、每小時、每分鐘以及自訂，若選擇自訂，支援輸入不超過128個字元。
API分組
選擇API需要歸屬的分組。如需建立，請參見建立服務分組。
描述
填寫對API的簡單描述。不超過128個字元。
協議
資料產生API的介面協議，支援HTTP、HTTPS協議。
HTTP：即超文字傳輸通訊協定 (HTTP)HTTP（HyperText Transfer Protocol），是應用最為廣泛的網路通訊協定。
HTTPS：若網關配置為阿里公用雲端API Gateway（專享執行個體或共用執行個體）時，支援選中HTTPS協議，請確保獨立網域名稱的SSL認證有效，避免無法正常調用。請通過選擇平台管理網路設定，在網路設定頁面，進行SSL認證配置。
調用模式
用於用戶端和伺服器之間的通訊，以擷取或處理資料。支援選擇同步調用和非同步呼叫，預設為同步調用。
同步調用：用戶端發送請求後，必須等伺服器返回結果後才能繼續執行其他請求，針對複雜查詢語句，回應時間較長且在等待過程中會佔用伺服器串連數，造成伺服器壓力。適用於即時性要求高、處理時間短的情境。
非同步呼叫：用戶端發送請求後，無需等待伺服器響應，可繼續執行其他請求，伺服器處理完成後再通知用戶端，在批量擷取資料時，可降低資料庫查詢結果的重複率，用資料服務API進行資料擷取。適用於處理時間長、即時性要求不高的情境，如批量處理等。
執行逾時時間
當調用模式為非同步呼叫時支援該配置項。用於監控SQL執行的時間長度。預設為60秒，支援設定的時間範圍為1到7200秒（2小時）的正整數。
逾時時間
用於監控API調用的最大時間長度。當調用模式為同步調用時，預設為3秒，支援設定的時間範圍為3到60秒的正整數；當調用模式為非同步呼叫時，預設為600秒，支援設定的時間範圍為3到7200秒（2小時）的正整數。
調用API過程中如果超過了設定的逾時時間，則調用API時會報錯，便於您及時發現並處理調用API的異常情況。關於異常情況的查看，詳情請參見查看及管理營運監控API。
最大返回條數
當操作類型為LIST時支援該配置項。API最大的返回條數為10000條。支援輸入1~10000之間的正整數。
緩衝設定
當調用模式為同步調用時支援該配置項。支援開啟或關閉。開啟後需配置緩衝時間長度。預設300秒，支援設定60秒~1000000秒（約277.78小時）之間的正整數。
版本號碼
請填寫API的版本號碼，每份配置資訊會有所屬版本號碼，以便於和上個版本資訊對比。該API下版本號碼唯一。命名規則如下：
不超過64個字元。
支援輸入大小寫英文字母、數字、底線（_）、半形句號（.）、短劃線（-）。
傳回型別
預設JSON。
API請求參數和返回參數配置
在配置API請求參數和返回參數的過程中，您需要先確定輸入參數和輸出參數的來源表，再編寫API SQL並解析出請求參數和返回參數，最後配置請求參數和返回參數的基本資料。
在API參數配置地區，確定輸入參數和輸出參數的來源表，並根據參考樣本編寫API SQL指令碼。
參數
描述
模式
選擇資料來源環境，支援Basic或Dev-Prod。
Basic模式下開發時、提交及發布線上均讀取生產庫。
Dev-Prod模式下開發及提交讀取開發庫，發布線上讀取生產庫。
資料來源
根據資料來源類型選擇資料來源，支援非同步呼叫模式的資料來源，請參見資料服務支援的資料來源。
說明MySQL支援MySQL5.1.43、MySQL5.6/5.7和MySQL8版本。
查詢加速
當資料來源為MaxCompute時可配置此參數。開啟後，將使用MaxCompute MCQA加速查詢，可提升任務的查詢速度，將執行時間縮短至秒級。MCQA每一個租戶下，作業數量與並發數有限制，可能會導致加速失敗，執行報錯解決方式請參見查詢加速（MCQA）。
SQL模式
支援選擇基礎SQL和進階SQL兩種模式。
結果分頁
當調用模式為同步調用且操作類型為List時，支援設定結果分頁。開啟後，請務必指定排序欄位，確保返回查詢結果的穩定，避免導致分頁查詢的部分結果重複及丟失；關閉後，API調試或測試頁面不展示分頁參數（PageStart及PageSize），您可以取消選中隱藏參數，展示分頁參數。
排序優先順序
當SQL模式選擇基礎SQL時，可以選擇排序的優先順序順序，支援選擇SQL指令碼或OrderByList請求參數。
SQL指令碼：若SQL指令碼指定了排序，則公用請求參數中的OrderByList不生效。
OrderByList請求參數：在測試或調試API時，SQL指令碼中定義的排序與OrderByList公用請求參數同時生效，OrderByList公用請求參數的優先順序高於API中定義的排序設定。
當SQL模式選擇進階SQL時，在測試或調試API時，SQL指令碼中定義的排序與OrderByList公用請求參數同時生效，OrderByList公用請求參數的優先順序高於API中定義的排序設定。
說明當資料來源為HBase0.9.4/1.1.x/2.x、TDengine、SAP HANA時，不支援配置排序優先順序。
API SQL指令碼編輯
API SQL指令碼協助您在編輯指令碼時需遵循的SQL編輯規範，詳情請參見API SQL指令碼編輯說明。
參考樣本
Dataphin能解析出返回參數和請求參數的SQL指令碼模板如下：
Get/List基礎SQL樣本：
-- 樣本一：根據條件查詢單條記錄；id非必填且未傳參時，自動忽略該條件 SELECT id,name FROM tablename WHERE id = ${id} -- 樣本二：In條件批量查詢，id_list參數按“,”分隔 SELECT id,name FROM tablename WHERE id in (${id_list}) -- 樣本三：使用Like模糊比對，彙總函式使用語義化別名 SELECT MAX(a) AS max_a, SUM(a) AS sum_a, MIN(a) AS min_a, COUNT(*) AS count_all FROM tableName WHERE name LIKE ${name_pattern} -- 樣本四：帶標別名的查詢 SELECT t.name as name FROM tablename t WHERE id=${id_card} -- 樣本五：運算式計算+多條件查詢 SELECT (a+b) as sum_ab, (b+c) as sum_bc FROM tablename WHERE id=${id_card} and b>=${num} and c<=${num1} -- 樣本六：分組 + CASE統計 SELECT category, SUM(CASE WHEN name LIKE ${name_pattern} THEN 1 ELSE 0 END) AS proj_score FROM table WHERE id=${id} GROUP BY categoryGet/List進階SQL樣本：
-- 目前支援的Mybatis標籤類型包括：if、choose、when、otherwise、trim、foreach和where。 -- 標籤內的SQL參數支援$或者#符號標識，具體樣本如下 -- 樣本1：使用 <where> + <if> 實現條件過濾 SELECT id, name, age FROM tableName <where> <if test="name != null and name != ''"> AND age > #{age} </if> <if test="name == null"> AND age < #{age} </if> </where> -- 樣本2：使用 <choose> 實現互斥條件 SELECT id, name, age FROM tableName <where> <choose> <when test="name != null and name != ''"> AND age > #{age} </when> <when test="age != null"> AND age < #{maxAge} </when> <otherwise> AND status = 'active' </otherwise> </choose> </where> -- 樣本3：使用 <foreach> 實現 IN 查詢 SELECT id, name FROM tableName <where> id IN <foreach item="item" index="index" collection="idList" open="(" separator="," close=")"> #{item} </foreach> </where> -- 樣本4：使用 <trim> 自訂首碼（替代 <where>） SELECT id, name, age FROM ${tableName} <trim prefix="WHERE" prefixOverrides="AND | OR "> <if test="name != null"> AND name LIKE #{namePattern} </if> <if test="minAge != null"> AND age >= #{minAge} </if> <if test="status != null"> AND status = #{status} </if> </trim> -- 樣本5：動態欄位查詢（var_cols） SELECT category,${var_cols_metrics} FROM tableName WHERE id = ${id} GROUP BY category
格式化
支援對SQL語句格式化處理展示，僅支援對基礎SQL。
欄位參考
在欄位參考面板中，為您展示已選擇資料表中的所有欄位。
複製：支援複製表名稱、全表欄位或單個欄位。
快捷插入：單擊快捷插入，系統根據操作類型插入SQL指令碼語句，指令碼語句詳情請參見API SQL指令碼快捷匯入SQL。
異常欄位用警示
表徵圖標識，您需要查看該欄位所屬的服務單元是否發行至生產環境或該服務單元是否存在。
單擊解析參數，Dataphin會自動解析出API SQL的入參和出參並分別添加至請求參數和返回參數地區。若SQL模式選擇進階SQL，支援勾選保留手動設定，當修改SQL指令碼需再次解析參數時，系統將保留已填寫的參數資訊；如需刪除無用參數資訊，請手動刪除。適用於複雜的SQL語句參數無法解析，需手動填寫參數資訊的情境。
說明若SQL模式為進階SQL，以
var_cols開頭的參數為動態參數，支援通過傳參的方式動態指定SQL語句查詢返回的欄位，可將所有支援的欄位添加到返回參數中。調用API時，在動態參數中傳入需要查詢的欄位，若未傳入，則欄位在返回參數中為Null值。若SQL模式為基礎SQL，當參數為非必填且無輸入參數時，系統將自動改寫SQL，忽略對應的篩選條件；若參數實值型別為between，則該參數值為必填。
進階SQL語句較為複雜，SQL編譯解析的參數不一定完整且正確。因此，您可根據SQL語句對解析結果進行刪除參數、新增請求參數和新增返回參數操作。
參數
描述
請求參數
參數名稱
必填，顯示對外開放的參數名，系統從SQL中解析，不支援修改。
參數類型
必填，需選擇參數名對應綁定欄位的參數類型，支援選擇DOUBLE、FLOAT、STRING、DATE(yyyy-MM-dd HH:mm:ss)、BOOLEAN、INT、LONG、SHORT、BYTE、BIGDECIMAL和BINARY。
如果邏輯表的欄位類型不在待選參數類型範圍內，推薦選擇String。
參數實值型別
必填，選擇參數值的類型，支援單值、多值。
單值：根據參數類型傳入，傳入參數將被解析為單一值，適用的操作符為
=、like、>=、<=、>、<、!=、between。多值：傳入參數將被解析為多個值，多個值之間使用半形逗號（,）分隔，適用的操作符為
in。
參數處理
當操作符為LIKE時需配置。若未選擇參數處理，需在入參時手動輸入萬用字元進行匹配。支援選擇模糊比對（%keyword%）、右匹配（%keyword）、左匹配（keyword%）。
樣本
填寫請求參數值和返回參數值的樣本，便於開發人員理解。支援輸入不超過1000個字元。
描述
填寫對請求參數和返回參數的簡單描述。支援輸入不超過1000個字元。
是否必填
選擇請求參數是否為調用API時的必填參數。
選擇否：調用API的語句中沒有該參數也可以執行調用API的SQL語句。
選擇是：調用API的語句中沒有該參數，將無法執行調用API的SQL語句。
例如，請求參數為id，請求參數為必填參數，返回參數為name；則執行以下語句會有不同的返回：
返回對應的name欄位及資料：
select name from tableA where id=5;。SQL語句執行報錯：
select name from tableA;。
操作
支援批量修改請求參數的參數類型、參數實值型別、參數處理（僅操作符為LIKE時支援操作）、是否必填及大量刪除參數（僅進階SQL模式支援操作）。
當選擇進階SQL模式，支援單擊新增請求參數，手動添加參數。
返回參數
參數名稱
必填，顯示對外開放的參數名，系統從SQL中解析，不支援修改。
參數類型
必填，需選擇參數名對應綁定欄位的參數類型，支援選擇DOUBLE、FLOAT、STRING、DATE(yyyy-MM-dd HH:mm:ss)、BOOLEAN、INT、LONG、SHORT、BYTE、BIGDECIMAL和BINARY。
如果邏輯表的欄位類型不在待選參數類型範圍內，推薦選擇String。
樣本
填寫請求參數值和返回參數值的樣本，便於開發人員理解。支援輸入不超過1000個字元。
描述
填寫對請求參數和返回參數的簡單描述。支援輸入不超過1000個字元。
操作
支援批量修改返回參數的參數類型及大量刪除參數（僅進階SQL模式支援操作）。
當選擇進階SQL模式時，支援單擊新增返回參數按鈕，手動添加參數。
單擊SQL試運行，在請求參數輸入對話方塊中，選擇參數類型、參數實值型別、參數處理和試運行輸入值，然後單擊確認。
作業記錄：支援查看SQL試運行時實際執行的SQL語句。
試運行輸入值：需要配置綁定欄位的欄位值，可以在資料預覽面板查看綁定欄位的欄位值。
大量操作：支援批量修改請求參數的參數類型、參數實值型別、參數處理（僅操作符為LIKE時支援操作）及大量刪除參數（僅進階SQL模式支援操作）。
單擊填充參數樣本值，系統會將最近一次試運行成功的樣本值填充至請求參數和返回參數。如果樣本有值，則不進行覆蓋，支援修改。
僅當SQL模式為進階SQL且已有試運行結果記錄時，支援單擊填充返回參數/從試運行結果匯入，在填充參數對話方塊中，配置參數的添加方式及同名參數處理方式。
添加方式：匯入參數時的添加策略，支援追加新參數和全量替換已有參數。
追加新參數：保留返回參數列表中已有參數並追加本次試運行結果中的解析的參數，根據參數名稱唯一性，添加列表中不同名參數。
全量替換已有參數：將返回參數列表中已有參數全部替換為試運行結果中解析的參數。
同名參數處理：當添加方式為追加新參數時支援配置。針對添加的參數名稱重複時處理策略，支援保持不變或替換。
保持不變：保留原有參數資訊不變更。
替換：若試運行結果的參數名稱和列表中的參數名稱重複，以本次試運行結果中解析的參數類型和樣本值為準更新列表中的資訊；若試運行結果的值為空白，則不進行替換。
若選中同步填充請求參數的樣本值，將根據填充參數的配置同步替換請求參數列表中的樣本值。
僅當SQL模式為基礎SQL時支援展示關聯線級許可權。單擊解析參數按鈕，系統自動為您解析資料來源表所關聯的行級許可權資訊，包括行級許可權名稱、描述說明、控制欄位、資料來源環境、關聯表、關聯欄位。同時，您可以執行如下操作。
開啟或關閉行級許可權：控制行級許可權的生效狀態以及在查看API、版本對比、調試/測試API時是否可見行級許可權列表資訊。
去建立行級許可權：操作人需具有行級許可權建立許可權。單擊跳轉至管理中心 > 許可權管理的行級許可權建立頁面，建立行級許可權。
說明調用該API所返回的資料範圍受到行級許可權的管控，行級許可權不一致時，資料返回結果會存在差異。
當模式為Basic時，展示生產環境關聯的資料來源錶行級許可權；模式為Dev-Prod時，展示開發環境和生產環境關聯的資料來源錶行級許可權。
單擊提交，系統將校正API引用的欄位在所屬的資料來源中是否存在，校正通過後，完成API的產生。