API使用說明

一、政府計畫資料庫(以下簡稱本平臺)之API資料服務，為在有限的資源下提供使用者穩定的資料服務水準、提升服務品質以及加強資訊安全管理，故本平臺導入會員及API管理機制。

二、當會員介接API服務時，須帶入APP ID與APP Key加上當下的時間戳記組成之簽章始取得服務。歡迎先至API使用範例網站(Swagger)輸入APP ID 及APP Key進行測試。

三、APP ID為會員申請API服務時，系統自動產生之唯一識別身份值；APP Key則為該APP ID對應之加密憑證。

四、API使用範例網站(Swagger)使用說明

1.請於Swagger右上角輸入APP ID與APP Key並按下Explore。

2.點選任一API服務進行測試，API說明如下：

API服務	說明
/DatasetList	可查詢使用者可取得之資料集清單
/SchemaInfoApi/{Dsno}	輸入資料集編號，可取得該資料集欄位
/Dataset/{Dsno}	輸入資料集編號，可取得資料內容

3.以/DatasetList為例，點選該服務並點擊Try it out!，即可於Response Body瀏覽API呼叫結果。

4.最後透過/DatasetList 所取得的 Dsno 欄位內容，即可至/SchemaInfoApi/{Dsno}或/Dataset/{Dsno}服務取得資料內容。

五、 API授權驗證

1. 本平臺採用HMAC認證授權機制，以HMAC簽章驗證使用者的身份，用戶在請求API服務時，將APP Key 與當下時間（格式請使用GMT時間）做HMAC-SHA256 運算後轉成Base64 格式，帶入signature屬性欄位，服務器端將驗證用戶請求時的header欄位，驗證使用者身份及請求服務的時效性。

2. HMAC Signature簽章時效性：於使用範例網站(Swagger)測試時，請在最上方輸入APP ID與APP Key (請再次確認是否有將APP ID與APP Key填寫正確，若欄位資訊相反會無法執行）。 點選Explore ，每次請求下方API時，會於header 帶入Authorization 及 x-date ，依照請求當下的時間及APP Key 製作簽章。

3. 建議於每次請求API服務當下建立新的signature ，簽章時效性為5分鐘。

Key	Value
Authorization	hmac username="APP ID", algorithm="hmac-sha256", headers="x-date", signature="Base64(HMAC-SHA256("x-date: " + x-date , APP Key))"
x-date	Tue, 24 Aug 2021 04:05:16 GMT

4. HMAC認證失效樣態：依照存取API 的HTTP header資訊判別用戶是否為授權身份，若未符合身份驗證將以下列訊息回應用戶端。

(1) HTTP Status Code 400錯誤發生原因：輸入的API參數錯誤或OData語法錯誤。

(2) HTTP Status Code 401錯誤發生原因：未帶簽章，未經授權，APP ID或Key輸入錯誤。

(3) HTTP Status Code 403錯誤發生原因：無該資料集使用權限； x-date的間隔時間超過定義的clock skew秒數；x-date日期格式正確，但簽章演算法有問題。

六、 OData查詢語法

OData語法	說明	範例
$select	回傳資料的某些欄位	回傳欄位1 $select= Field1
$filter	回傳符合特定表達式的資料	欄位A等於abc123的資料 $filter= FieldA eq ' abc123' 欄位A包含abc123的資料 $filter= contains(FieldA, ' abc123)
$orderby	決定資料的結果排序是升冪或降冪	針對欄位1作升冪 $orderby= Field1 asc 針對欄位1作降冪 $orderby= Field1 desc
$top	表示回傳前 n 筆資料	取前10筆 $top=10
$skip	表示略過前 n 筆資料	跳過前100筆 $skip=100
$format	決定資料的格式	$format=json