數據服務支持通過腳本模式或向導模式生成API,相對于向導模式,您可以自行編寫API的查詢SQL,支持多表關聯、復雜查詢和聚合函數等功能,滿足您個性化查詢需求。本文為您介紹如何通過腳本模式生成API。
前提條件
配置API前,請先在配置數據源。
頁面配置數據源。詳情請參見進入數據服務頁面
登錄DataWorks控制臺,單擊左側導航欄的數據服務,在下拉框中選擇對應工作空間后單擊進入數據服務。
生成API
在服務開發頁面,鼠標懸停至圖標,單擊 。
您也可以打開相應的業務流程,右鍵單擊API,選擇
。在生成API對話框中,配置各項參數。
參數
描述
API模式
包括向導模式和腳本模式,此處選擇腳本模式。
SQL模式
包括基礎SQL和高級SQL:
基礎SQL:通過基礎SQL語法來編寫查詢邏輯,與舊版SQL的支持能力一致。
高級SQL:通過支持MyBatis標簽的SQL語法來編寫查詢邏輯。目前支持的標簽類型包括:if、choose、when、otherwise、trim、foreach和where。
API名稱
支持中文、英文、數字、下劃線(_),且只能以英文或中文開頭,4~50個字符。
API Path
API存放的路徑,例如/user。
協議
支持HTTP和HTTPS協議。
如果您需要通過HTTPS協議調用API,請您發布API至網關后,在API網關控制臺綁定獨立域名,并上傳SSL證書。詳情請參見支持HTTPS。
請求方式
支持GET和POST請求方式。
說明當請求方式選擇GET時,請求參數位置僅支持選擇QUERY。當請求方式選擇POST時,請求參數位置支持選擇QUERY和BODY。
返回類型
僅支持JSON返回類型。
可見范圍
包括工作空間和私有:
工作空間:該API對本工作空間內的所有成員可見。
私有:該API僅對API的負責人可見,且暫不支持授權。
說明如果設置可見范圍為私有,在目錄樹中,僅自己可見,工作空間內的其他成員不可見。
標簽
從標簽列表中選擇相應的標簽,詳情請參見創建及管理API標簽。
說明標簽名稱支持漢字、英文、數字和下劃線(_),您最多可以設置5個標簽,且每個標簽不超過20個字符。
描述
對API進行簡要描述,不得超過2000個字符。
目標文件夾
存放API的目錄。
單擊確定。
配置API
雙擊打開API的編輯頁面,在選擇表區域,配置數據源類型和數據源名稱、數據源環境等參數。
不同數據源類型的配置參數略有不同,具體配置參數以界面為準。
說明您需要提前在
中配置好數據源,數據表下拉列表支持表名搜索。必須先選擇一個數據源,并且僅支持同一個數據源的多表關聯查詢。
標準模式工作空間支持在數據源環境配置項選擇訪問開發或生產環境數據源,詳情請參見必讀:簡單模式和標準模式的區別。
對于MaxCompute類的數據源表,您可以使用DataWorks數據服務的加速服務,或MaxCompute的MCQA加速服務進行加速,選擇加速服務進行加速時,您需要先創建加速項,操作詳情請參見加速服務。
在編寫查詢SQL區域,輸入查詢SQL語句。
如果您選擇的是基礎SQL模式,則僅支持普通SQL語法。
說明SELECT查詢的字段為API的返回參數,WHERE條件處的參數為API的請求參數,請使用${}標識請求參數。
輸入SQL語句時,您需要遵循以下規則:
支持同一數據源下的單表查詢、多表關聯查詢和嵌套查詢。
不支持以下語句:
不支持多條SQL語句。
不支持寫入注釋。
不支持INSERT、UPDATE和DELETE等非SELECT語法。
不支持
SELECT \*
,必須明確指定查詢的列。不支持將${param}放在引號中。例如
'${id}'
、'abc${xyz}123'
。如果您有相關需求,請通過concat('abc', ${xyz}, '123’)
實現。不支持設置參數為可選。
如果SELECT查詢列的列名帶有表名前綴(例如t.name),則必須取別名作為返回參數名(例如t.name as name)。
如果使用聚合函數(min、max、sum和count等),必須取別名作為返回參數名。例如
sum(num) as total\_num
。SQL中的${param}統一作為請求參數進行替換,包含字符串中的${param}。當${param}前包含轉義符(\)時,作為普通字符串處理。
如果您選擇的是高級SQL模式,則支持MyBatis標簽語法。
高級SQL支持的Mybatis標簽類型包括if、choose、when、otherwise、trim、foreach和where,您可以借助標簽語法來靈活實現空值校驗、多值遍歷、動態查表、動態排序及聚合等復雜查詢邏輯,常見場景的代碼示例請參見腳本模式實踐:高級SQL(Mybatis語法)示例。
如果在高級SQL中編輯Mybatis標簽時包含了特殊字符,則需要將特殊字符進行轉義處理。常見的轉義處理可參考下表:
特殊字符
轉義字符
含義
>
>
大于
>=
>=
大于等于
<
<
小于
<=
<=
小于等于
&
&
和
'
'
單引號
"
"
雙引號
單擊API編輯頁面右側的請求參數,配置各項參數。
如果您選擇的是高級SQL模式,為了確保API詳情的參數說明與實際調用情況一致,請您根據SQL腳本,手動新增所有請求參數至列表中。
說明進行結果預覽前請設置API參數的示例值、默認值、描述等信息。
盡量設置有索引的字段為請求參數。
參數
描述
參數名稱
請求參數的名稱,支持英文、數字、下劃線、連字符(-),且僅支持以英文開頭,不能超過64個字符。
參數類型
包括STRING、INT、LONG、FLOAT、DOUBLE和BOOLEAN。
參數位置
包括QUERY和BODY。
說明當有一個或多個參數位置選擇BODY時,需要對BODY位置的參數進一步設置Content-Type來定義調用方在消息體中的傳參格式。
Content-Type包括:
application/json;charset=utf-8(JSON格式)
application/xml;charset=utf-8(XML格式)
application/x-www-form-urlencoded;charset=utf-8(FORM格式)
是否必填
該請求參數是否必填。
示例值
該請求參數的示例值。
默認值
該請求參數的默認值。
描述
該請求參數的簡要說明。
單擊API編輯頁面右側的返回參數,配置各項參數。
配置返回參數。
如果您選擇的是高級SQL模式,為了確保API詳情的參數說明與實際調用情況一致,請您根據SQL腳本,手動新增所有返回參數至列表中。
參數
描述
參數名稱
返回參數的名稱,支持英文、數字、下劃線、連字符(-),且僅支持以英文開頭,不能超過64個字符。
參數類型
包括STRING、INT、LONG、FLOAT、DOUBLE和BOOLEAN。
示例值
該返回參數的示例值。
描述
該返回參數的簡要說明。
在高級配置區域,設置是否返回結果分頁。
如果不開啟返回結果分頁,則API默認最多返回2000條記錄。
如果返回結果可能超過2000條,請開啟返回結果分頁功能,開啟后,您可以進入右側導航欄的服務資源組頁面,根據資源組類型設置單頁條數上限。
說明當數據服務的API在編輯頁面右側導航欄的返回參數已經開啟了返回結果分頁,如果您在該API編輯頁面的編寫查詢SQL區域,使用SQL語句配置了
limit
限制(即返回結果的條數限制),則該limit
限制不生效,返回結果的條數限制仍然會以返回結果分頁的配置內容為準。開啟返回結果分頁后,會自動增加以下公共參數:
公共請求參數
returnTotalNum:用于確定單次請求中是否要返回數據總條數。
pageNum:當前頁號。
pageSize:頁面大小,即每頁記錄數。
公共返回參數
pageNum:當前頁號。
pageSize:頁面大小,即每頁記錄數。
totalNum:總記錄數。
說明API允許不設置請求參數,當無請求參數時,必須開啟返回結果分頁。
配置過濾器。
當您需要對API的請求參數進行預處理或對查詢結果進行二次加工時,您可以在API編輯頁面的右側導航欄中,單擊過濾器,根據需要勾選使用前置過濾器或使用后置過濾器,并選擇函數類型后,單擊前置過濾器或后置過濾器右側的下拉框選擇目標函數(可添加多個函數,執行時會按添加順序對參數進行處理),完成后,您可以單擊API返回結果預覽查看使用過濾器后的結果是否符合預期。創建和使用過濾器詳情請參見:創建Aviator函數、創建Python函數。
說明當使用Python函數作為過濾器時,請先開通DataWorks專業版及以上版本,并使用公共數據服務資源組。
當使用Aviator函數作為過濾器時,無DataWorks版本限制,但需要使用獨享數據服務資源組。
若在過濾器的下拉列表中無法獲取目標函數,請檢查目標函數是否已發布,或嘗試新建函數并發布。詳情請參見發布函數。
配置服務資源組。
在API編輯頁面的右側導航欄中,單擊服務資源組,您可以在資源組類型區域配置API調用時使用的資源組類型。
支持您選擇獨享服務資源組或公共服務資源組,獨享服務資源組可以在列表中選擇目標資源組名稱。公共服務資源組不可選擇資源組名稱,由DataWorks內部自動維護。
說明若在列表中無法選中目標資源組名稱,請進入DataWorks控制臺通過“修改歸屬工作空間”將資源組與工作空間進行綁定。
在環境配置區域,您可設置內存、超時時間和單次請求數據條數上限。
所選DataWorks服務資源組和API網關實例的類型不同,允許設置的超時時間上限不同:
API網關共享實例:公共服務資源組不超過30000ms,獨享數據服務資源組不超過30000ms。
API網關專享實例:公共服務資源組不超過30000ms,獨享數據服務資源組不超過90000ms。
所選服務資源組類型不同,允許設置的單頁條數上限不同:
如果選擇公共服務資源組,開啟分頁后的每頁數據記錄最多支持2000條。
如果選擇獨享服務資源組,開啟分頁后的每頁數據記錄最多支持10000條。
單擊工具欄中的圖標,保存API后,所選資源組將在測試時生效。
配置API后,您可以對其進行測試。詳情請參見測試API。
測試成功后,單擊右上方的提交。
在API編輯頁面的右側導航欄中,單擊版本,找到待申請版本單擊申請發布跳轉到申請頁面,申請類型默認為發布數據服務API,填寫申請原因后單擊申請權限完成發布申請。
說明工作空間定義審批流后需要走流程審批才可以發布API,詳情請參見:審批中心概述
發布API后,服務資源組的配置即可在調用API時生效。
您還可以在服務開發頁面左側目錄樹中對目標API進行克隆和刪除等操作。您也可以在服務管理頁面,展開API列表,查看已發布API的詳情。詳情請參見查看、刪除、移動、克隆、批量操作、代碼搜索API