全部產品
Search
文件中心

DataWorks:通過嚮導模式產生API

更新時間:Dec 10, 2024

資料服務支援通過嚮導模式或指令碼模式產生API,相對於指令碼模式,您無需編碼能力,可以可視化地配置API。本文為您介紹如何通過嚮導模式產生API。

前提條件

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

背景資訊

如果您存在個人化查詢需求,您可以通過自訂SQL指令碼模式建立API,自行編寫API的查詢語句。在指令碼模式下,支援多表關聯、複雜查詢和彙總函式等功能。例如,當請求參數為某欄位區間時,您可以使用指令碼模式配置API。

進入資料服務頁面

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

產生API

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

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

  2. 產生API對話方塊中,配置各項參數。

    參數

    描述

    API模式

    包括嚮導模式指令碼模式,此處選擇嚮導模式

    API名稱

    支援中文、英文、數字、底線(_),且只能以英文或中文開頭,4~50個字元。

    API Path

    API存放的路徑,即相對於服務host,API的請求路徑。例如/user

    說明

    支援英文、數字、底線(_)和連字號(-),且只能以( /) 開頭,不得超過200個字元。

    協議

    支援HTTPHTTPS

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

    請求方式

    支援GETPOST

    說明

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

    傳回型別

    僅支援JSON傳回型別。

    可見範圍

    包括工作空間私人

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

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

      說明

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

    標籤

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

    說明

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

    描述

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

    目標檔案夾

    存放API的目錄,可以在下拉式清單選擇已建立的商務程序,選定後,會產生API的存放路徑。預設格式為:“商務程序/商務程序名稱/API”,例如商務程序/ceshi/API

  3. 單擊確定

配置API

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

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

    說明
    • 您需要提前在Data Integration中配置好資料來源,資料表下拉式清單支援表名搜尋。

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

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

    • 建立好API後,會自動跳轉至資料表配置頁面,您可以直接進行配置。

  2. 選擇參數地區,佈建要求參數和返回參數。

    您選擇資料表後,選擇參數地區會自動顯示該表的所有欄位。根據自身需求,分別選中相應的欄位設為請求參數設為返回參數,添加至請求參數和返回參數列表中。選擇參數

    如果您需要對欄位進行排序,單擊相應欄位後的添加到欄位排序,將其添加至排序欄位列表中。排序

    您可以根據資料表中的指定欄位對API的返回結果進行排序。當您的排序列表中有多個欄位時,序號越小的欄位,排序的優先順序越高,您可以通過上移下移操作來調整排序欄位的優先順序。對於每個排序欄位,您均可以選擇升序降序的方式進行排序。

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

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

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

    請求參數

    參數

    描述

    參數名稱

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

    綁定欄位

    預設不可以修改。如果您需要修改綁定欄位,請使用指令碼模式。詳情請參見:通過指令碼模式產生API

    參數類型

    包括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格式)

    操作符

    操作符用於表示請求參數和實際賦值之間的關聯和比較。您可以選擇以下操作符:

    • 等於:請求參數等於實際賦值。

    • LIKE:為請求參數搜尋某種指定模式。

    • IN:為請求參數規定賦值集合。

    • NOT IN:請求參數不在賦值集合中。

    • NOT LIKE:請求參數不在該指定模式中。

    • !=:請求參數不等於實際賦值。

    • >:請求參數大於實際賦值。

    • <:請求參數小於實際賦值。

    • >=:請求參數大於或等於實際賦值。

    • <=:請求參數小於或等於實際賦值。

    說明

    選擇表地區的資料來源類型配置為Table Store時,操作符僅支援選擇等於

    是否必填

    該請求參數是否必填。

    樣本值

    該請求參數的樣本值。

    預設值

    該請求參數的預設值。

    描述

    該請求參數的簡要說明。

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

    返回參數

    1. 配置返回參數。

      參數

      描述

      參數名稱

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

      綁定欄位

      預設不可以修改。

      參數類型

      包括STRINGINTLONGFLOATDOUBLEBOOLEAN

      樣本值

      該返回參數的樣本值。

      描述

      該返回參數的簡要說明。

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

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

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

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

      • 公用請求參數

        • pageNum:當前頁號。

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

      • 公用返回參數

        • pageNum:當前頁號。

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

        • totalNum:總記錄數。

      說明

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

  5. 配置過濾器。

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

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

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

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

    過濾器

  6. 佈建服務資源群組。

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

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

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

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

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

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

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

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

        說明

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

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

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

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

        說明

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

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

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

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

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

    說明

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

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

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

轉換嚮導模式為指令碼模式

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

  1. 服務開發頁面,展開目標API所在的商務程序 > API

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

  3. 單擊工具列中的轉換指令碼表徵圖。

  4. 提示對話方塊中,單擊確認,您可以在編寫查詢SQL地區,查看轉換後的SQL語句。

    重要
    • 資料服務僅支援轉換嚮導模式配置的API為指令碼模式。

    • 嚮導模式轉換為指令碼模式後,無法回退至嚮導模式。