SQL模式是基于服務單元編寫SQL語句創建API。本文為您介紹如何使用SQL模式生成API。
前提條件
基于服務單元生成API，需先完成服務單元的創建。具體操作，請參見創建服務單元。
權限說明
支持服務的項目管理員和開發用戶生成API。
使用說明
在API調用時，若數據源本身支持分頁，且API請求方式為List，則無論是否開啟分頁查詢，均可使用PageStart及PageSize設置分頁。
當在SQL腳本中使用Limit語句指定返回查詢的結果條數時，PageStart及PageSize參數將失效，結果將返回Limit語句指定的條數。
當使用基礎SQL創建API時，SQL腳本中使用Limit限制返回查詢的結果條數，則不支持使用分頁查詢。
注意事項
API的請求參數和返回參數需從同一個服務單元（單物理表服務單元或多物理表服務單元）中獲取，否則后續無法正常調用該API。
基于服務單元編寫SQL語句支持使用MySQL語法，不支持其他SQL語言。
步驟一：選擇生成API的方式
在Dataphin首頁，單擊頂部菜單欄服務 > 開發。
選擇項目，單擊左側導航欄API，在API頁面，單擊+新建API。
在API創建方式選擇對話框中，選擇服務單元API-SQL模式后，單擊確定。
步驟二：配置API參數信息
在新建API頁面，配置API基本信息和參數配置。
API基本信息配置
參數
描述
API名稱
填寫API的名稱。命名規則如下：
只能包含漢字、字母、數字或下劃線（_）。
長度為4~42個字符。
以字母開頭。
全局唯一。
請求方式
API請求方式包括GET和LIST：
GET：請求服務器獲取指定的某個資源。
LIST：請求服務器獲取某一部分的資源。
數據更新頻率
定義API返回數據的更新頻率，便于調用方了解數據的時效性，支持每天、每小時、每分鐘更新API返回的數據。
API分組
選擇API需要歸屬的分組。如需創建，請參見創建服務分組。
結果分頁
當請求方式為List時，支持設置結果分頁。開啟后，請務必指定排序字段，確保返回查詢結果的穩定，避免導致分頁查詢的部分結果重復及丟失；關閉后，API調試或測試頁面不展示分頁參數（PageStart及PageSize），您可以取消選中隱藏參數，展示分頁參數。
描述
填寫對API的簡單描述。不超過128個字符。
協議
僅支持HTTP。HTTP即超文本傳輸協議（HyperText Transfer Protocol），是應用最廣泛的網絡協議。
若網關配置為阿里公有云API網關（專享實例或共享實例）時，支持勾選HTTPS協議，請確保獨立域名的SSL證書有效，避免無法正常調用。請通過選擇平臺管理網絡配置，在網絡配置頁面，進行SSL證書配置。
超時時間
超時時間用于監控API調用的時長。調用API過程中如果超過了設定的超時時間，則調用API時會報錯，便于您及時發現并處理調用API的異常情況。異常情況查看，詳情請參見運維監控概述。
緩存設置
支持開啟或關閉。開啟后需配置緩存時長。默認300（秒），支持設置60秒~1000000秒（約277.78小時）之間的正整數。
版本號
請填寫API的版本號，每份配置信息會有所屬版本號，以便于和上一個版本信息對比。支持輸入不超過64個字符，且該API下版本號唯一。
返回類型
默認JSON。
API請求參數和返回參數配置
在配置API請求參數和返回參數過程中，您需要先確定入參和出參的來源（服務單元），再編寫API SQL并解析出請求參數和返回參數，最后配置請求參數和返回參數的基本信息。
在參數配置區域，選擇模式和服務單元后，系統會為您展示已選服務單元中所有的字段，便于作為編寫API SQL時的參考。
參數
描述
模式
支持Basic或Dev_Prod兩種模式。
Basic模式下開發時、提交及發布線上均讀取生產庫。
Dev-Prod模式下開發及提交讀取開發庫，發布線上讀取生產庫。
服務單元對應字段
支持復制全表字段或單個字段。異常字段用告警
圖標標識，您需要查看該字段所屬的服務單元是否已發布至生產環境或該服務單元是否存在。您可以根據參考示例編寫API SQL。
Dataphin能解析出返回參數和請求參數的SQL腳本模板如下：
模板一：僅查詢和返回服務單元中的字段。
命令格式
select <返回參數> from <服務單元名> where <請求參數>=${請求參數值}使用示例
--在服務單元A中查詢當c=id_card時，返回id_card和name。 select id_card,name from 服務單元A where c=${id_card}
模板二：查詢和返回服務單元包含的字段。
命令格式
select <返回參數> from <服務單元名> where <請求參數> in (${請求參數值})使用示例
--在服務單元A中查詢當c %in% id_card時，返回id_card和name。 select id_card,name from 服務單元A where c in (${id_card})
模板三：字段間支持使用max、sum、min和count聚合函數，同時支持使用like進行模糊匹配。
命令格式
select max(<返回參數1>) as <別名c>,sum(<返回參數1>) as <別名b> ,min(<返回參數1>) as <別名d>,count(*) as <別名e> from <服務單元A> where <請求參數名1> like ${請求參數值1}使用示例
--在服務單元A中查詢字段c %like% id_card時，返回字段a的最大值，參數名為c；返回a的最小值，參數名為d；返回a的總和，參數名為b。 select max(a) as c,sum(a) as b ,min(a) as d,count(*) as e from 服務單元A where c like ${id_card}
模板四：字段間的運算支持+（加法）、-（減法）、 * （乘法）、/（除法）、% （求余數）、 // （整除） **（冪次方），同時支持邏輯運算符and（與）和or（或）。
命令格式
select (<返回參數1>+<返回參數2>) as <別名>，(<返回參數2>+<返回參數3>) as <別名> from <服務單元A> where <字段c>=${請求參數名1} and <字段b>>=${請求參數名2} or <字段c><=${請求參數名3}使用示例
--在服務單元A中查詢當字段c=id_card，或字段b>=num，且字段c<=num1時，返回a+b、b+c的參數值，參數名分別為acd、bcf。 select (a+b) as acd, (b+c) as bcf from 服務單元A where c=${id_card} aor b>=${num} or c<=${num1}
重要上述四種模板中API的請求參數和返回參數需從同一個服務單元（單物理表服務單元或多物理表服務單元）中獲取，否則后續無法正常調用該API。
單擊SQL試運行，在請求參數輸入對話框中，輸入試運行輸入值，單擊確認后即試跑運行SQL。
運行日志：支持查看SQL試運行實際執行的SQL語句。
試運行輸入值：需要配置成綁定字段的字段值，可以在數據預覽頁面選擇綁定字段的字段值。
單擊解析參數后，Dataphin會自動解析出API SQL的入參和出參，并分別添加至請求參數和返回參數區域。請求參數和返回參數的基本信息基本一致，下表為您介紹請求參數和返回參數的基本信息及需要您配置的信息。
參數
描述
參數名
對外開放的參數。
參數類型
參數類型包括Double、Float、String、Date、Boolean、Int、Long、Short、Byte、BigDecimal、Binary。您需要選擇參數名對應的綁定字段的參數類型。
服務單元字段類型與請求參數字段類型保持一致，您選擇對應的字段類型即可。
示例
填寫請求參數值和返回參數值的示例，便于開發者理解。輸入不超過50個字符。
是否必填
選擇請求參數是否為調用API時的必填參數。
選擇為否：調用API的語句中沒有該參數也可以執行調用API的SQL語句。
選擇為是：調用API的語句中沒有該參數，無法執行調用API的SQL語句。
例如，請求參數為id，請求參數為必填參數，返回參數為name；則執行以下語句會有不同的返回：
seclect name from tableA where id=5；：則返回對應的name字段及數據結果。seclect name from tableA;：則SQL語句執行報錯。
描述
填寫對請求參數和返回參數的簡單描述。支持輸入不超過100個字符。
單擊提交，系統將校驗API引用的字段在所屬的服務單元中是否存在，校驗通過后，完成API的生成。