資料服務 (Data Services)
Data Service 是一個 API 的資料服務,讓您能夠更輕鬆地建立自定義 API。
透過 "Data Service API",您可以輕鬆地將工作區中的資料集轉化為可用的 API,無需編寫複雜的程式碼,只需使用介面上的選單操作,就能快速建立 API。
Data Service 設定流程步驟
Step 1: 進入 Data Service 頁面
首先,在工作區頁面,進入到 Data Services
的頁籤中。
Step 2: 建立 API 基本資訊
點擊 Create a Data Service
按鈕。
此功能需由工作區Owner 在工作區權限控管中,開放 建立 Data Service 權限予使用者。
設定該 Data Service 的基本資料如下。
Name : 輸入自定義名稱
Select a Dataset : 選取設計所需的資料集
Description : 輸入自定義描述
URL Path : 可輸入自定義字元,系統最終依據系統設定+自定義字元產出 API URL 接口。
Cache 與否: 可設定是否啟用 Cache (預先快取資料) 。若啟用可加速API 取用時間。點擊 Cache
按鈕,顯示可設定的 Cache 排程。
- 排程更新時間:可選擇永不重複 (Does not repeat ) 或定期更新 (Repeats)
- 定期更新時間:可選擇
分
、時
、天
、週
時間單位
完成以上設定後點擊 Next 進入下一步設定。
Step 3: 設定 Parameters, Validation rules, Response Columns
點擊 +
按鈕,新增 Parameter。
可設定多個參數( 即: Parameter),每個參數可設定以下欄位:
- Required : 表示是否為必要參數
- Operator : API Parameters 抓取資料條件選項。(包含equal to / greater than /greater than or equal to / less than / less than or equal to )
- Validation Rules : API Parameters 驗證條件,使用者填入不符合條件規則的參數值時會回傳錯誤。驗證條件可多選,若一個參數有多個條件,則必須同時滿足所有條件,才可成功請求 API。
一個參數可有多個 Operators。點擊 Add Operation
按鈕,新增 Operator。
Operator 與對應的 Validation Rules 支援項目請參考本章節最下方説明 (標題:支援的 Parameter Operations 與 Validation Rules)
點擊 Add Operation
按鈕,新增 Operator,一個參數可有多個 Operators。
- Response columns : 左側為資料集中可設定的欄位,右側為在此Data Service 設定要回傳的欄位,您可以透過
>
與<
來選擇要將哪些欄位加入及移除。
Step 4: 模擬 API 查詢結果
系統會根據您在上一個步驟的設計模擬 API 查詢結果。
模擬結果呈現小量資料以達成抽樣驗證。若輸入參數得出大量資料結果,則系統呈現部分資料供檢視。
可點選 Select Parameters 選取在Step 3 設定的其他參數欄位模擬結果。點擊 Select Parameters
按鈕,輸入要模擬查詢的參數。
- Customize SQL : 在這一階段您可以根據自身需求客製化查詢語句,但強烈建議此一操作最好由技術人員執行。輸入客製化 SQL 語法後需再回到前一步驟將設定調整成與剛剛客製化的內容一致,否則 Data Service API 的設計與 API 文件將出現不一致情況。
建議使用 Customize SQL 功能的情境為 : 當上述 Step 3 中無法設定的複雜 Validation rules,可透過 Customize SQL 撰寫語法補充檢核邏輯。但選擇參數欄位請透過 Step 3 操作。
DATA SERVICE API 只支援單一資料集轉換成 API
在 Customize SQL 中您可以對多個資料集進行查詢,但 Data Service API 只支援單一資料集轉換成 API。因此 Customize SQL 中應避免對多個資料集進行查詢,否則此Data Service API 將執行失敗。
模擬結果: 當使用 Customize SQL 時,請在SQL 語法中輸入參數以便模擬查詢結果。
Step 5: API 設定完成
回到 Data Services
的頁籤,可以看到剛剛建立的 Data Service API。
- 點擊
View API Docs
,另外開啟 API 文件分頁, 並支援 API 文件下載。 - 編輯與刪除權限,僅限建立者和工作區 owner
DATA CONSUMER 只能看到 SEMANTIC 資料
在 Data Services 頁籤中,若使用者為工作區的Data Consumer 角色,將可能無法看到此工作區的所有Data Service APIs。當 Data Service API 的設計是來自於未開啟 semantic 設定 的資料集,則Data Consumer 在此頁籤中無法看到此類的 Data Service API 項目。
DATA SERVICE API 建立者刪除
若 API 建立者的帳號需要從平台移除,需先刪除其底下所有創建的 API,方可完成帳號移除。刪除 Data Service API 可由建立者或工作區Owner 執行。
支援的 Parameter Operations 與 Validation Rules
Parameter 的型別 | Operator | Validation Rules-1 | Validation Rules-2 | Validation Rules-3 |
---|---|---|---|---|
Boolean | eq(=) | x | x | x |
Integer, Fixed-precision, Floating-point | equal to (eq) | Max, Min | x | x |
greater than(gt) | x | x | x | |
greater than and equal to (gte) | x | x | x | |
less than (lt) | x | x | x | |
less than and equal to (lte) | x | x | x | |
String | equal to (eq) | Max, Min | Format (Regex Pattern) | enum |
like | Max, Min | Format (Regex Pattern) | x | |
in | Max, Min | Format (Regex Pattern) | x | |
Date | equal to (eq) | Format(YYYY-MM-DD) | x | x |
greater than(gt) | Format(YYYY-MM-DD) | x | x | |
greater than and equal to (gte) | Format(YYYY-MM-DD) | x | x | |
less than (lt) | Format(YYYY-MM-DD) | x | x | |
less than and equal to (lte) | Format(YYYY-MM-DD) | x | x | |
Timestamp | equal to (eq) | Format(YYYY-MM-DD HH:mm:ss) | x | x |
greater than(gt) | Format(YYYY-MM-DD HH:mm:ss) | x | x | |
greater than and equal to (gte) | Format(YYYY-MM-DD HH:mm:ss) | x | x | |
less than (lt) | Format(YYYY-MM-DD HH:mm:ss) | x | x | |
less than and equal to (lte) | Format(YYYY-MM-DD HH:mm:ss) | x | x |
API 使用資訊
Authorization
使用資料服務前,需要在 Canner Enterprise 先建立 Personal Access Token 並將生成的 Token 複製放置於 Header 中。
Name | Format | Sample |
---|---|---|
Authorization | format("canner-pat %s", PAT) | canner-pat asdsafgwg4gregregergergregerg32 |
Error Handling
常見的 Error 有以下幾種形式。
Status | Description |
---|---|
400 | 參數設定錯誤,例如 Column 不存在此資料服務設定中 |
401 | 授權失敗,例如 Token 資訊填寫錯誤或是讀取未授權的 Workspace |
404 | 找不到該資源,例如沒有該 Workspace 或 Materialized View |