資料服務 (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。

info

一個參數可有多個 Operators。點擊 Add Operation 按鈕，新增 Operator。

Operator 與對應的 Validation Rules 支援項目請參考本章節最下方説明 (標題：支援的 Parameter Operations 與 Validation Rules)

點擊 Add Operation 按鈕，新增 Operator，一個參數可有多個 Operators。

• Response columns : 左側為資料集中可設定的欄位，右側為在此Data Service 設定要回傳的欄位，您可以透過 >與< 來選擇要將哪些欄位加入及移除。

Step 4: 模擬 API 查詢結果

系統會根據您在上一個步驟的設計模擬 API 查詢結果。

info

模擬結果呈現小量資料以達成抽樣驗證。若輸入參數得出大量資料結果，則系統呈現部分資料供檢視。

可點選 Select Parameters 選取在Step 3 設定的其他參數欄位模擬結果。點擊 Select Parameters 按鈕，輸入要模擬查詢的參數。

• Customize SQL : 在這一階段您可以根據自身需求客製化查詢語句，但強烈建議此一操作最好由技術人員執行。輸入客製化 SQL 語法後需再回到前一步驟將設定調整成與剛剛客製化的內容一致，否則 Data Service API 的設計與 API 文件將出現不一致情況。

建議使用 Customize SQL 功能的情境為 : 當上述 Step 3 中無法設定的複雜 Validation rules，可透過 Customize SQL 撰寫語法補充檢核邏輯。但選擇參數欄位請透過 Step 3 操作。

danger

DATA SERVICE API 只支援單一資料集轉換成 API

在 Customize SQL 中您可以對多個資料集進行查詢，但 Data Service API 只支援單一資料集轉換成 API。因此 Customize SQL 中應避免對多個資料集進行查詢，否則此Data Service API 將執行失敗。

info

模擬結果: 當使用 Customize SQL 時，請在SQL 語法中輸入參數以便模擬查詢結果。

Step 5: API 設定完成

回到 Data Services 的頁籤，可以看到剛剛建立的 Data Service API。

• 點擊 View API Docs ，另外開啟 API 文件分頁， 並支援 API 文件下載。
• 編輯與刪除權限，僅限建立者和工作區 owner

info

DATA CONSUMER 只能看到 SEMANTIC 資料

在 Data Services 頁籤中，若使用者為工作區的Data Consumer 角色，將可能無法看到此工作區的所有Data Service APIs。當 Data Service API 的設計是來自於未開啟 semantic 設定 的資料集，則Data Consumer 在此頁籤中無法看到此類的 Data Service API 項目。

danger

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