DataWorks：通過指令碼模式產生API

1. 選擇表

雙擊開啟API的編輯頁面，在選擇表地區，配置數據源類型和數據源名稱、數據源環境等參數。

不同資料來源類型的配置參數略有不同，具體配置參數以介面為準。

2. 編寫查詢SQL

在編寫査詢SQL地區，輸入查詢SQL語句。

• 如果您選擇的是基礎SQL模式，則僅支援普通SQL文法。

  SELECT
  name,
  addr AS address,
  SUM(num) as total_num
  FROM
  table_name
  WHERE
  user_id =${uid}

  說明

  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標籤文法。

  SELECT id, name, create_name
  FROM t_parameter
  <where>
  <if test="'list!=null'">
      id in (
          <foreach collection="list" open="(" close=")" separator="," item="id_num">
              ${id_num}
          </foreach>
      )
  </if>
  </where>

  進階SQL支援的Mybatis標籤類型包括if、choose、when、otherwise、trim、foreach和where，您可以藉助標籤文法來靈活實現空值校正、多值遍曆、動態查表、動態排序及彙總等複雜查詢邏輯，常見情境的程式碼範例請參見指令碼模式：進階SQL（Mybatis文法）樣本。

  如果在進階SQL中編輯Mybatis標籤時包含了特殊字元，則需要將特殊字元進行轉義處理。常見的轉義處理可參考下表：

  特殊字元	逸出字元	含義
  >	>	大於
  >=	>=	大於等於
  <	&lt;	小於
  <=	&lt;=	小於等於
  &	&amp;	和
  '	&apos;	單引號
  "	&quot;	雙引號

3. 配置請求參數

單擊API編輯頁面右側的請求參數，配置各項參數。

如果您選擇的是高級SQL模式，為了確保API詳情的參數說明與實際調用情況一致，請您根據SQL指令碼，手動新增所有請求參數至列表中。

4. 配置返回參數

單擊API編輯頁面右側的返回參數，配置各項參數。

1. 配置返回參數。

   如果您選擇的是高級SQL模式，為了確保API詳情的參數說明與實際調用情況一致，請您根據SQL指令碼，手動新增所有返回參數至列表中。

   參數	描述
   參數名稱	返回參數的名稱，支援英文、數字、底線、連字號（-），且僅支援以英文開頭，不能超過64個字元。
   參數類型	包括STRING、INT、LONG、FLOAT、Double和Boolean。
   示例值	該返回參數的樣本值。
   描述	該返回參數的簡要說明。

2. 在高級配置地區，設定是否返回結果分頁。

   • 如果不開啟返回結果分頁，則API預設最多返回2000條記錄。

   • 如果返回結果可能超過2000條，請開啟返回結果分頁功能，開啟後，您可以進入右側導覽列的服務資源組頁面，根據資源群組類型設定單頁條數上限。

   說明

   當資料服務的API在編輯頁面右側導覽列的返回參數已經開啟了返回結果分頁，如果您在該API編輯頁面的編寫査詢SQL地區，使用SQL語句配置了limit限制（即返回結果的條數限制），則該limit限制不生效，返回結果的條數限制仍然會以返回結果分頁的配置內容為準。

   開啟返回結果分頁後，會自動增加以下公用參數：

   • 公用請求參數

     • returnTotalNum：用於確定單次請求中是否要返回資料總條數。

     • pageNum：當前頁號。

     • pageSize：頁面大小，即每頁記錄數。

   • 公用返回參數

     • pageNum：當前頁號。

     • pageSize：頁面大小，即每頁記錄數。

     • totalNum：總記錄數。

   說明

   API允許不佈建要求參數，當無請求參數時，必須開啟返回結果分頁。

5. 配置過濾器

當您需要對API的請求參數進行預先處理或對查詢結果進行二次加工時，您可以在API編輯頁面的右側導覽列中，單擊過濾器，根據需要勾選使用前置過濾器或使用後置過濾器，並選擇函數類型後，單擊前置過濾器或後置過濾器右側的下拉框選擇目標函數（可添加多個函數，執行時會按添加順序對參數進行處理），完成後，您可以單擊API返回結果預覽查看使用過濾器後的結果是否符合預期。建立和使用過濾器詳情請參見：建立Aviator函數、建立Python函數。

6. 佈建服務資源群組

1. 在API編輯頁面的右側導覽列中，單擊服務資源組，您可以在資源組類型地區配置API調用時使用的資源群組類型。

   支援您選擇獨享服務資源組或公共服務資源組，獨享服務資源組可以在列表中選擇目標資源群組名稱。公共服務資源組不可選擇資源群組名稱，由DataWorks內部自動維護。

   說明

   • 若在列表中未看到目標資源群組名稱，請進入資源群組列表頁，單擊指定資源群組操作列的綁定工作空間，將資源群組與工作空間進行綁定。

   • 若在列表中已展示目標資源群組，但無法選中，請進入資源群組列表頁，單擊指定資源群組操作列的 > 配額管理，手動設定資源群組資料服務用途的當前佔用CU（隨用隨付資源群組設定）或CU保障（訂用帳戶資源群組設定）取值。

2. 在環境配置地區，您可設定記憶體、超時時間和單次請求數據條數上限。

   • 所選DataWorks服務資源群組和API Gateway執行個體的類型不同，允許設定的逾時時間上限不同：

     • API Gateway共用執行個體：公用服務資源群組不超過30000ms，獨享資料服務資源群組不超過30000ms。

     • API Gateway專享執行個體：公用服務資源群組不超過30000ms，獨享資料服務資源群組不超過90000ms。

     說明

     API的回應時間取決於SQL實際的執行時間，請根據實際SQL的執行時間合理配置API超時時間，避免因響應逾時導致請求失敗。

   • 所選服務資源群組類型不同，允許設定的單頁條數上限不同：

     • 如果選擇公用服務資源群組，開啟分頁後的每頁資料記錄最多支援2000條。

     • 如果選擇獨享服務資源群組，開啟分頁後的每頁資料記錄最多支援10000條。

     說明

     API返回結果總數暫無上限控制，返回結果數與實際查詢結果數一致。

7. 儲存並提交

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