通過(guò)直連數(shù)據(jù)源模式創(chuàng)建API
直連數(shù)據(jù)源模式是通過(guò)SQL直接從數(shù)據(jù)源創(chuàng)建API。本文為您介紹如何使用直連數(shù)據(jù)源模式生成API。
權(quán)限說(shuō)明
支持服務(wù)的項(xiàng)目管理員和開(kāi)發(fā)用戶可以生成API。
使用說(shuō)明
在API調(diào)用時(shí)，若數(shù)據(jù)源本身支持分頁(yè)，且API請(qǐng)求方式為L(zhǎng)ist，則無(wú)論是否開(kāi)啟分頁(yè)查詢，均可使用PageStart及PageSize設(shè)置分頁(yè)。
當(dāng)使用高級(jí)SQL模式創(chuàng)建API時(shí)，若在SQL腳本中使用Limit限制返回查詢的結(jié)果條數(shù)，則在API調(diào)用時(shí)，參數(shù)中指定的OrderByList僅針對(duì)Limit返回的數(shù)據(jù)進(jìn)行排序，即Limit優(yōu)先級(jí)高于OrderByList。例如：將phone_no排名前10的數(shù)據(jù)再根據(jù)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--調(diào)用時(shí)添加OrderByList的執(zhí)行語(yǔ)句當(dāng)使用基礎(chǔ)SQL創(chuàng)建API時(shí)，SQL腳本中使用Limit限制返回查詢的結(jié)果條數(shù)，則不支持使用分頁(yè)查詢。
步驟一：選擇生成API的方式
在Dataphin首頁(yè)，在頂部菜單欄選擇服務(wù) > 開(kāi)發(fā)。
在左上角選擇項(xiàng)目，單擊左側(cè)導(dǎo)航欄API，然后在API頁(yè)面，單擊+新建API。
在API創(chuàng)建方式選擇對(duì)話框中，選擇直連數(shù)據(jù)源模式-SQL模式后，單擊確定。
步驟二：配置API參數(shù)信息
在新建API頁(yè)面，配置API基本信息和參數(shù)配置。
API基本信息配置
參數(shù)
描述
API名稱
填寫API的名稱。命名規(guī)則如下：
支持中文、字母、數(shù)字或下劃線（_）。
長(zhǎng)度為4~42個(gè)字符。
必須以中文、英文開(kāi)頭。
全局唯一。
請(qǐng)求方式
API請(qǐng)求方式包括GET和LIST：
GET：請(qǐng)求服務(wù)器獲取指定的某個(gè)資源。
LIST：請(qǐng)求服務(wù)器獲取某一部分的資源。
API分組
選擇API需要?dú)w屬的分組。如需創(chuàng)建，請(qǐng)參見(jiàn)創(chuàng)建服務(wù)分組。
描述
填寫對(duì)API的簡(jiǎn)單描述。不超過(guò)128個(gè)字符。
協(xié)議
僅支持HTTP。HTTP即超文本傳輸協(xié)議（HyperText Transfer Protocol），是應(yīng)用最廣泛的網(wǎng)絡(luò)協(xié)議。
若網(wǎng)關(guān)配置為阿里公有云API網(wǎng)關(guān)（專享實(shí)例或共享實(shí)例）時(shí)，支持選擇HTTPS協(xié)議，請(qǐng)確保獨(dú)立域名的SSL證書有效，避免無(wú)法正常調(diào)用。請(qǐng)通過(guò)選擇平臺(tái)管理網(wǎng)絡(luò)配置，在網(wǎng)絡(luò)配置頁(yè)面，進(jìn)行SSL證書配置。
超時(shí)時(shí)間
超時(shí)時(shí)間用于監(jiān)控API調(diào)用的時(shí)長(zhǎng)。調(diào)用API過(guò)程中如果超過(guò)了設(shè)定的超時(shí)時(shí)間，則調(diào)用API時(shí)會(huì)報(bào)錯(cuò)，便于您及時(shí)發(fā)現(xiàn)并處理調(diào)用API的異常情況。關(guān)于異常情況的查看，詳情請(qǐng)參見(jiàn)查看及管理運(yùn)維監(jiān)控API。
最大返回條數(shù)
API最大的返回條數(shù)為10000條。支持輸入1~10000之間的正整數(shù)。當(dāng)請(qǐng)求方式選擇為LIST時(shí)顯示該配置項(xiàng)。
緩存設(shè)置
支持開(kāi)啟或關(guān)閉。開(kāi)啟后需配置緩存時(shí)長(zhǎng)。默認(rèn)300sec（秒），支持設(shè)置60秒~1000000秒（約277.78小時(shí)）之間的正整數(shù)。
版本號(hào)
請(qǐng)?zhí)顚慉PI的版本號(hào)，每份配置信息會(huì)有所屬版本號(hào)，以便于和上個(gè)版本信息對(duì)比。該API下版本號(hào)唯一。命名規(guī)則如下：
不超過(guò)64個(gè)字符。
支持輸入大小英文字母、數(shù)字、下劃線（_）、半角句號(hào)（.）、短劃線（-）。
返回類型
默認(rèn)JSON。
API請(qǐng)求參數(shù)和返回參數(shù)配置
在配置API請(qǐng)求參數(shù)和返回參數(shù)過(guò)程中，您需要先確定輸入?yún)?shù)和輸出參數(shù)的來(lái)源表，再編寫API SQL并解析出請(qǐng)求參數(shù)和返回參數(shù)，最后配置請(qǐng)求參數(shù)和返回參數(shù)的基本信息。
在參數(shù)配置區(qū)域，確定輸入?yún)?shù)和輸出參數(shù)的來(lái)源表，并根據(jù)參考示例編寫API SQL腳本。
參數(shù)
描述
模式
選擇數(shù)據(jù)來(lái)源環(huán)境，支持Basic或Dev-Prod。
Basic模式下開(kāi)發(fā)時(shí)、提交及發(fā)布線上均讀取生產(chǎn)庫(kù)。
Dev-Prod模式下開(kāi)發(fā)及提交讀取開(kāi)發(fā)庫(kù)，發(fā)布線上讀取生產(chǎn)庫(kù)。
數(shù)據(jù)源
選擇數(shù)據(jù)源類型及該類型的數(shù)據(jù)源。包含IMPALA、Oracle、MySQL、Elasticsearch、PostgreSQL、Microsoft SQL Server、Hologres、Lindorm（寬表）、ClickHouse、StarRocks、SAP HANA、DM、SelectDB。
說(shuō)明MySQL支持MySQL5.1.43、MySQL5.6/5.7和MySQL8版本。
SQL模式
支持選擇基礎(chǔ)SQL和高級(jí)SQL兩種模式。
結(jié)果分頁(yè)
當(dāng)請(qǐng)求方式為L(zhǎng)ist時(shí)，支持設(shè)置結(jié)果分頁(yè)。開(kāi)啟后，請(qǐng)務(wù)必指定排序字段，確保返回查詢結(jié)果的穩(wěn)定，避免導(dǎo)致分頁(yè)查詢的部分結(jié)果重復(fù)及丟失；關(guān)閉后，API調(diào)試或測(cè)試頁(yè)面不展示分頁(yè)參數(shù)（PageStart及PageSize），您可以取消選中隱藏參數(shù)，展示分頁(yè)參數(shù)。
排序優(yōu)先級(jí)
當(dāng)SQL模式選擇基礎(chǔ)SQL時(shí)，可以選擇排序的優(yōu)先級(jí)順序，支持選擇SQL腳本或OrderByList請(qǐng)求參數(shù)。
SQL腳本：若SQL腳本指定了排序，則公共請(qǐng)求參數(shù)中的OrderByList不生效。
OrderByList請(qǐng)求參數(shù)：在測(cè)試或調(diào)試API時(shí)，SQL腳本中定義的排序與OrderByList公共請(qǐng)求參數(shù)同時(shí)生效，OrderByList公共請(qǐng)求參數(shù)的優(yōu)先級(jí)高于API中定義的排序設(shè)置。
當(dāng)SQL模式選擇高級(jí)SQL時(shí)，在測(cè)試或調(diào)試API時(shí)，SQL腳本中定義的排序與OrderByList公共請(qǐng)求參數(shù)同時(shí)生效，OrderByList公共請(qǐng)求參數(shù)的優(yōu)先級(jí)高于API中定義的排序設(shè)置。
API SQL腳本編輯
支持同一數(shù)據(jù)源下的單表查詢、多表關(guān)聯(lián)查詢和嵌套查詢。
PostgreSQL數(shù)據(jù)源類型不支持跨Schema。
不支持以下用法：
不支持多條SQL語(yǔ)句。
不支持INSERT、UPDATE、CREATE和DELETE等非SELECT語(yǔ)法。
不支持
SELECT *，查詢時(shí)必須明確指定查詢的列。不支持在SQL語(yǔ)句里設(shè)置參數(shù)的可選項(xiàng)。
如果SELECT查詢列的列名帶有表名前綴（例如
t.name），則必須取別名作為返回參數(shù)名（例如t.name as name）。如果使用聚合函數(shù)（MIN、MAX、SUM和COUNT等），必須取別名作為返回參數(shù)名。例如
sum(num) as total_num。支持在SELECT區(qū)域配置參數(shù)，例如
select id_card, sum(case when id_card like ${id_card} then 1 else 0 end) as proj_score from 數(shù)據(jù)表A where c like ${id_card} group by id_card。不支持在SQL中使用分頁(yè)語(yǔ)句，需通過(guò)分頁(yè)參數(shù)實(shí)現(xiàn)分頁(yè)。
說(shuō)明數(shù)據(jù)源類型為TDengine和SAP HANA時(shí)，需要在SQL中使用分頁(yè)語(yǔ)句，定義分頁(yè)參數(shù)。
高級(jí)SQL模式支持傳參的方式動(dòng)態(tài)指定SQL語(yǔ)句查詢返回的字段，參數(shù)名必須以var_cols開(kāi)頭（格式：var_cols_xxx），并將參數(shù)寫在查詢語(yǔ)句內(nèi)，返回參數(shù)中需要將所有可支持的字段添加為返回參數(shù)。調(diào)用API時(shí)，在動(dòng)態(tài)參數(shù)中傳入需要查詢的字段即可，未傳入的字段在返回結(jié)果中為null值。例如：
API的SQL語(yǔ)句：
select id,${var_cols_args} from table1。var_cols_args參數(shù)傳入值：
name,age,old。API實(shí)際執(zhí)行的SQL語(yǔ)句：
select id,name,age,old from table1。
數(shù)據(jù)源類型為Elasticsearch時(shí)：
當(dāng)不指定scrollId時(shí)，最多只能查詢前10000條數(shù)據(jù)，調(diào)用設(shè)置分頁(yè)P(yáng)ageStart和PageSize時(shí)，請(qǐng)注意不要查詢超過(guò)10000條數(shù)據(jù)，否則調(diào)用會(huì)失敗。
例如：PageStart設(shè)置為9998，PageSize最大只能設(shè)置為2。
如果要查詢10000條以后的數(shù)據(jù)，需要使用where語(yǔ)句指定scrollId，可以在API開(kāi)發(fā)時(shí)指定一個(gè)請(qǐng)求參數(shù)scrollId，查詢時(shí)傳入對(duì)應(yīng)的scrollId值。
說(shuō)明指定了scrollId值查詢時(shí)，就不能使用分頁(yè)，即PageStart和PageSize不能傳值，否則調(diào)用失敗。
目前，只支持scrollId這個(gè)字段作為條件查詢，其余字段不生效。例如：
select a from table where scrollId=${scrollId}。
參考示例
Dataphin能解析出返回參數(shù)和請(qǐng)求參數(shù)的SQL腳本模板如下：
基礎(chǔ)SQL示例：
模板一：
select id_card,name from 數(shù)據(jù)表A where c=${id_card}模板二：
select id_card,name from 數(shù)據(jù)表A where c in (${id_card})模板三：
select max(a) as c,sum(a) as b ,min(a) as d,count(*) as e from 數(shù)據(jù)表A where c like ${id_card}模板四：
select t.name as name from 數(shù)據(jù)表A c=${id_card}模板五：
select (a+b) as acd，(b+c) as bcf from 數(shù)據(jù)表A where c=${id_card} and/or b>=${num} and/or c<=${num1}模板六：
select id_card, sum(case when name like ${name} then 1 else 0 end) as proj_score from 數(shù)據(jù)表A where c=${id_card} group by id_card
高級(jí)SQL示例：
示例一：
select id from 數(shù)據(jù)表 <where> <if test="name != null "> AND age > ${age} </if> <if test="name == null"> AND age < ${age} </if> </where>示例二：
select id from 數(shù)據(jù)表 <where> <if test="name != null "> AND age > #{age} </if> <if test="name == null"> AND age < #{age} </if> </where>
格式化
支持對(duì)SQL語(yǔ)句格式化處理展示，僅支持對(duì)基礎(chǔ)SQL。
字段參考
在字段參考面板中，為您展示已選擇數(shù)據(jù)表中的所有字段。支持復(fù)制表名稱、全表字段或單個(gè)字段。異常字段用告警
圖標(biāo)標(biāo)識(shí)，您需要查看該字段所屬的服務(wù)單元是否已發(fā)布至生產(chǎn)環(huán)境或該服務(wù)單元是否存在。單擊SQL試運(yùn)行，在請(qǐng)求參數(shù)輸入對(duì)話框中，選擇參數(shù)類型、操作符和試運(yùn)行輸入值，然后單擊確認(rèn)。
運(yùn)行日志：支持查看SQL試運(yùn)行實(shí)際執(zhí)行的SQL語(yǔ)句。
試運(yùn)行輸入值：需要配置成綁定字段的字段值，可以在數(shù)據(jù)預(yù)覽頁(yè)面選擇綁定字段的字段值。
單擊解析參數(shù)，Dataphin會(huì)自動(dòng)解析出API SQL的入?yún)⒑统鰠⒉⒎謩e添加至請(qǐng)求參數(shù)和返回參數(shù)區(qū)域。若SQL模式選擇高級(jí)SQL，支持勾選保留手動(dòng)配置，當(dāng)修改SQL腳本需再次解析參數(shù)時(shí)，系統(tǒng)將保留已填寫的參數(shù)信息；如需刪除無(wú)用參數(shù)信息，請(qǐng)手動(dòng)刪除。適用于復(fù)雜的SQL語(yǔ)句參數(shù)無(wú)法解析，需手動(dòng)填寫參數(shù)信息的場(chǎng)景。
請(qǐng)求參數(shù)和返回參數(shù)的基本信息基本一致，下表介紹請(qǐng)求參數(shù)和返回參數(shù)的基本信息說(shuō)明。
參數(shù)
描述
參數(shù)名
顯示對(duì)外開(kāi)放的參數(shù)名。
參數(shù)類型
參數(shù)類型包括DOUBLE、FLOAT、STRING、DATE(yyyy-MM-dd HH:mm:ss)、BOOLEAN、INT、LONG、SHORT、BYTE、BIGDECIMAL和BINARY，需選擇參數(shù)名對(duì)應(yīng)的綁定字段的參數(shù)類型。
如果邏輯表的字段類型不在待選參數(shù)類型范圍內(nèi)，推薦選擇String。
操作符
選擇您所需的操作符。
說(shuō)明expr代表高級(jí)SQL中標(biāo)簽參數(shù)表達(dá)式。
示例
填寫請(qǐng)求參數(shù)值和返回參數(shù)值的示例，便于開(kāi)發(fā)者理解。支持輸入不超過(guò)50個(gè)字符。
描述
填寫對(duì)請(qǐng)求參數(shù)和返回參數(shù)的簡(jiǎn)單描述。支持輸入不超過(guò)100個(gè)字符。
是否必填
選擇請(qǐng)求參數(shù)是否為調(diào)用API時(shí)的必填參數(shù)。
選擇為否：調(diào)用API的語(yǔ)句中沒(méi)有該參數(shù)也可以執(zhí)行調(diào)用API的SQL語(yǔ)句。
選擇為是：調(diào)用API的語(yǔ)句中沒(méi)有該參數(shù)，將無(wú)法執(zhí)行調(diào)用API的SQL語(yǔ)句。
例如，請(qǐng)求參數(shù)為id，請(qǐng)求參數(shù)為必填參數(shù)，返回參數(shù)為name；則執(zhí)行以下語(yǔ)句會(huì)有不同的返回：
返回對(duì)應(yīng)的name字段及數(shù)據(jù)：
select name from tableA where id=5；。SQL語(yǔ)句執(zhí)行報(bào)錯(cuò)：
select name from tableA;。
說(shuō)明高級(jí)SQL語(yǔ)句較為復(fù)雜，SQL編譯解析的參數(shù)不一定完整且正確。因此，您可根據(jù)SQL語(yǔ)句對(duì)解析結(jié)果進(jìn)行刪除參數(shù)、新增請(qǐng)求參數(shù)和新增返回參數(shù)操作。
單擊提交，系統(tǒng)將校驗(yàn)API引用的字段在所屬的數(shù)據(jù)源中是否存在，校驗(yàn)通過(guò)后，完成API的生成。
后續(xù)步驟
生成API后，需要對(duì)API進(jìn)行測(cè)試并發(fā)布至數(shù)據(jù)服務(wù)市場(chǎng)，便于后續(xù)應(yīng)用可以調(diào)用API。具體操作，請(qǐng)參見(jiàn)測(cè)試與發(fā)布API。
若需要對(duì)API進(jìn)行刪除、版本管理、轉(zhuǎn)讓負(fù)責(zé)人等操作，請(qǐng)參見(jiàn)查看及管理API。