跳至主要内容
版本:v4

資料服務 (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 的型別OperatorValidation Rules-1Validation Rules-2Validation Rules-3
Booleaneq(=)xxx
Integer, Fixed-precision, Floating-pointequal to (eq)Max, Minxx
greater than(gt)xxx
greater than and equal to (gte)xxx
less than (lt)xxx
less than and equal to (lte)xxx
Stringequal to (eq)Max, MinFormat (Regex Pattern)enum
likeMax, MinFormat (Regex Pattern)x
inMax, MinFormat (Regex Pattern)x
Dateequal to (eq)Format(YYYY-MM-DD)xx
greater than(gt)Format(YYYY-MM-DD)xx
greater than and equal to (gte)Format(YYYY-MM-DD)xx
less than (lt)Format(YYYY-MM-DD)xx
less than and equal to (lte)Format(YYYY-MM-DD)xx
Timestampequal to (eq)Format(YYYY-MM-DD HH:mm:ss)xx
greater than(gt)Format(YYYY-MM-DD HH:mm:ss)xx
greater than and equal to (gte)Format(YYYY-MM-DD HH:mm:ss)xx
less than (lt)Format(YYYY-MM-DD HH:mm:ss)xx
less than and equal to (lte)Format(YYYY-MM-DD HH:mm:ss)xx

API 使用資訊

Authorization

使用資料服務前,需要在 Canner Enterprise 先建立 Personal Access Token 並將生成的 Token 複製放置於 Header 中。

NameFormatSample
Authorizationformat("canner-pat %s", PAT)canner-pat asdsafgwg4gregregergergregerg32

Error Handling

常見的 Error 有以下幾種形式。

StatusDescription
400參數設定錯誤,例如 Column 不存在此資料服務設定中
401授權失敗,例如 Token 資訊填寫錯誤或是讀取未授權的 Workspace
404找不到該資源,例如沒有該 Workspace 或 Materialized View