資料服務支援通過嚮導模式或指令碼模式產生API,相對於指令碼模式,您無需編碼能力,可以可視化地配置API。本文為您介紹如何通過嚮導模式產生API。
前提條件
配置API前,請先在配置資料來源。
頁面配置資料來源。詳情請參見背景資訊
如果您存在個人化查詢需求,您可以通過自訂SQL指令碼模式建立API,自行編寫API的查詢語句。在指令碼模式下,支援多表關聯、複雜查詢和彙總函式等功能。例如,當請求參數為某欄位區間時,您可以使用指令碼模式配置API。
進入資料服務頁面
登入DataWorks控制台,切換至目標地區後,單擊左側導覽列的資料服務,在下拉框中選擇對應工作空間後單擊進入資料服務。
產生API
在服務開發頁面,滑鼠移至上方至表徵圖,單擊 。
您也可以開啟相應的商務程序,按右鍵API,選擇
。在產生API對話方塊中,配置各項參數。
參數
描述
API模式
包括嚮導模式和指令碼模式,此處選擇嚮導模式。
API名稱
支援中文、英文、數字、底線(_),且只能以英文或中文開頭,4~50個字元。
API Path
API存放的路徑,即相對於服務host,API的請求路徑。例如/user。
說明支援英文、數字、底線(_)和連字號(-),且只能以( /) 開頭,不得超過200個字元。
協議
支援HTTP和HTTPS。
如果您需要通過HTTPS協議調用API,請您發布API至網關後,在API Gateway控制台綁定獨立網域名稱,並上傳SSL認證。詳情請參見支援HTTPS。
請求方式
支援GET和POST。
說明當請求方式選擇GET時,請求參數位置僅支援選擇QUERY。當請求方式選擇POST時,請求參數位置支援選擇QUERY和BODY。
傳回型別
僅支援JSON傳回型別。
可見範圍
包括工作空間和私人:
工作空間:該API對本工作空間內的所有成員可見。
私人:該API僅對API的負責人可見,且暫不支援授權。
說明如果設定可見範圍為私人,在分類樹中,僅自己可見,工作空間內的其他成員不可見。
標籤
從標籤列表中選擇相應的標籤,詳情請參見建立及管理API標籤。
說明標籤名稱支援漢字、英文、數字和底線(_),您最多可以設定5個標籤,且每個標籤不超過20個字元。
描述
對API進行簡要描述,不得超過2000個字元。
目標檔案夾
存放API的目錄,可以在下拉式清單選擇已建立的商務程序,選定後,會產生API的存放路徑。預設格式為:“商務程序/商務程序名稱/API”,例如商務程序/ceshi/API。
單擊確定。
配置API
雙擊開啟API的編輯頁面,在選擇表地區,配置資料來源類型、資料來源名稱、資料來源環境、資料表名稱等參數。
不同資料來源類型的配置參數略有不同,具體配置參數以介面為準。
說明您需要提前在Data Integration中配置好資料來源,資料表下拉式清單支援表名搜尋。
標準模式工作空間支援在資料來源環境配置項選擇訪問開發或生產環境資料來源,詳情請參見必讀:簡單模式和標準模式的區別。
對於MaxCompute類的資料來源表,您可以使用DataWorks資料服務的加速服務,或MaxCompute的MCQA加速服務進行加速,選擇加速服務進行加速時,您需要先建立加速項,操作詳情請參見加速服務。
建立好API後,會自動跳轉至資料表配置頁面,您可以直接進行配置。
在選擇參數地區,佈建要求參數和返回參數。
您選擇資料表後,選擇參數地區會自動顯示該表的所有欄位。根據自身需求,分別選中相應的欄位設為請求參數和設為返回參數,添加至請求參數和返回參數列表中。
如果您需要對欄位進行排序,單擊相應欄位後的添加到欄位排序,將其添加至排序欄位列表中。
您可以根據資料表中的指定欄位對API的返回結果進行排序。當您的排序列表中有多個欄位時,序號越小的欄位,排序的優先順序越高,您可以通過上移和下移操作來調整排序欄位的優先順序。對於每個排序欄位,您均可以選擇升序或降序的方式進行排序。
單擊API編輯頁面右側的請求參數,配置各項參數。
說明進行結果預覽前請設定API參數的樣本值、預設值、描述等資訊。
盡量設定有索引的欄位為請求參數。
參數
描述
參數名稱
請求參數的名稱,支援英文、數字、底線、連字號(-),且僅支援以英文開頭,不能超過64個字元。
綁定欄位
預設不可以修改。如果您需要修改綁定欄位,請使用指令碼模式。詳情請參見:通過指令碼模式產生API。
參數類型
包括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格式)
操作符
操作符用於表示請求參數和實際賦值之間的關聯和比較。您可以選擇以下操作符:
等於:請求參數等於實際賦值。
LIKE:為請求參數搜尋某種指定模式。
IN:為請求參數規定賦值集合。
NOT IN:請求參數不在賦值集合中。
NOT LIKE:請求參數不在該指定模式中。
!=:請求參數不等於實際賦值。
>:請求參數大於實際賦值。
<:請求參數小於實際賦值。
>=:請求參數大於或等於實際賦值。
<=:請求參數小於或等於實際賦值。
說明當選擇表地區的資料來源類型配置為Table Store時,操作符僅支援選擇等於。
是否必填
該請求參數是否必填。
樣本值
該請求參數的樣本值。
預設值
該請求參數的預設值。
描述
該請求參數的簡要說明。
單擊API編輯頁面右側的返回參數,配置各項參數。
配置返回參數。
參數
描述
參數名稱
返回參數的名稱,支援英文、數字、底線、連字號(-),且僅支援以英文開頭,不能超過64個字元。
綁定欄位
預設不可以修改。
參數類型
包括STRING、INT、LONG、FLOAT、DOUBLE和BOOLEAN。
樣本值
該返回參數的樣本值。
描述
該返回參數的簡要說明。
在進階配置地區,設定是否返回結果分頁。
如果不開啟返回結果分頁,則API預設最多返回2000條記錄。
如果返回結果可能超過2000條,請開啟返回結果分頁功能,開啟後,您可以進入右側導覽列的服務資源群組頁面,根據資源群組類型設定單頁條數上限。
開啟返回結果分頁後,會自動增加以下公用參數:
公用請求參數
pageNum:當前頁號。
pageSize:頁面大小,即每頁記錄數。
公用返回參數
pageNum:當前頁號。
pageSize:頁面大小,即每頁記錄數。
totalNum:總記錄數。
說明API允許不佈建要求參數,當無請求參數時,必須開啟返回結果分頁。
配置過濾器。
當您需要對API的請求參數進行預先處理或對查詢結果進行二次加工時,您可以在API編輯頁面的右側導覽列中,單擊過濾器,根據需要勾選使用前置過濾器或使用後置過濾器,並選擇函數類型後,單擊前置過濾器或後置過濾器右側的下拉框選擇目標函數(可添加多個函數,執行時會按添加順序對參數進行處理),完成後,您可以單擊API返回結果預覽查看使用過濾器後的結果是否符合預期。建立和使用過濾器詳情請參見:建立Aviator函數、建立Python函數。
說明當使用Python函數作為過濾器時,請先開通DataWorks專業版及以上版本,並使用公用資料服務資源群組。
當使用Aviator函數作為過濾器時,無DataWorks版本限制,但需要使用獨享資料服務資源群組。
若在過濾器的下拉式清單中無法擷取目標函數,請檢查目標函數是否發行,或嘗試建立函數並發布。發布函數
佈建服務資源群組。
在API編輯頁面的右側導覽列中,單擊服務資源群組,您可以在資源群組類型地區配置API調用時使用的資源群組類型。
支援您選擇獨享服務資源群組或公用服務資源群組,獨享服務資源群組可以在列表中選擇目標資源群組名稱。公用服務資源群組不可選擇資源群組名稱,由DataWorks內部自動維護。
說明若在列表中無法選中目標資源群組名稱,請進入DataWorks控制台通過“修改歸屬工作空間”將資源群組與工作空間進行綁定。
在環境配置地區,您可設定記憶體、逾時時間和單次請求資料條數上限。
所選DataWorks服務資源群組和API Gateway執行個體的類型不同,允許設定的逾時時間上限不同:
API Gateway共用執行個體:公用服務資源群組不超過30000ms,獨享資料服務資源群組不超過30000ms。
API Gateway專享執行個體:公用服務資源群組不超過30000ms,獨享資料服務資源群組不超過90000ms。
所選服務資源群組類型不同,允許設定的單頁條數上限不同:
如果選擇公用服務資源群組,開啟分頁後的每頁資料記錄最多支援2000條。
如果選擇獨享服務資源群組,開啟分頁後的每頁資料記錄最多支援10000條。
單擊工具列中的表徵圖,儲存API後,所選資源群組將在測試時生效。
配置API後,您可以對其進行測試。詳情請參見測試API。
測試成功後,單擊右上方的提交。
在API編輯頁面的右側導覽列中,單擊版本,找到待申請版本單擊申請發布跳轉到申請頁面,申請類型預設為發布資料服務API,填寫申請原因後單擊申請許可權完成發布申請。
說明工作空間定義審批流後需要走流程審批才發行就緒API,詳情請參見:核准中心概述
發布API後,服務資源群組的配置即可在調用API時生效。
您還可以在服務開發頁面左側分類樹中對目標API進行複製和刪除等操作。您也可以在服務管理頁面,展開API列表,查看發行API的詳情。詳情請參見查看、刪除、移動、複製、大量操作、程式碼搜尋API
轉換嚮導模式為指令碼模式
您可以轉換嚮導模式產生的API為指令碼模式:
在服務開發頁面,展開目標API所在的 。
雙擊相應的API名稱,開啟該API的編輯頁面。
單擊工具列中的表徵圖。
在提示對話方塊中,單擊確認,您可以在編寫查詢SQL地區,查看轉換後的SQL語句。
重要資料服務僅支援轉換嚮導模式配置的API為指令碼模式。
嚮導模式轉換為指令碼模式後,無法回退至嚮導模式。