跳至主要內容

政府資料開放平臺

:::

玖、跨平臺介接協定與功能(標準檢測)

一、資料存取應用程式介面(API)功能說明

針對上述功能中所提之 API 功能說明如下，SRU 代表品質檢測的 API 服務根網址，呼叫服務路徑時，需將{SRU}代換成實際網址。

(一)取得機關資料集之標準檢測結果

透過取得機關資料集之品質檢測結果 API 擷取資料集(datasetId)之標準檢測結果，其功能如下表所列。

表 19: 取得機關資料集之標準檢測結果
功能說明 取得機關資料集之標準檢測結果
服務路徑 {SRU}/api/v2/rest/dsv_list/{publisherOID}, Method=GET
輸入說明 資源路徑 {publisherOID}
資源定義 提供機關物件識別碼
輸入範例 {SRU}/api/v2/rest/dsv_list/2.16.886.101.20003.20082
輸入參數 role_type=api
輸出說明 輸出內容 政府資料開放平臺之機關資料集之標準檢測結果欄位和內容。
輸出範例 {
"success": true,
"code": 200,
"message": "",
"payload": {
"search_count": 24,
"search_result": [
{
"nid": 156489,
"vid": 741061,
"title": "政府資料開放平臺資料集清單",
"creator_uid": 33095,
"dataset_status": "c01",
"dataset_status_name": "已上架",
"schema_test_time": "",
"schema_completed_time": "",
"agency_tid": 33218,
"agency_name": "數位發展部",
"schema_test_state": "",
"quality_badge_type": "金",
"schema_badge_type": "",
"schema_check_unit": "",
"provider": "數位發展部機關管理者 (33095)",
"schema_check_link": "/dash/dataset/scheme_check/result/156489"
},
{
"nid": 156490,
"vid": 741062,
"title": "政府資料開放平臺資料集瀏覽及下載次數統計",
"creator_uid": 33095,
"dataset_status": "c01",
"dataset_status_name": "已上架",
"schema_test_time": "",
"schema_completed_time": "",
"agency_tid": 33218,
"agency_name": "數位發展部",
"schema_test_state": "",
"quality_badge_type": "金",
"schema_badge_type": "",
"schema_check_unit": "",
"provider": "數位發展部機關管理者 (33095)",
"schema_check_link": "/dash/dataset/scheme_check/result/156490"
}
]
}
}
備註 1.資料集識別碼（nid）為「政府資料開放平臺」系統自動產出流水號，作為識別資料集之唯一值，不得重複與修改。
2.提供機關物件識別碼（publisherOID），請參考物件識別碼中心網站 https://oid.nat.gov.tw/OIDWeb/ ，為提供機關物件識別碼（OID），也可為下屬機關之 OID，建立後則不得再修改。
3.輸出範例的"quality_badge_type"，為該資料集品質檢測標章。
4."schema_badge_type"為該資料集標準檢測結果，若為空白表示無檢測紀錄或檢測失敗。

(二)取得單筆資料集標準檢測結果資料

透過取得單筆資料集標準檢測結果 API 擷取單筆資料集(datasetId)標準檢測結果，其功能如下表所列。

表 20: 取得單筆資料集標準檢測結果
功能說明 取得單筆資料集標準檢測結果
服務路徑 {SRU}/api/v2/rest/dsv_result/{datasetId}, Method=GET
輸入說明 資源路徑 {datasetId}
資源定義 資料集識別碼
輸入範例 {SRU}/api/v2/rest/dsv_result/11548
輸入參數 無
輸出說明 輸出內容 政府資料開放平臺之單筆資料集標準檢測結果欄位和內容。
輸出範例 {
"success": true,
"code": 200,
"message": "",
"payload": {
"nid": 11548,
"test_state": 1,
"org": "金融監督管理委員會證券期貨局",
"created": {
"date": "2015-02-10 15:20:13.000000",
"timezone_type": 3,
"timezone": "Asia/Taipei"
},
"content": [
{
"delta": 0,
"url": "https://www.twse.com.tw/exchangeReport/STOCK_DAY_AVG_ALL?response=open_data",
"desc": [
{
"name": "股票代號",
"desc": "",
"uri": ""
},
{
"name": "股票名稱",
"desc": "",
"uri": ""
},
{
"name": "收盤價",
"desc": "",
"uri": "api/CurrencyandFinancial/CommonData/NormalCommonData/DollarfloatTWD"
},
{
"name": "月平均價",
"desc": "",
"uri": ""
}
],
"test_state": "符合",
"message": ""
}
]
}
}
備註 1.資料集識別碼（datasetId）為「政府資料開放平臺」系統自動產出流水號，作為識別資料集之唯一值，不得重複與修改。
2.提供機關物件識別碼（publisherOID），請參考物件識別碼中心網站 https://oid.nat.gov.tw/OIDWeb/ ，為提供機關物件識別碼（OID），也可為下屬機關之 OID，建立後則不得再修改。
3."test_state"為單筆資源檢測結果，分為符合及不符合。

(三)呼叫執行標準檢測

提供「提供者/平臺」新增「政府資料開放平臺」之單筆/批次標準檢測執行，必須配合所設定之資料來源 IP 和 API KEY。其功能如下表所列：

表 21: 新增單筆/批次標準檢測執行
功能說明 新增單筆/批次標準檢測執行
服務路徑 批次：
{SRU}/api/v2/rest/do_dsv/{publisherOID}, Method=POST
單筆：
{SRU}/api/v2/rest/do_dsv/{publisherOID}/{datasetId}, Method=POST
輸入說明 資源路徑 批次：
{publisherOID}
單筆：
{publisherOID}/{datasetId}
資源定義 批次：提供機關物件識別碼
單筆：提供機關物件識別碼/資料集識別碼
輸入範例 批次：
{SRU}/api/v2/rest/do_dsv/2.16.886.101.20003.20082
單筆：
{SRU}/api/v2/rest/do_dsv/2.16.886.101.20003.20082/6564
輸入參數 批次：
{
"target_type": "agency"
}
輸出說明 輸出內容 新增標準檢測執行。
輸出範例 1.執行成功如下所示：
{
"success": true,
"result": {
"message": "已送出資料標準成功",
"data": "{\"nids\":[\"1234\"],\"task_id(sno)\": 12345}"
}
}
2.執行失敗如下所示：
{
"pass": false,
"error": {
"error_msg": "來源機構代碼 oid 不允許",
"error_type": "ER0003:來源機構代碼 oid 不允許",
"oid": "2.16.886.101.20003.20069"
}
}
備註 1.資料集識別碼（datasetId）為「政府資料開放平臺」系統自動產出流水號，作為識別資料集之唯一值，不得重複與修改。
2.提供機關物件識別碼（publisherOID），請參考物件識別碼中心網站 https://oid.nat.gov.tw/OIDWeb/ ，為提供機關物件識別碼（ OID），也可為下屬機關之 OID，建立後則不得再修改。
3.各機關可於 24 小時內進行 1 次批次資料標準檢測，若已檢測之機關須於 24 小時過後再行檢測。

(四)取得特定資料集資料標準檢測欄位及 URI

表 22: 取得特定資料集資料標準檢測欄位及 URI
功能說明 取得特定資料集資料標準檢測欄位及 URI
服務路徑 {SRU}/api/v2/rest/dsv/resources/{nid}, Method=GET
輸入說明 資源路徑 {nid}
資源定義 提供資料集識別碼
輸入範例 {SRU}/api/v2/rest/dsv/resources/156825
輸入參數 無
輸出說明 輸出內容 取得特定資料集資料標準檢測欄位及 URI。
輸出範例 執行成功如下所示：
{
"help": "",
"success": true,
"result": {
"0": {
"description": "",
"url": "https://opendata.tdcc.com.tw/getOD.ashx?id=3-4",
"field": [
"基金代碼",
"基金名稱",
"日期",
"基金淨值",
"ISINCODE",
"計價幣別",
"境外基金機構",
"總代理機構"
],
"uri": [
{
"基金代碼": ""
},
{
"基金名稱": ""
},
{
"日期": "api/Commonality/Commonality/CommonData/Date"
},
{
"基金淨值": "api/CurrencyandFinancial/CommonData/NormalCommonData/DollarfloatTWD"
},
{
"ISINCODE": ""
},
{
"計價幣別": ""
},
{
"境外基金機構": ""
},
{
"總代理機構": ""
}
]
},
"title": "境外基金淨值",
"nid": "156825",
"status": "檢測成功"
}
}
備註 1.資料集識別碼（nid）為「政府資料開放平臺」系統自動產出流水號，作為識別資料集之唯一值，不得重複與修改。
2.資料標準檢測 URI(uri)包含資料資源欄位名稱及該欄位使用檢測之 URI

(五)輸入特定資料集資料標準檢測欄位及 URI

表 23: 輸入特定資料集資料標準檢測欄位及 URI
功能說明 輸入特定資料集資料標準檢測欄位及 URI
服務路徑 {SRU}/api/v2/rest/dsv/resources/modify/{nid}, Method=PUT
輸入說明 資源路徑 {nid}
資源定義 提供資料集識別碼
輸入範例 {SRU}/api/v2/rest/dsv/resources/modify/156825
輸入參數 {
"columns":
{
"年度": "api/BudgetAccountingandStatistics/Statistics/AgricultureForestryFisheryandAnimalHusbandryCensus/TimePeriodYYYROC",
"月份": "api/Biodiversity/Occurrence/Event/month"
}
}
輸出說明 輸出內容 輸出內容
輸出範例 執行成功如下所示：
{
"help": "",
"success": true,
"result": {
"uri": [
{
"年度": "api/BudgetAccountingandStatistics/Statistics/AgricultureForestryFisheryandAnimalHusbandryCensus/TimePeriodYYYROC"
},
{
"月份": "api/Biodiversity/Occurrence/Event/month"
},
{
"使用者數": ""
}
],
"title": "資料品質教育訓練測試資料集",
"nid": "146690",
"delta": 0
}
}
備註 1.資料集識別碼（nid）為「政府資料開放平臺」系統自動產出流水號，作為識別資料集之唯一值，不得重複與修改。
2.輸入參數須包含資料資源欄位名稱及該欄位使用檢測之 URI

(六)錯誤訊息代碼一覽

錯誤代碼 訊息內容 說明
ER0001 API Key 錯誤 API Key 錯誤
ER0002 來源 IP 不允許 來源 IP 不允許
ER0003 來源機構代碼 oid 不允許 來源機構代碼oid不允許
ER0004 資料集代碼 datasetId 不允許 資料集代碼datasetId不允許
ER0005 平臺上不存在此機關代碼對應的資料集 平臺上不存在此機關代碼對應的資料集
400 找不到此資料集之資料標準檢測結果 此資料集無資料標準檢測結果