跳至主要內容

政府資料開放平臺

:::

陸、跨平臺介接協定與功能(我有話要說)

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

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

(一)取得我有話要說民眾意見及機關回應(單筆)

透過取得我有話要說民眾意見及機關回應 API 擷取我有話要說民眾意見及機關回應，其功能如下表所列。

表 3:取得我有話要說民眾意見及機關回應
功能說明 取得我有話要說民眾意見及機關回應
服務路徑 {SRU}/api/v2/rest/comments/{datasetId}, Method=GET
輸入說明 資源路徑 {datasetId}
資源定義 資料集識別碼
輸入範例 {SRU}/api/v2/rest/comments/6564
輸入參數 無
輸出說明 輸出內容 政府資料開放平臺之我有話要說民眾意見及機關回應欄位和內容。
輸出範例 "dataset": {
"datasetId": "6564",
"title": "政府資料開放平臺資料集清單"
},
"result": [
{
"commentId": "535040",
"pid": "0",
"subject": "建議新增「資料集標籤」欄位內容",
"comment_body_value": "管理員，您好：\r\n不好意思打擾了，關於此資料集的內容希望能夠新增「資料集標籤」的欄位內容，使得可以透過標籤查詢相關的 Open Data，再煩請評估新增，非常感謝！",
"name": "J****y",
"create_time": "2017-09-10 19:29:14"
},
{
"commentId": "537317",
"pid": "0",
"subject": "下載頁面出現錯誤",
"comment_body_value": "管理者您好，\r\n目前「政府資料開放平臺資料集清單」的下載連結似乎壞了，是否能協助處理呢？感謝~",
"name": "J****y",
"create_time": "2017-09-04 15:11:52",
"reply_status": "已回復"
"reply": [
{
"commentId": "537355",
"pid": "537317",
"subject": "Re:下載頁面出現錯誤",
"comment_body_value": "您好,\r\n「政府資料開放平臺資料集清單」下載連結已修復。\r\n謝謝您對政府資料開放之支持與關心，祝您身體健康一切如意。國家發展委員會敬復",
"name": "y****g",
"create_time": "2017-07-07 21:32:51",
}
]
}
]
備註 1.資料集識別碼（datasetId）為「政府資料開放平臺」系統自動產出流水號，作為識別資料集之唯一值，不得重複與修改。
2.我有話要說識別碼(commentId)為「政府資料開放平臺」系統自動產出流水號，作為識別我有話要說之唯一值，不得重複與修改。
3.輸出範例的 reply 為機關首次回應、民眾首次意見、機關對首次回應補充、機關貳次回應、民眾貳次意見、機關對貳次回應補充之內容。
4.reply_status 欄位為回復狀態，若機關未回復，狀態顯示「未回復」；若機關已回復，狀態顯示「已回復」；若機關需貳次回復，狀態顯示「再回復」

(二)取得我有話要說民眾意見及機關回應(批次)

透過取得我有話要說民眾意見及機關回應 API 擷取我有話要說民眾意見及機關回應，其功能如下表所列。

表 4:取得我有話要說民眾意見及機關回應
功能說明 批次取得我有話要說民眾意見及機關回應
服務路徑 {SRU}/api/v2/rest/agency/comment, Method=GET
輸入說明 資源路徑 無
資源定義 無
輸入範例 {SRU}/api/v2/rest/agency/comment
輸入參數 可輸入 reply_status，包含已回復、未回復及再回復
範例:
{SRU}/api/v2/rest/agency/comment?reply_status=已回復
輸出說明 輸出內容 政府資料開放平臺之我有話要說民眾意見及機關回應欄位和內容。
輸出範例 {
"help": "",
"success": true,
"result": {
"84429": {
"543015": {
"nid": 84429,
"cid": 543015,
"title": "資料無法下載",
"body": "資料無法下載",
"reply_status": "已回復"
},
"543128": {
"nid": 84429,
"cid": 543128,
"title": "未進行更新",
"body": "未進行更新",
"reply_status": "再回復"
}
}
}
}
備註 1.資料集識別碼（nid）為「政府資料開放平臺」系統自動產出流水號，作為識別資料集之唯一值，不得重複與修改。
2.我有話要說識別碼(cid)為「政府資料開放平臺」系統自動產出流水號，作為識別我有話要說之唯一值，不得重複與修改。
3.輸出範例的 title 及 body 為民眾首次意見之內容。
4.reply_status 欄位為回復狀態，若機關未回復，狀態顯示「未回復」；若機關已回復，狀態顯示「已回復」；若機關需貳次回復，狀態顯示「再回復」。

(三)呼叫回應/補充我有話要說

提供「提供者/平臺」新增「政府資料開放平臺」之我有話要說回應及補充資料，必須配合所設定之資料來源 IP 和 API KEY。其功能如下表所列：

1.新增我有話要說機關回應(機關首次/貳次回應民眾)

表 5:新增我有話要說機關回應(機關首次/貳次回應民眾)
功能說明 新增我有話要說機關回應(機關首次/貳次回應民眾)
服務路徑 {SRU}/api/v2/rest/comments/{datasetId}/{commentId}, Method=POST
輸入說明 資源路徑 {datasetId}/{commentId}
資源定義 資料集識別碼/我有話要說識別碼
輸入範例 {SRU}/api/v2/rest/comments/6564/537317
輸入參數 以 JSON 格式示範我有話要說回應資料(機關首次/貳次回應民眾)的欄位和內容：
{
"subject":"RE:民眾回應之標題",
"comment_body_value":"RE:民眾回應之內容",
"dataProvider":"loginaccount",
"comment_stage":"first"(滿意度評分低於 3 星，機關須貳次回應時填入"second")
}
輸出說明 輸出內容 新增我有話要說回應資料之結果。
輸出範例 1.執行成功如下所示：
{
"success": true,
"message": "回應成功。回應 CID：537355"(系統產生),
"result": {
"datasetId": "6564",
"commentId": "537355",
"pid": "537317",
"name": "loginaccount",
"created": "2017-07-07 21:32:51",
"subject": "RE:民眾回應之標題",
"comment_body_value": "RE:民眾回應之內容"
}
}
2.執行失敗如下所示：
{
"success": false,
"error": {
"datasetId": "6564",
"error_type": "ER0078:comment_stage 錯誤",
"message": "firstcomment_stage 填入錯誤"}
}
備註 1.資料集識別碼（datasetId）為「政府資料開放平臺」系統自動產出流水號，作為識別資料集之唯一值，不得重複與修改。
2.我有話要說識別碼(commentId)為「政府資料開放平臺」系統自動產出流水號，作為識別我有話要說之唯一值，不得重複與修改。
3.輸入參數 dataProvider 必須填入該筆資料集的資料提供者帳號。
4.新增我有話要說回應資料(機關首次/貳次回應民眾)需填入民眾我有話要說留言之我有話要說識別碼(commentId)。
5.輸入參數 comment_stage 內容包含 first、second，機關針對民眾回應進行首次回應或貳次回應之區別

2.新增我有話要說機關補充(機關首次/貳次補充回應)

表 6:新增我有話要說機關補充(機關首次/貳次補充回應)
功能說明 新增我有話要說機關補充(機關首次/貳次補充回應)
服務路徑 {SRU}/api/v2/rest/comments_ps/{datasetId}/{commentId}, Method=POST
輸入說明 資源路徑 {datasetId}/{commentId}
資源定義 資料集識別碼/我有話要說識別碼
輸入範例 {SRU}/api/v2/rest/comments/6564/537355
輸入參數 以 JSON 格式示範我有話要說補充資料(機關首次/貳次補充回應)的欄位和內容：
{
"subject":"補充:機關首次回應之標題",
"comment_body_value":"補充:機關首次回應之內容",
"dataProvider":"loginaccount",
"comment_stage":"first"(機關對貳次回應進行補充時填入"second")
}
輸出說明 輸出內容 新增我有話要說補充資料之結果。
輸出範例 1.執行成功如下所示：
{
"success": true,
"message": "回應成功。回應 CID：537356",
"vote": "",
"result": {
"datasetId": "6564",
"commentId": "537356",
"pid": "537355",
"name": "loginaccount",
"created": "2017-07-08 12:27:14",
"subject": "補充:機關首次回應之標題",
"comment_body_value": "補充:機關首次回應之內容"
}
}
2.執行失敗如下所示：
{
"success": false,
"error": {
"datasetId": "6564",
"error_type": "ER0077:CID 錯誤",
"message": "此 CID 填入錯誤，請確認 CID 號碼與狀態"
}
}
備註 1.資料集識別碼（datasetId）為「政府資料開放平臺」系統自動產出流水號，作為識別資料集之唯一值，不得重複與修改。
2.我有話要說識別碼(commentId)為「政府資料開放平臺」系統自動產出流水號，作為識別我有話要說之唯一值，不得重複與修改。
3.輸入參數 dataProvider 必須填入該筆資料集的資料提供者帳號。
4.新增我有話要說補充資料(機關首次/貳次補充回應)需填入機關首次/貳次回應之我有話要說識別碼(commentId)。若是針對機關首次回應進行補充，{commentId} 填入機關首次回應系統自動產生之 commentId，若為針對機關貳次回應進行補充，{commentId} 填入機關貳次回應系統自動產生之 commentId。
5.輸入參數 comment_stage 內容包含 first、second，機關針對機關首次回應之補充或貳次回應之補充區別。

(四)錯誤訊息代碼一覽表

錯誤代碼 訊息內容 說明
ER0001 API Key 錯誤 API Key 錯誤
ER0002 來源 IP 不允許 來源 IP 不允許
ER0020 必填欄位未填 1.我有話要說標題(subject)未填
2.我有話要說內容(comment_body_value)未填
3.資料集提供者(dataProvider)未填
4.回應次(comment_stage)未填
ER0076 資料提供者錯誤 非本資料集之資料提供者
ER0077 commentId 錯誤 此 commentId 填入錯誤，請確認 commentId 號碼與狀態
ER0078 comment_stage 錯誤 comment_stage 填入錯誤
ER0079 民眾尚未評分或滿意度評分大於 3 星 此筆我有話要說民眾尚未評分或滿意度評分大於 3 星以上，無須進行貳次回復。