DataWorks：通過資料來源產生API（API Gateway）

前提條件

• 已在工作空間管理 > 數據源管理頁面配置資料來源。詳情請參見配置資料來源。

• 資料服務需提前準備資源群組，生產環境建議使用Serverless資源群組，詳情請參見資源群組與網路連通。

進入資料服務頁面

登入DataWorks控制台，切換至目標地區後，單擊左側導覽列的資料分析與服務 > 資料服務，在下拉框中選擇對應工作空間後單擊進入資料服務。

步驟一：開通API Gateway並建立API分組

在建立商務程序之前，您需要先在API Gateway控制台完成以下準備工作。

1. 登入API Gateway控制台，開通API Gateway服務。

2. 在API Gateway控制台中，建立一個API分組。API分組是指標對某一個功能或情境的API集合，也是API Gateway對API的最小嵌入式管理單元。

   重要

   API Gateway的地區必須與DataWorks工作空間地區一致。

步驟二：建立商務程序

資料服務基於商務程序實現以業務為單元的API開發，每個商務程序需綁定一個API分組。在產生API前，您需要先建立商務程序。

1. 在服務開發頁面，單擊表徵圖，選擇新建業務流程。

2. 在新建業務流程對話方塊中，配置各項參數。

   參數	描述
   業務名稱	在所屬工作空間中必須唯一。支援漢字、英文字母、數字、底線（_），以英文字母或漢字開頭，4~50個字元。
   API 群組	選擇您在步驟一中建立的API分組。如果需要建立分組，請進入API Gateway建立。 重要 商務程序綁定API分組後，不支援修改。請謹慎選擇。
   業務描述	對商務程序進行描述，不能超過180個字元。

3. 單擊確定。建立完成後，您可以在業務流程列表中查看。

步驟三：選擇API建立模式

資料服務支援通過嚮導模式和指令碼模式兩種方式產生API。兩種模式共用相同的API基礎配置流程，但在查詢邏輯的構建方式上有本質區別。

步驟四：產生API

1. 在服務開發頁面，滑鼠移至上方至表徵圖，單擊新建API > 生成API。

   您也可以開啟相應的商務程序，按右鍵API，選擇新建API > 生成API。

2. 在生成API對話方塊中，配置各項參數。

   參數	描述
   API 模式	選擇嚮導模式或腳本模式。選擇指令碼模式時，還需進一步選擇SQL 模式（基礎SQL或高級SQL）。 基礎SQL：通過基礎SQL文法編寫查詢邏輯。 高級SQL：通過支援MyBatis標籤的SQL文法編寫查詢邏輯。支援的標籤類型包括：if、choose、when、otherwise、trim、foreach和where。
   API名稱	支援中文、英文、數字、底線（_），且只能以英文或中文開頭，4~50個字元。
   APIPath	API存放的路徑，即相對於服務host的請求路徑，例如/user。支援英文、數字、底線（_）和連字號（-），以（/）開頭，不超過200個字元。
   協議	支援HTTP和HTTPS。 如果您需要通過HTTPS協議調用API，請您發布API至網關後，在API Gateway控制台綁定獨立網域名稱，並上傳SSL認證。詳情請參見支援HTTPS。
   請求方式	支援GET和POST。 說明 選擇GET時，請求參數位置僅支援QUERY。選擇POST時，支援QUERY和Body。
   返回類型	僅支援JSON傳回型別。
   可見範圍	工作空間：該API對本工作空間內的所有成員可見。 私有：該API僅對API的負責人可見，且暫不支援授權。
   標籤	從標籤列表中選擇，最多5個標籤，每個不超過20個字元。詳情請參見建立及管理API標籤。
   描述	對API進行簡要描述，不超過2000個字元。
   目標文件夾	選擇已建立的商務程序作為API存放目錄。預設格式為："商務程序/商務程序名稱/API"。

3. 單擊確定，進入API編輯頁面。

步驟五：配置API

步驟六：儲存並提交

單擊工具列中的表徵圖，儲存API後，所選資源群組將在測試時生效。

附錄：嚮導模式轉指令碼模式

您可以將嚮導模式產生的API轉換為指令碼模式：

1. 在服務開發頁面，展開目標API所在的業務流程 > API。

2. 雙擊相應的API名稱，開啟該API的編輯頁面。

3. 單擊工具列中的表徵圖。

4. 在提示對話方塊中，單擊確定。

   警告

   • 僅支援將嚮導模式轉換為指令碼模式。

   • 轉換後無法回退至嚮導模式，請謹慎操作。

附錄：進階SQL（MyBatis文法）樣本

以下樣本展示指令碼模式下使用進階SQL編寫複雜查詢邏輯的常見情境。使用時請將表名、欄位和查詢條件替換為您的實際內容。

select col01,col02
from table_name
<choose>
    <when test='var == 1'>
    order by col01
    </when>
    <when test='var == 2'>
    order by col02
    </when>
    <when test='var == 3'>
    order by col01,col02
    </when>
    <when test='var == 4'>
    order by col02,col01
    </when>
</choose>

select col01
from
<choose>
 <when test='var == 1'>
 table_name01
 </when>
 <when test='var == 2'>
 table_name02
 </when>
</choose>

SELECT area_id, area, amount
FROM table_name
<where>
	<if test='list!=null'>
	area in
		<foreach collection="list" open="(" close=")" separator="," item="area">
		#{area}
		</foreach>
	</if>
</where>

附錄：最佳實務 — 選填參數設定

在實際業務中，經常需要部分請求參數為可選——調用方可自行決定是否傳入某個參數值，未傳值時該參數不參與查詢條件。以下以ods_user_info_d表為例，將uid設為必填參數，gender設為選填參數。

SELECT uid, gender, age_range, zodiac
FROM ods_user_info_d
<where>
    <if test='gender!=null'>
    gender = ${gender}
    </if>
    and uid = ${uid}
</where>