全部產品
Search
文件中心

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

更新時間:Jun 19, 2024

資料服務支援通過指令碼模式或嚮導模式產生API,相對於嚮導模式,您可以自行編寫API的查詢SQL,支援多表關聯、複雜查詢和彙總函式等功能,滿足您個人化查詢需求。本文為您介紹如何通過指令碼模式產生API。

前提條件

配置API前,請先在工作空間管理 > 資料來源管理頁面配置資料來源。詳情請參見配置資料來源

進入資料服務頁面

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

產生API

  1. 服務開發頁面,滑鼠移至上方至image.png表徵圖,單擊建立API > 產生API

    您也可以開啟相應的商務程序,按右鍵API,選擇建立API > 產生API

  2. 產生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

    協議

    支援HTTPHTTPS協議。

    如果您需要通過HTTPS協議調用API,請您發布API至網關後,在API Gateway控制台綁定獨立網域名稱,並上傳SSL認證。詳情請參見支援HTTPS

    請求方式

    支援GETPOST請求方式。

    說明

    請求方式選擇GET時,請求參數位置僅支援選擇QUERY。當請求方式選擇POST時,請求參數位置支援選擇QUERYBODY

    傳回型別

    僅支援JSON傳回型別。

    可見範圍

    包括工作空間私人

    • 工作空間:該API對本工作空間內的所有成員可見。

    • 私人:該API僅對API的負責人可見,且暫不支援授權。

      說明

      如果設定可見範圍為私人,在分類樹中,僅自己可見,工作空間內的其他成員不可見。

    標籤

    標籤列表中選擇相應的標籤,詳情請參見建立及管理API標籤

    說明

    標籤名稱支援漢字、英文、數字和底線(_),您最多可以設定5個標籤,且每個標籤不超過20個字元。

    描述

    對API進行簡要描述,不得超過2000個字元。

    目標檔案夾

    存放API的目錄。

  3. 單擊確定

配置API

  1. 雙擊開啟API的編輯頁面,在選擇表地區,配置資料來源類型資料來源名稱資料來源環境等參數。

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

    說明
    • 您需要提前在工作空間管理 > 資料來源管理中配置好資料來源,資料表下拉式清單支援表名搜尋。

    • 必須先選擇一個資料來源,並且僅支援同一個資料來源的多表關聯查詢。

    • 標準模式工作空間支援在資料來源環境配置項選擇訪問開發或生產環境資料來源,詳情請參見必讀:簡單模式和標準模式的區別

    • 對於MaxCompute類的資料來源表,您可以使用DataWorks資料服務的加速服務,或MaxCompute的MCQA加速服務進行加速,選擇加速服務進行加速時,您需要先建立加速項,操作詳情請參見加速服務

  2. 編寫查詢SQL地區,輸入查詢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標籤文法。Mybatis

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

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

      特殊字元

      逸出字元

      含義

      >

      >

      大於

      >=

      >=

      大於等於

      <

      &lt;

      小於

      <=

      &lt;=

      小於等於

      &

      &amp;

      '

      &apos;

      單引號

      "

      &quot;

      雙引號

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

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

    說明
    • 進行結果預覽前請設定API參數的樣本值、預設值、描述等資訊。

    • 盡量設定有索引的欄位為請求參數。

    請求參數

    參數

    描述

    參數名稱

    請求參數的名稱,支援英文、數字、底線、連字號(-),且僅支援以英文開頭,不能超過64個字元。

    參數類型

    包括STRINGINTLONGFLOATDOUBLEBOOLEAN

    參數位置

    包括QUERYBODY

    說明

    當有一個或多個參數位置選擇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格式)

    是否必填

    該請求參數是否必填。

    樣本值

    該請求參數的樣本值。

    預設值

    該請求參數的預設值。

    描述

    該請求參數的簡要說明。

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

    返回參數

    1. 配置返回參數。

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

      參數

      描述

      參數名稱

      返回參數的名稱,支援英文、數字、底線、連字號(-),且僅支援以英文開頭,不能超過64個字元。

      參數類型

      包括STRINGINTLONGFLOATDOUBLEBOOLEAN

      樣本值

      該返回參數的樣本值。

      描述

      該返回參數的簡要說明。

    2. 進階配置地區,設定是否返回結果分頁

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

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

      說明

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

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

      • 公用請求參數

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

        • pageNum:當前頁號。

        • pageSize:頁面大小,即每頁記錄數。

      • 公用返回參數

        • pageNum:當前頁號。

        • pageSize:頁面大小,即每頁記錄數。

        • totalNum:總記錄數。

      說明

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

  5. 配置過濾器。

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

    說明
    • 當使用Python函數作為過濾器時,請先開通DataWorks專業版及以上版本,並使用公用資料服務資源群組。

    • 當使用Aviator函數作為過濾器時,無DataWorks版本限制,但需要使用獨享資料服務資源群組。

    • 若在過濾器的下拉式清單中無法擷取目標函數,請檢查目標函數是否發行,或嘗試建立函數並發布。詳情請參見發布函數

    過濾器

  6. 佈建服務資源群組。

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

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

      說明

      若在列表中無法選中目標資源群組名稱,請進入DataWorks控制台通過“修改歸屬工作空間”將資源群組與工作空間進行綁定。

    2. 環境配置地區,您可設定記憶體逾時時間單次請求資料條數上限

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

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

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

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

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

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

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

    配置API後,您可以對其進行測試。詳情請參見測試API

    測試成功後,單擊右上方的提交

    在API編輯頁面的右側導覽列中,單擊版本,找到待申請版本單擊申請發布跳轉到申請頁面,申請類型預設為發布資料服務API,填寫申請原因後單擊申請許可權完成發布申請。

    說明

    工作空間定義審批流後需要走流程審批才發行就緒API,詳情請參見:核准中心概述

    發布API後,服務資源群組的配置即可在調用API時生效。

    您還可以在服務開發頁面左側分類樹中對目標API進行複製和刪除等操作。您也可以在服務管理頁面,展開API列表,查看發行API的詳情。詳情請參見查看、刪除、移動、複製、大量操作、程式碼搜尋API