跳至主要內容

政府資料開放平臺

:::

捌、跨平臺介接協定與功能(品質檢測)

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

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

(一)取得機關資料集之品質檢測結果

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

表 14: 取得機關資料集之品質檢測結果
功能說明 取得機關資料集之品質檢測結果
服務路徑 {SRU}/api/v2/rest/qc/{publisherOID}, Method=GET
輸入說明 資源路徑 {publisherOID}
資源定義 提供機關物件識別碼
輸入範例 {SRU}/api/v2/rest/qc/2.16.886.101.20003.20069
輸入參數 無
輸出說明 輸出內容 政府資料開放平臺之機關資料集之品質檢測結果欄位和內容。
輸出範例 {
"success": true,
"result": [
{
"datasetId": "5959",
"title": "行政院公報",
"linkable": "1",
"downloadable": "1",
"structure": "1",
"encoding_match": "1",
"desc_match": "1",
"csv": "1",
"created": "2019-08-23 12:09:13",
"request": "2019-08-23 12:09:13",
"changed": "2019-08-23 12:09:15"
},
{
"datasetId": "5960",
"title": "數位機會調查",
"linkable": "1",
"downloadable": "1",
"structure": "1",
"encoding_match": "1",
"desc_match": "0",
"csv": "1",
"created": "2018-07-20 15:27:41",
"request": "2019-08-05 14:27:27",
"changed": "2019-08-05 14:27:33"
}
]
}
備註 1.資料集識別碼（datasetId）為「政府資料開放平臺」系統自動產出流水號，作為識別資料集之唯一值，不得重複與修改。
2.提供機關物件識別碼（publisherOID），請參考物件識別碼中心網站 https://oid.nat.gov.tw/OIDWeb/ ，為提供機關物件識別碼（OID），也可為下屬機關之 OID，建立後則不得再修改。
3.輸出範例的 linkable、downloadable、structure、encoding_match、desc_match 分別代表為連結狀態、直接下載、結構化格式、編碼符合、主要欄位說明符合，"0"=否，"1"=是，"2"=未知。

(二)取得單筆資料集之品質檢測結果

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

表 15: 取得單筆資料集品質檢測結果
功能說明 取得單筆資料集品質檢測結果
服務路徑 {SRU}/api/v2/rest/quality_result/{datasetId}, Method=GET
輸入說明 資源路徑 {datasetId}
資源定義 資料集識別碼
輸入範例 {SRU}/api/v2/rest/quality_result/6564
輸入參數 無
輸出說明 輸出內容 政府資料開放平臺之單筆資料集品質檢測結果欄位和內容。
輸出範例 {
"success": true,
"message": "檢測成功",
"result": {
"status": true,
"dataset": {
"linkable": 1,
"downloadable": 1,
"structure": 0,
"encoding_match": 1,
"desc_match": 0,
"csv": 0,
"is_whitelist": 1,
"agency": "491",
"pubdate": "2013-11-01 00:00:00"
},
"resources": {
"https://data.gov.tw/datasets/export/csv": {
"resource": {
"linkable": 1,
"downloadable": 1,
"structure": 1,
"encoding_match": 1,
"desc_match": 0,
"csv": 1,
"url": "https://data.gov.tw/datasets/export/csv",
"desc": "103 年 01 月 01 日開始收錄",
"fields": "id、資料集名稱、檔案格式、下載連結、資料集類型、資料集描述、主要欄位說明、提供機關、更新頻率、授權方式、計費方式、編碼格式、資料集提供機關聯絡人、資料集提供機關聯絡人電話、備註、意見樣態類型",
"qclevel": "",
"encoding": "UTF-8",
"file_type": "csv",
"amount": 0,
"last_update_time": "2021-06-17 14:29:50",
"check_time": "2021-06-17 14:30:30",
"ref_key": "",
"is_whitelist": 0,
"messages": [
"structure_result(): 主要欄位比對失敗"
]
},
"files": [
{
"filename": "DTQC_sHeuWo_s1.csv",
"file_type": "CSV",
"structure": 1,
"csv": 1,
"desc_match": 0,
"encoding": "UTF-8",
"qclevel": "",
"enc_match": 1,
"fields": [],
"amount": 49747,
"message": "structure_result(): 主要欄位比對失敗"
}
],
"is_whitelist": 1
},
"https://data.gov.tw/datasets/export/xml": {
"resource": {
"linkable": 1,
"downloadable": 1,
"structure": 0,
"encoding_match": 1,
"desc_match": 0,
"csv": 0,
"url": "https://data.gov.tw/datasets/export/xml",
"desc": "103 年 01 月 01 日開始收錄",
"fields": "id、資料集名稱、檔案格式、下載連結、資料集類型、資料集描述、主要欄位說明、提供機關、更新頻率、授權方式、計費方式、編碼格式、資料集提供機關聯絡人、資料集提供機關聯絡人電話、備註、意見樣態類型",
"qclevel": "",
"encoding": "",
"file_type": "xml",
"amount": 0,
"last_update_time": "2021-06-17 14:30:07",
"check_time": "2021-06-17 14:30:30",
"ref_key": "",
"is_whitelist": 0,
"messages": [
"[004] process_resource_file():is_xslx(): XML error: Invalid character at line 1149"
]
},
"files": [
{
"filename": "DTQC_zsSGAv_s1.xml",
"file_type": "XML",
"structure": 0,
"csv": 0,
"desc_match": 0,
"encoding": "",
"qclevel": "",
"enc_match": 1,
"fields": [],
"amount": 0,
"message": "[004] process_resource_file():is_xslx(): XML error: Invalid character at line 1149"
}
],
"is_whitelist": 1
}
},
"no_qc": []
}
}
備註 1.資料集識別碼（datasetId）為「政府資料開放平臺」系統自動產出流水號，作為識別資料集之唯一值，不得重複與修改。
2.提供機關物件識別碼（publisherOID），請參考物件識別碼中心網站 https://oid.nat.gov.tw/OIDWeb/ ，為提供機關物件識別碼（OID），也可為下屬機關之 OID，建立後則不得再修改。
3.輸出範例的 linkable、downloadable、structure、encoding_match、desc_match 分別代表為連結狀態、直接下載、結構化格式、編碼符合、主要欄位說明符合，"0"=否，"1"=是，"2"=未知。

(三)呼叫執行品質檢測

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

表 16: 新增單筆/批次品質檢測執行
功能說明 新增單筆/批次品質檢測執行
服務路徑 批次：
{SRU}/api/v2/rest/do_qc/{publisherOID}, Method=POST
單筆：
{SRU}/api/v2/rest/do_qc/{publisherOID}/{datasetId}, Method=POST
輸入說明 資源路徑 批次：
{publisherOID}
單筆：
{publisherOID}/{datasetId}
資源定義 批次：
提供機關物件識別碼
單筆：
提供機關物件識別碼/資料集識別碼
輸入範例 批次：
{SRU}/api/v2/rest/do_qc/2.16.886.101.20003.20069
單筆：
{SRU}/api/v2/rest/do_qc/2.16.886.101.20003.20069/6564
輸入參數 批次：
{
"target_type": "agency"
}
輸出說明 輸出內容 新增品質檢測執行。
輸出範例 1.執行成功如下所示：
{
"success": true,
"result": {
"message": "send qc",
"data": "{\"nids\":[\"5959\",\"5960\",\"5961\"],\"batch_key\":null}"
}
}
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，建立後則不得再修改。

(四)清除品質檢測暫存檔

提供「提供者/平臺」進行「政府資料開放平臺」之資料集品質檢測結果清除 cache 暫存檔，必須配合所設定之資料來源 IP 和 API KEY。其功能如下表所列：

表 17: 清除品質檢測暫存檔
功能說明 清除品質檢測暫存檔
服務路徑 /api/v2/rest/qc/clear/{nid}, Method=POST
輸入說明 資源路徑 {nid}
資源定義 提供資料集識別碼
輸入範例 {SRU}/api/v2/rest/qc/clear/146689
輸入參數 無
輸出說明 輸出內容 清除品質檢測暫存檔執行結果。
輸出範例 執行成功如下所示：
{
"success": true,
"code": 200,
"message": ""
}
備註 1.資料集識別碼（nid）為「政府資料開放平臺」系統自動產出流水號，作為識別資料集之唯一值，不得重複與修改。
2.清除暫存檔後，不影響品質檢測結果。

(五)重設品質檢測結果

提供「提供者/平臺」進行「政府資料開放平臺」之資料集品質檢測結果重設，必須配合所設定之資料來源 IP 和 API KEY。其功能如下表所列：

表 18: 重設品質檢測結果
功能說明 重設品質檢測結果
服務路徑 /api/v2/rest/qc/reset/{nid}, Method=POST
輸入說明 資源路徑 {nid}
資源定義 提供資料集識別碼
輸入範例 {SRU}/api/v2/rest/qc/reset/146689
輸入參數 無
輸出說明 輸出內容 重設品質檢測結果
輸出範例 執行成功如下所示：
{
"success": true,
"code": 200,
"message": ""
}
備註 1.資料集識別碼（nid）為「政府資料開放平臺」系統自動產出流水號，作為識別資料集之唯一值，不得重複與修改。
2.重設品質檢測結果後，資料集將回到未檢測狀態，資料集檢測結果及標章皆會清除。

(六)錯誤訊息代碼一覽

錯誤代碼 訊息內容 說明
ER0001 API Key 錯誤 API Key 錯誤
ER0002 來源 IP 不允許 來源 IP 不允許
ER0003 來源機構代碼 oid 不允許 來源機構代碼oid不允許
ER0004 資料集代碼 datasetId 不允許 資料集代碼datasetId不允許
ER0005 平臺上不存在此機關代碼對應的資料集 平臺上不存在此機關代碼對應的