Open AI ） 
柒、跨平臺介接協定與功能
實現跨平臺詮釋資料介接作業，對應所需的應用程式介面（API）、管理功能、交換協定如下說明：
一、詮釋資料集中至政府資料開放平臺
（一）即時發布功能
「政府資料開放平臺」必須提供管理功能包括「設定資料來源 IP」、「取得授權API KEY」和「異動資料集詮釋資料」（包含新增、修改、下架）API 介面功能。
◼ 設定資料來源 IP：「政府資料開放平臺」系統管理者至「政府資料開放平臺」系統後端管理介面，設定其資料開放平臺資料來源 IP，增加資訊安全性。
◼ 取得授權 API KEY：「政府資料開放平臺」提供 API KEY，作為該平臺之辨識，提供資料來源的可信度。
◼ 各資料開放平臺資料異動時，呼叫「政府資料開放平臺」之「異動資料集詮釋資料」API，檢視來源 IP、API KEY以及機關物件識別碼（publisherOID）之正確性後，進行資料集新增、修改及下架。
◼ 各資料開放平臺若需發布新增資料集詮釋資料，不需填寫資料集識別碼（datasetId），「政府資料開放平臺」新增該筆資料集詮釋資料後將提供資料集識別碼（datasetId）供後續資料集修改使用。
◼ 各資料開放平臺發布需修改之資料集的詮釋資料，「政府資料開放平臺」將比對來源 IP、API KEY、資料集識別碼（datasetId）及提供機關物件識別碼（publisherOID），若符合則依據其異動內容，更新於「政府資料開放平臺」該筆資料集詮釋資料。
◼ 各資料開放平臺發布需下架之資料集，「政府資料開放平臺」將比對資料集資料來源 IP、API KEY、資料集識別碼（datasetId），若符合則於「政府資料開放平臺」下架該筆資料集詮釋資料。
各資料開放平臺必須於詮釋資料異動後同步發布異動詮釋資料。呼叫「政府資料開放平臺」異動資料集詮釋資料 API，並配合所設定之資料來源 IP 和 API KEY。
呼叫新增、修改、下架詮釋資料 API，需使用 HTTP 基本認證（HTTP Basic Authentication）以確認授權身分（即在 HTTP header 裡設定屬性 Authorization 的值為 API KEY）。
（二）定期發布功能
各資料開放平臺必須提供「定期發布排程」管理功能，檢視異動資料集詮釋資料，呼叫「政府資料開放平臺」之異動資料集詮釋資料 API。
各資料開放平臺可依據詮釋資料異動頻率設定排程，定期呼叫「政府資料開放平臺」異動資料集詮釋資料 API，並須配合所設定之資料來源 IP、API KEY、資料集識別碼（datasetId）及提供機關物件識別碼（publisherOID）。
呼叫新增、修改、下架詮釋資料 API，需使用 HTTP 基本認證（HTTP Basic Authentication）以確認授權身分（即在 HTTP header 裡設定屬性 Authorization 的值為 API KEY）。
二、 各資料開放平臺至政府資料開放平臺擷取其他詮釋資料
各資料開放平臺呼叫「政府資料開放平臺」取得詮釋資料 API，取得所需資料集詮釋資料。
三、資料存取應用程式介面（API）功能說明
針對上述功能中所提之 API 功能說明如下，SRU 代表詮釋資料的 API 服務根網址，呼叫服務路徑時，需將{SRU}代換成實際網址。
（一）取得資料集詮釋資料內容
透過取得資料集詮釋資料 API 擷取檔案資料、API 服務資料集詮釋資料，其功能如下表所列。
1. 取得詮釋資料(檔案資料)
| 功能說明 | 取得資料集詮釋資料(檔案資料) | |
|---|---|---|
| 服務路徑 | {SRU}/api/v2/rest/dataset/{datasetId}, Method=GET | |
| 輸入說明 | 資源路徑 | {datasetId} |
| 資源定義 | 資料集識別碼 | |
| 輸入範例 | {SRU}/api/v2/rest/dataset/6564 | |
| 輸入參數 | 無 | |
| 輸出說明 | 輸出內容 | 1. 資料開放平臺之資料集詮釋資料欄位和內容。詮釋資料欄位應包含「資料集詮釋資料標準指引」制定之詮釋資料欄位。 2. 當執行跨平臺詮釋資料交換時，輸出內容必須包含提供機關物件識別碼（publisherOID），以利各資料開放平臺識別資料集機關來源。機關 OID 欄位內容，請參見政府物件識別碼中心網站。 |
| 輸出範例 | 以 JSON 格式示範資料集詮釋資料的欄位和內容： { "help": "", "success": true, "result": { "categoryService":"I00", "categoryDataset":"A", "datasetId":"6564", "identifier":"A41000000G-000001", "title":"政府資料開放平臺資料集清單", "description":"集中列示於政府資料開放平臺資料集之 詮釋資料、資料集提供機關聯絡人、資料集提供機 關聯絡人電話、備註等", "type":"api", "license":"1", "cost":"free", "dataProvider":" loginaccount", "publisherOID":"2.16.886.101.20003.20069.20001|國家發展委員會檔案管理局", "publisherContactName":"秘書室林小姐", "publisherContactPhone":"02-23165300#XXX", "publisherContactEmail":"example@ndc.gov.tw", "updateFrequency":"每日", "detectFrequency":"everyday", "dataQuality":"G", "coverageStartedDate":"2014-01-01", "coverageEndedDate":"2015-01-01", "publishedDate":"2017-01-01", "modifiedDate":"2017-01-01 23:59:59", "spatialCoverage":"A6305-0001-00", "language":"zh", "relatedUrl":" https://example1.gov.tw", "notes":"集中於政府資料開放平臺資料集之詮釋資料", "distribution":[ { "resourceDescription":" 103 年 01 月 01 日開始收錄", "resourceField": [ { "name": "村名", "description ": "name " }, { "name ": "人口", "description ": "population " } ], "qcLevel":"/Document/definition/dataset", "resourceFormat":"CSV", "resourceCharacterEncoding":"UTF-8", " resource.quality_check_time ":"2015-01-01 23:59:59", "resourceDownloadUrl":"https://data.gov.tw/datasets/exp ort/csv", "resourceAmount":"4600", "resourceNotes":"統計截止到 2014 年 12 月底" } ], "keyword": [ "OpenData", "全部資料集" ] } } 若查無資料，則回傳： { "success": false, "error": { "error_type": "Not Found", "message": "Not Found" } } |
|
| 備註 | 1. 輸出內容之資料集編號（identifier）為各資料開放平臺發布資料集的資訊編號，由各平臺自行輸入。於民國 109 年 5 月政府資料開放平臺改版後，該欄位不需填寫。 2. 提供機關物件識別碼（publisherOID），請參考物件識別碼中心網站，為提供機關物件識別碼（OID）。 3. 提供機關物件識別碼（publisherOID）為識別資料集提供機關之唯一識別碼，新增後則不得修改。 4. 資料集識別碼（datasetId）為「政府資料開放平臺」系統自動產出流水號，作為識別資料集之唯一值，不得重複與修改。 |
|
2. 取得詮釋資料(API 服務)
| 功能說明 | 取得資料集詮釋資料(API 服務) | |
|---|---|---|
| 服務路徑 | {SRU}/api/v2/rest/dataset/{datasetId}, Method=GET | |
| 輸入說明 | 資源路徑 | {datasetId} |
| 資源定義 | 資料集識別碼 | |
| 輸入範例 | {SRU}/api/v2/rest/dataset/161170 | |
| 輸入參數 | 無 | |
| 輸出說明 | 輸出內容 | 1. 資料開放平臺之資料集詮釋資料欄位和內容。詮釋資料欄位應包含「資料集詮釋資料標準指引」制定之詮釋資料欄位。 2. 當執行跨平臺詮釋資料交換時，輸出內容必須包含提供機關物件識別碼（publisherOID），以利各資料開放平臺識別資料集機關來源。機關 OID 欄位內容，請參見政府物件識別碼中心網站。 |
| 輸出範例 | 以 JSON 格式示範資料集詮釋資料的欄位和內容： { "categoryService": "A00", "categoryDataset": "B", "datasetId": 161170, "title": "高速公路發布路段即時路況資料", "description": "取得[高速公路局]發布路段即時路況", "type": "api", "license": "1", "cost": "free", "dataProvider": "loginaccount", "publisherOID": "2.16.886.101.20003.20008", "publisherContactName": "TDX 維運團隊", "publisherContactPhone": "02-23492803", "publisherContactEmail": "tdx@motc.gov.tw", "updateFrequency": { "regularupdate": "1", "Frequency": "1", "unittime": "分" }, "dataQuality": "", "coverageStartedDate": "", "coverageEndedDate": "", "publishedDate": "2023-02-21", "modifiedDate": "2023-04-17 10:55:08", "spatialCoverage": "臺灣", "language": "zh", "relatedUrl": "https://tdx.transportdata.tw", "notes": "請先至 TDX 平台註冊會員並建立 API Key", "apiDocUrl":"https://tdx.transportdata.tw/apiservice/swagger/basic/7f07d940-91a4-495d-9465-1c9df89d709c#/FreewayTraffic/Live_Freeway", "distribution": [ { "resourceDescription": "取得[高速公路局]發布路段即時路況", "resourceField": [ { "name": "請參考https://tdx.transportdata.tw/apiservice/swagger/basic/7f07d940-91a4-495d-9465-1c9df89d709c#/FreewayTraffic/Live_Freeway", "description": "" } ], "resourceQualityCheckTime": "", "resourceDownloadUrl":"https://tdx.transportdata.tw/api/basic/v2/Road/Traffic/Live/Freeway", "resourceNotes": "請先至 TDX 平台註冊會員並建立API Key", "resourceRequestMethod": "GET", "resourceOasUrl": "https://tdx.transportdata.tw/backend/api/File/Swagger/V3/7f07d940-91a4-495d-9465-1c9df89d709c", "resourceRequestParameters": [ { "name": "$format", "type": "string", "required": 2, "_default": null, "description": "指定回傳資料格式" }, { "name": "$count", "type": "Boolean", "required": 2, "_default": null, "description": "查詢數量" }, { "name": "$skip", "type": "integer", "required": 2, "_default": null, "description": "跳過前幾筆" }, { "name": "$top", "type": "integer", "required": 2, "_default": null, "description": "取前幾筆" }, { "name": "$orderby", "type": "string", "required": 2, "_default": null, "description": "排序" }, { "name": "$filter", "type": "string", "required": 2, "_default": null, "description": "過濾" }, { "name": "$select", "type": "string", "required": 2, "_default": null, "description": "挑選" } ], "resourcePathParameters": [] } ], "keyword": [ "高速公路", "發布路段即時路況" ] } 若查無資料，則回傳： { "success": false, "error": { "error_type": "Not Found", "message": "Not Found" } }備註1. 提供機關物件識別碼（publisherOID），請參考物件識別碼中心網站，為提供機關物件識別碼（OID）。 2. 提供機關物件識別碼（publisherOID）為識別資料集提供機關之唯一識別碼，新增後則不得修改。 3. 資料集識別碼（datasetId）為「政府資料開放平臺」系統自動產出流水號，作為識別資料集之唯一值，不得重複與修改。 4. 資料提供屬性(categoryDataset)欄位為標示「政府資料開放平臺」之資料服務，選項包含 A=檔案資料、B=API 服務。 |
|
（二）呼叫異動資料集詮釋資料
提供各資料開放平臺更新「政府資料開放平臺」之資料集詮釋資料，必須配合所設定之資料來源 IP 和 API KEY。其功能如下表所列：
1. 新增詮釋資料(檔案資料)
| 功能說明 | 新增詮釋資料(檔案資料) | |
|---|---|---|
| 服務路徑 | {SRU}/api/v2/rest/dataset,Method=POST | |
| 輸入說明 | 請求標示(headers) | Authorization:{API Key} Content-Type:application/json |
| 輸入參數 | 以 JSON 格式示範資料集詮釋資料的欄位和內容： { "categoryTheme":"001", "categoryService":"I00", "categoryDataset":"A", "title":"政府資料開放平臺資料集清單", "description":"集中列示於政府資料開放平臺資料集之詮釋資料式、資料集提供機關聯絡人、資料集提供機關聯絡人電話、備註等", "license":"1", "cost":"free", "dataProvider":"loginaccount” "publisherOID":"2.16.886.101.20003.20069.20001|國家發展委員會檔案管理局", "publisherContactName":"秘書室林小姐", "publisherContactPhone":"02-23165300#XXX", "publisherContactEmail":"example@ndc.gov.tw", "updateFrequency":"每日", "detectFrequency":"everyday", "coverageStartedDate":"2014-01-01", "coverageEndedDate":"2015-01-01", "publishedDate": "2022-05-09", "spatialCoverage":"A6305-0001-00", "language":"zh", "relatedUrl":" https://example1.gov.tw", "keyword": [ "OpenData", "全部資料集" ], "notes":"集中於政府資料開放平臺資料集之詮釋資料", "distribution":[ { "resourceDescription":" 103 年 01 月 01 日開始收錄", "resourceField":" 村名(name)、人口(population)", "qcLevel":"/Document/definition/dataset", "resourceFormat":"CSV", "resourceCharacterEncoding":"UTF-8", "resourceDownloadUrl":"https://data.gov.tw/datasets/export/csv", "resourceAmount ":"4600", "resourceNotes":"統計截止到 2014 年 12 月底" } ] } |
|
| 輸出說明 | 輸出內容 | 新增資料集詮釋資料之結果。 |
| 輸出範例 | 1. 執行成功如下所示： { "success": true, "result": { "datasetId":6564（系統產生） } } 2. 執行失敗如下所示： { "success":"false", "error": { "error_type":"ER0032:資料集主題分類錯誤", "message":"無此主題分類 categoryTheme=k00"} } |
|
| 備註 | 1. 輸出內容之資料集編號（identifier）為各資料開放平臺發布資料集的資訊編號，由各平臺自行輸入。於民國 109 年 5 月政府資料開放平臺改版後，該欄位不需填寫。 2. 提供機關物件識別碼（publisherOID），請參考物件識別碼中心網站，為提供機關物件識別碼（OID），也可為下屬機關之OID，建立後則不得再修改。 3. 資料集識別碼（datasetId）為「政府資料開放平臺」系統自動產出流水號，作為識別資料集之唯一值，不得重複與修改。新增詮釋資料完成後，系統會回傳此識別碼。 4. 資料提供屬性(categoryDataset)欄位為「政府資料開放平臺」資料上架類型，選項包含 A=檔案資料、B=API 服務。 |
|
2. 新增詮釋資料(API 服務)
| 功能說明 | 新增詮釋資料(API 服務) | |
|---|---|---|
| 服務路徑 | {SRU}/api/v2/rest/dataset,Method=POST | |
| 輸入說明 | 請求標示(headers) | Authorization:{API Key} Content-Type:application/json |
| 輸入參數 | 以 JSON 格式示範資料集詮釋資料的欄位和內容： { "categoryService": "A00", "categoryDataset": "B", "title": "高速公路發布路段即時路況資料", "description": "取得[高速公路局]發布路段即時路況", "type": "api", "license": "1", "cost": "free", "dataProvider": "loginaccount", "publisherOID": "2.16.886.101.20003.20008", "publisherContactName": "TDX 維運團隊", "publisherContactPhone": "02-23492803", "publisherContactEmail": "tdx@motc.gov.tw", "updateFrequency": { "regularupdate": "1", "Frequency": "1", "unittime": "分" }, "coverageStartedDate": "", "coverageEndedDate": "", "publishedDate": "2023-02-21", "modifiedDate": "2023-04-17 10:55:08", "spatialCoverage": "臺灣", "language": "zh", "relatedUrl": "https://tdx.transportdata.tw", "notes": "請先至 TDX 平台註冊會員並建立 API Key", "apiDocUrl": "https://tdx.transportdata.tw/apiservice/swagger/basic/7f07d940-91a4-495d-9465-1c9df89d709c#/FreewayTraffic/Live_Freeway", "distribution": [ { "resourceDescription": "取得[高速公路局]發布路段即時路況", "resourceField": [ { "name": "請參考 https://tdx.transportdata.tw/api-service/swagger/basic/7f07d940-91a4-495d-9465-1c9df89d709c#/FreewayTraffic/Live_Freeway", "description": "" } ], "resourceQualityCheckTime": "", "resourceDownloadUrl": "https://tdx.transportdata.tw/api/basic/v2/Road/Traffic/Live/Freeway", "resourceNotes": "請先至 TDX 平台註冊會員並建立API Key", "resourceRequestMethod": "GET", "resourceOasUrl": "https://tdx.transportdata.tw/backend/api/File/Swagger/V3/7f07d940-91a4-495d-9465-1c9df89d709c", "resourceRequestParameters": [ { "name": "$format", "type": "string", "required": 2, "_default": null, "description": "指定回傳資料格式" }, { "name": "$count", "type": "Boolean", "required": 2, "_default": null, "description": "查詢數量" }, { "name": "$skip", "type": "integer", "required": 2, "_default": null, "description": "跳過前幾筆" }, { "name": "$top", "type": "integer", "required": 2, "_default": null, "description": "取前幾筆" }, { "name": "$orderby", "type": "string", "required": 2, "_default": null, "description": "排序" }, { "name": "$filter", "type": "string", "required": 2, "_default": null, "description": "過濾" }, { "name": "$select", "type": "string", "required": 2, "_default": null, "description": "挑選" } ], "resourcePathParameters": [] } ], "keyword": [ "高速公路", "發布路段即時路況" ] } |
|
| 輸出說明 | 輸出內容 | 新增資料集詮釋資料之結果。 |
| 輸出範例 | 1. 執行成功如下所示： { "success": true, "result": { "datasetId":6564（系統產生） } } 2. 執行失敗如下所示： { "success":"false", "error": { "error_type":"ER0032:資料集主題分類錯誤", "message":"無此主題分類 categoryTheme=k00"} } |
|
| 備註 | 1. 提供機關物件識別碼（publisherOID），請參考物件識別碼中心網站，為提供機關物件識別碼（OID），也可為下屬機關之 OID，建立後則不得再修改。 2. 資料集識別碼（datasetId）為「政府資料開放平臺」系統自動產出流水號，作為識別資料集之唯一值，不得重複與修改。新增詮釋資料完成後，系統會回傳此識別碼。 3. 資料提供屬性(categoryDataset)欄位為「政府資料開放平臺」資料上架類型，選項包含 A=檔案資料、B=API 服務。 |
|
3. 修改詮釋資料(檔案資料)
| 功能說明 | 修改資料集詮釋資料(檔案資料) | |
|---|---|---|
| 服務路徑 | {SRU}/api/v2/rest/dataset/{datasetId},Method=PUT | |
| 輸入說明 | 請求標示(headers) | Authorization:{API Key} Content-Type:application/json |
| 資源路徑 | {datasetId} | |
| 資源定義 | 資料集識別碼 | |
| 輸入範例 | {SRU}/rest/dataset/6564 | |
| 輸入參數 | 以取得資料集詮釋資料 JSON 格式示範修改資料集詮釋資料的欄位和內容： { "categoryTheme":"001", "categoryService":"I00", "categoryDataset":"A", "datasetId":"6564", "title":"政府資料開放平臺資料集清單", "description":"集中列示於政府資料開放平臺資料集之詮釋資料式、資料集提供機關聯絡人、資料集提供機關聯絡人電話、備註等", "license":"1", "cost":"free", "dataProvider":" loginaccount", "publisherOID":"2.16.886.101.20003.20069.20001|國家發展委員會檔案管理局", "publisherContactName":"秘書室林先生", "publisherContactPhone":"02-23165300#XXX", "publisherContactEmail":"example1@ndc.gov.tw", "updateFrequency":"每日", "detectFrequency":"everyday", "coverageStartedDate":"2014-01-01", "coverageEndedDate":"2015-01-01", "publishedDate":"2017-01-01", "spatialCoverage":"A6305-0001-00", "language":"zh", "relatedUrl":" https://example1.gov.tw", "keyword": [ "OpenData", "全部資料集" ], "notes":"集中於政府資料開放平臺資料集之詮釋資料", "distribution":[ { "resourceDescription":" 103 年 01 月 01 日開始收錄", "resourceField":"村名(name)、人口(population)", "qcLevel":"/Document/definition/dataset", "resourceFormat":"CSV", "resourceCharacterEncoding":"UTF-8", "resourceDownloadUrl":"https://data.gov.tw/datasets/export/csv", "resourceAmount ":"4600", "resourceNotes":"統計截止到 2014 年 12 月底" } ] } |
|
| 輸出說明 | 輸出內容 | 修改資料集詮釋資料結果。 |
| 輸出範例 | 1. 執行成功如下所示： { "success": true, "result": {"datasetId": "6564"} } 2. 執行失敗如下所示： { "success": false, "error": { "datasetId": "656", "error_type":"ER0051:欲修改的資料集不存在。", "message": "欲修改的資料集不存在。"} } |
|
| 備註 | 1. 以取得資料集詮釋資料 JSON 格式示範，有關系統自動產出之欄位不得進行修改，例如 ：資料集類型（type）、資料品質（dataQuality）、上架日期（publishedDate）、詮釋資料更新時間（modifiedDate）、資料資源品質檢測時間（resource.quality_check_time），無法修改。 2. 輸出內容之資料集編號（identifier）為各資料開放平臺發布資料集的資訊編號，由各平臺自行輸入。於民國 109 年 5 月政府資料開放平臺改版後，該欄位不需填寫。 3. 提供機關物件識別碼（publisherOID），請參考物件識別碼中心網站，為提供機關物件識別碼（OID），也可為下屬機關之 OID，建立後則不得再修改。 4. 資料集識別碼（datasetId）為「政府資料開放平臺」系統自動產出流水號，作為識別資料集之唯一值，不得重複與修改。 |
|
4. 修改詮釋資料(API 服務)
| 功能說明 | 修改資料集詮釋資料(API 服務) | |
|---|---|---|
| 服務路徑 | {SRU}/api/v2/rest/dataset/{datasetId},Method=PUT | |
| 輸入說明 | 請求標示(headers) | Authorization:{API Key} Content-Type:application/json |
| 資源路徑 | {datasetId} | |
| 資源定義 | 執行成果與資料集識別碼 | |
| 輸入範例 | {SRU}/rest/dataset/6564 | |
| 輸入參數 | 以取得資料集詮釋資料 JSON 格式示範修改資料集詮釋資料的欄位和內容： { "categoryService": "A00", "categoryDataset": "B", "datasetId": 161170, "title": "高速公路發布路段即時路況資料", "description": "取得[高速公路局]發布路段即時路況", "type": "api", "license": "1", "cost": "free", "dataProvider": "loginaccount", "publisherOID": "2.16.886.101.20003.20008", "publisherContactName": "TDX 維運團隊", "publisherContactPhone": "02-23492803", "publisherContactEmail": "tdx@motc.gov.tw", "updateFrequency": { "regularupdate": "1", "Frequency": "1", "unittime": "分" }, "dataQuality": "", "coverageStartedDate": "", "coverageEndedDate": "", "publishedDate": "2023-02-21", "modifiedDate": "2023-04-17 10:55:08", "spatialCoverage": "臺灣", "language": "zh", "relatedUrl": "https://tdx.transportdata.tw", "notes": "請先至 TDX 平台註冊會員並建立 API Key", "apiDocUrl": "https://tdx.transportdata.tw/apiservice/swagger/basic/7f07d940-91a4-495d-9465- 1c9df89d709c#/FreewayTraffic/Live_Freeway", "distribution": [ { "resourceDescription": "取得[高速公路局]發布路段即時路況", "resourceField": [ { "name": "請參考https://tdx.transportdata.tw/apiservice/swagger/basic/7f07d940-91a4-495d-9465-1c9df89d709c#/FreewayTraffic/Live_Freeway", "description": "" } ], "resourceQualityCheckTime": "", "resourceDownloadUrl": "https://tdx.transportdata.tw/api/basic/v2/Road/Traffic/Live/Freeway", "resourceNotes": "請先至 TDX 平台註冊會員並建立API Key", "resourceRequestMethod": "GET", "resourceOasUrl": "https://tdx.transportdata.tw/backend/api/File/Swagger/V3/7f07d940-91a4-495d-9465-1c9df89d709c", "resourceRequestParameters": [ { "name": "$format", "type": "string", "required": 2, "_default": null, "description": "指定回傳資料格式" }, { "name": "$count", "type": "Boolean", "required": 2, "_default": null, "description": "查詢數量" }, { "name": "$skip", "type": "integer", "required": 2, "_default": null, "description": "跳過前幾筆" }, { "name": "$top", "type": "integer", "required": 2, "_default": null, "description": "取前幾筆" }, { "name": "$orderby", "type": "string", "required": 2, "_default": null, "description": "排序" }, { "name": "$filter", "type": "string", "required": 2, "_default": null, "description": "過濾" }, { "name": "$select", "type": "string", "required": 2, "_default": null, "description": "挑選" } ], "resourcePathParameters": [] } ], "keyword": [ "高速公路", "發布路段即時路況" ] } |
|
| 輸出說明 | 輸出內容 | 修改資料集詮釋資料結果。 |
| 輸出範例 | 1. 執行成功如下所示： { "success": true, "result": {"datasetId": "161170"} } 2. 執行失敗如下所示： { "success": false, "error": { "datasetId": "161170", "error_type":"ER0051:欲修改的資料集不存在。", "message": "欲修改的資料集不存在。"} } |
|
| 備註 | 1. 以取得資料集詮釋資料 JSON 格式示範，有關系統自動產出之欄位不得進行修改，例如 ：資料集類型（type）、資料品質（dataQuality）、上架日期（publishedDate）、詮釋資料更新時間（modifiedDate）、資料資源品質檢測時間（resource.quality_check_time），無法修改。 2. 輸出內容之資料集編號（identifier）為各資料開放平臺發布資料集的資訊編號，由各平臺自行輸入。於民國 109 年 5 月政府資料開放平臺改版後，該欄位不需填寫。 3. 提供機關物件識別碼（publisherOID），請參考物件識別碼中心網站，為提供機關物件識別碼（OID），也可為下屬機關之 OID，建立後則不得再修改。 4. 資料集識別碼（datasetId）為「政府資料開放平臺」系統自動產出流水號，作為識別資料集之唯一值，不得重複與修改。 5. 資料提供屬性(categoryDataset)欄位為標示「政府資料開放平臺」之資料服務，選項包含 A=檔案資料、B=API 服務。 |
|
5. 下架詮釋資料(緊急下架)
| 功能說明 | 下架詮釋資料(緊急下架) | |
|---|---|---|
| 服務路徑 | {SRU}/api/v2/rest/dataset/{datasetId},Method=DELETE | |
| 輸入說明 | 請求標示(headers) | Authorization:{API Key} Content-Type:application/json |
| 資源路徑 | {datasetId} | |
| 資源定義 | 資料集識別碼 | |
| 輸入範例 | {SRU}/rest/dataset/6564 | |
| 輸入參數 | 無 | |
| 輸出說明 | 輸出內容 | 資料開放平臺之資料集詮釋資料欄位和內容。 |
| 輸出範例 | 1. 執行成功如下所示： { "success": true, "result": { "datasetId": "6564"} } 2. 執行失敗如下所示： { "success": false, "error": { "datasetId":"656", "error_type":"ER0052:欲下架的資料集不存在。", "message":"欲下架的資料集不存在。"} } |
|
| 備註 | 1. 資料集下架即為永久下架，不得再重新上架。 2. 詮釋資料同步下架完成，即同步移除其資料集識別碼（datasetId）。 |
|
5. 下架詮釋資料(一般下架)
| 功能說明 | 下架詮釋資料(一般下架) | |
|---|---|---|
| 服務路徑 | {SRU}/api/v2/rest/dataset/{datasetId},Method=DELETE | |
| 輸入說明 | 請求標示(headers) | Authorization:{API Key} Content-Type:application/json |
| 資源路徑 | {datasetId} | |
| 資源定義 | 資料集識別碼 | |
| 輸入範例 | {SRU}/rest/dataset/6564 | |
| 輸入參數 | 以 JSON 格式示範下架資料集詮釋資料(一般下架)的欄位和內容： { "unpublishType": "history", "unpublishDate": "2023-05-04", "unpublishNote": "資料集將於2023-11-04下架 (資 料資源在下架後將移除)" } |
|
| 輸出說明 | 輸出內容 | 執行成果與資料集識別碼 |
| 輸出範例 | 1. 執行成功如下所示： { "help": "", "success": true, "result": { "datasetId": "157392", "message": "資料集已在下架中，將於指定下架日 期下架" } } 2. 執行失敗如下所示： { "success": false, "error": { "error_type": "ER0051:欲修改的資料集不存在", "message": "資料集處於不允許修改的狀態" } } |
|
| 備註 | 1. 一般下架之下架時間需大於當天+7 天，若不符合則無法下架。 2. 介接成功後，資料集將轉為下架中狀態，待下架時間後即進入下架(歷史資料專區)。 |
|
（三）資料集移轉
提供各資料開放平臺更新「政府資料開放平臺」同一機關資料集移轉之功能，必須配合所設定之資料來源 IP 和 API KEY。其功能如下表所列：
| 功能說明 | 同一機關資料集移轉 | |
|---|---|---|
| 服務路徑 | {SRU}/api/v2/rest/dataset/transfer/provider,Method=PUT | |
| 輸入說明 | 請求標示(headers) | Authorization:{API Key} Content-Type:application/json |
| 資源路徑 | 無 | |
| 資源定義 | 無 | |
| 輸入範例 | {SRU}/api/v2/rest/dataset/transfer/provider | |
| 輸入參數 | 以 JSON 格式示範同一機關資料集移轉的欄位和內容： { "publisherOID":"2.16.886.101.90003.20002.2005 7", "targetDataProvider":"S123148189", "datasetId":[157490] } |
|
| 輸出說明 | 輸出內容 | 執行成果 |
| 輸出範例 | 1. 執行成功如下所示： { "help": "", "success": true, "result": "資料移轉成功" } 2. 執行失敗如下所示： { "success": false, "error": { "error_type": "ER0077:使用者角色錯誤", "message": "使用者錯誤 " } }備註1. 提供機關物件識別碼（publisherOID），請參考物件識別碼中心網站，為提供機關物件識別碼（OID）。 2. 資料集識別碼（datasetId）為「政府資料開放平臺」系統自動產出流水號，作為識別資料集之唯一值，不得重複與修改。 3. 目標資料提供者(targetDataProvider)為資料集移轉目標之帳號，請確認該帳號具有資料集所屬機關資料提供者權限。 |
|
（四）提供機關管理所屬公務帳號及其權限
提供各資料開放平臺管理「政府資料開放平臺」之資料集提供機關所屬公務帳號及其權限，必須配合所設定之資料來源 IP 與 API KEY。其功能如下表所列：
| 功能說明 | 管理所屬機關提供資料集之公務帳號及其權限 | |
|---|---|---|
| 服務路徑 | {SRU}/api/v2/rest/agency/roles, Method=GET | |
| 輸入說明 | 請求標示(headers) | Authorization:{API Key} Content-Type:application/json |
| 資源路徑 | 無 | |
| 資源定義 | 無 | |
| 輸入範例 | {SRU}/api/v2/rest/agency/roles | |
| 輸入參數 | 無 | |
| 輸出說明 | 輸出內容 | 取得所屬機關公務帳號及其權限。 |
| 輸出範例 | 1. 執行成功如下所示： { "help": "", "success": true, "result": [ { "agencyName": "臺北市政府", "oid": "2.16.886.101.90003.20002", "account": "AAA01", "roleName": "資料提供者" }, { "agencyName": "臺北市政府", "oid": "2.16.886.101.90003.20002", "account": "AAA02", "roleName": "機關管理者" } ] } 2. 執行失敗如下所示： { "success": false, "error": { "error_type": "ER0001:API Key 錯誤", "message": "API Key 錯 誤 ： 平 臺 上 不 存 在 此 APIKey 相對應的機關" } } |
|
| 備註 | 依據 API Key 提供所屬機關之帳號及其權限。 | |
（五）錯誤訊息代碼一覽表
| 錯誤代碼 | 訊息內容 | 說明 |
|---|---|---|
| ER0000 | 系統例外 | 系統例外。 |
| ER0001 | API KEY 錯誤 | API KEY 錯誤。 |
| ER0002 | 來源 IP 不允許 | 來源 IP 不允許。 |
| ER0003 | JSON 格式錯誤 | JSON 格式錯誤。 |
| ER0020 | 必填欄位未填 | 必填欄位未填，於 message 中顯示未填的必填欄位名稱。 主題分類(categoryTheme)未填 服務分類(categoryService)未填 資料提供屬性(categoryDataset)未填 資料集名稱(title)未填 資料集描述(description)未填 授權方式(license)未填 計費方式(cost)未填 資料提供者(dataProvider)未填 提供機關物件識別碼(publisherOID)未填 提供機關聯絡人姓名(publisherContactName)未填 提供機關聯絡人電話(publisherContactPhone)未填 提供機關聯絡電子郵件(publisherContactEmail)未填 更新頻率(updateFrequency)未填 檢測頻率(detectFrequency)未填 上架日期(publishedDate)未填 語系(language)未填 資料資源欄位(resourceField)未填 檔案格式(resourceFormat)未填 編碼格式(resourceCharacterEncoding)未填 資料下載網址(resourceDownloadUrl)未填。 |
| ER0030 | 欄位資料型態錯誤 | 欄位資料型態錯誤，於 message 中顯示錯誤的欄位名稱與內容。 資料集識別碼(datasetId)不可修改 資料集類型(type)不可修改 資料品質(dataQuality)不可修改 上架日期(publishedDate)不可修改 詮釋資料更新時間(modifiedDate)不可修改 資料資源品質檢測時間(resource.quality_check_time)不可修改 提供機關物件識別碼(publisherOID)不可修改 輸入提供機關聯絡電子郵件(publisherContactEmail)資料型態錯誤 輸入開始收錄日期(coverageStartedDate)資料型態錯誤 輸入結束收錄日期(coverageEndedDate)資料型態錯誤 輸入資料資源欄位(resourceField)資料型態錯誤。 |
| ER0031 | 資料集服務分類不存在 | 資料集服務分類錯誤：無此服務分類 categoryService=XXX。 |
| ER0032 | 資料集主題分類不存在 | 資料集主題分類錯誤：無此主題分類 categoryTheme=XXX。 |
| ER0033 | 資料提供分類不存在 | 資料提供分類錯誤：無此資料提供分類 categoryDataset=XXX。 |
| ER0034 | 資料集類型不存在 | 資料集類型錯誤：無此資料集類型 type=XXX。 |
| ER0035 | 授權方式不存在 | 授權方式錯誤：無此授權方式 license=XXX。 |
| ER0036 | 計費方式不存在 | 計費方式錯誤：無此計費方式 cost=XXX。 |
| ER0037 | 檢測頻率不存在 | 檢測頻率錯誤：無此檢測頻率 detectFrequency=XXX。 |
| ER0038 | 語系不存在 | 語系錯誤：無此語系 language=XXX。 |
| ER0039 | 檔案格式不存在 | 檔案格式錯誤：無此檔案格式 resourceFormat=XXX。 |
| ER0040 | 編碼格式不存在 | 編碼格式錯誤：無此編碼格式 resourceCharacterEncoding=XXX。 |
| ER0041 | 資料集識別碼不存在 | 資料集識別碼不存在：無此資料集識別 datasetId=XXX。 |
| ER0042 | 提供機關物件識別碼不存在 | 提供機關物件識別碼不存在：無此提供機關物件識別碼 publisherOID=2.16.886.101.20003|國發會。 |
| ER0050 | 欲新增的資料集已存在 | 同一提供機關物件識別碼不得重複使用相同資料集識別碼(datasetId)。 |
| ER0051 | 欲修改的資料集不存在 | 欲修改的資料集不存在。 |
| ER0052 | 欲下架的資料集不存在 | 欲下架的資料集不存在。 |
| ER0071 | 資料集名稱重複 | 同一提供機關物件識別碼不得重複使用相同資料集名稱。 |
| ER0072 | 平臺無此資料提供者 | 平臺無此資料提供者。 |
| ER0073 | 資料下載網址重複 | 資料下載網址（resourceDownloadUrl）重複輸入： "resourceDownloadUrl":"https://example.gov.tw"。 |
| ER0074 | 資料下載網址不允許 | 資料下載網址 resourceDownloadUrl 錯誤：支援 http 和 https 兩種協定。 |
| ER0075 | 欄位超過字元限制 | 欄位超過字元限制。 |
| ER0076 | 不允許資料集描述與資料集名稱相同 | 不允許資料集描述與資料集名稱相同。 |