Posted in

By

第 17 / 33 篇更新於 2026-11-17約 18 分鐘English

REST API是網路通訊技術中廣泛被使用的介面架構,可用於和第三方服務交換資料,優點為簡易方便的設計性與實用性,並遵守安全可靠有效率的通訊標準。

網路應用程式可以使用REST API傳送請求(Request)到伺服器,接著伺服器便會回傳回應(Response),以達到資訊交換的需求。整個通訊過程是基於REST架構所設計定義的標準規則,使用標準的HTTP方法,包括GET、PUT、POST。

HMI可以透過REST API功能對外部網路伺服器傳送請求(Request),透過POST/PUT將裝置(HMI,PLC)暫存器位址的資料傳送到伺服器的資料庫,也能透過GET從伺服器獲得資料將其讀取寫入暫存器位址。

本章將說明REST API的相關頁面與設定方式。

※此功能僅支援P5系列、FvRT

圖 210 應用示意圖

17.1 REST API用戶端

勾選【啟用REST API】,即可在【請求列表】增加新的REST請求。可在右方點擊【新增】按鈕新增一個新的請求、點擊【刪除】按鈕刪除選中的請求、點擊【編輯】或雙擊項目可編輯內容。

圖 211 【REST API用戶端】設定分頁

17.1.1 REST API用戶端設定

以下針對設定介面作介紹

圖 212 【REST請求】設定畫面

表 107 【REST請求】編輯視窗設定屬性

欄位

描述

【名稱】

設定請求的名稱,可作為描述說明。

【網址】

傳送請求取得資料的伺服器網址。

【位址】

使用變數更換連線的網址。

【發送模式】

【週期式】

定期發送請求,可設定間隔秒數。

【數值變化觸發】

數據項目的數值有變化才會發送請求。
(注意:訊息內容只會發送有數值變化的項目)

【位元控制】

設定用bit做觸發條件。

【檔案監控】

資料格式選擇form-data時可選,點選後在介面上可設定監控的檔案路徑。

【方法】

常用的資料傳送方法,說明如下:

名稱

說明

POST

新增-向伺服器「新增」一筆新的資料。

PUT

更新-向伺服器「更新」或「替換」指定的資料。

GET

讀取-從伺服器「取得」一筆或多筆資料

【資料格式】

【JSON】

常用的標準格式,格式範例:

{

"id": 111,

"name": "fatek",

"url": "https://www.fatek.com/",

"status": 100

}

(注意:如格式內容與上面範例不同時,請選擇使用【自訂】)

【自訂】

可自行定義格式,需注意自訂資料所使用的格式是【Text】。

【form-data】

可設定讀取的目錄及檔案名稱,將檔案POST到目標位置。

【狀態位址】

此處可將執行結果顯示於暫存器中

數值(16Bit-INT)

說明

100 ~ 199

資訊性

200 ~ 299

成功

300 ~ 399

重新導向-

400 ~ 499

用戶端錯誤

500 ~ 599

伺服器錯誤

-1

檔案錯誤

-2

超時

-3

無效

-4

檔案監控錯誤

-5

回應資料格式/類型不匹配

其他

未知錯誤

【標頭 (Heaters)】

標頭支援兩種Content-Type,分別是

application/json – 傳送JSON資料

multipart/form-data – 傳送檔案或混合資料

【標頭項目數量】

設定請求的標題項目數量。

【內容-請求 (Body – Request)】

請求方法選擇POST或PUT時可見,這裡用於編輯向伺服器發送的資料。

【數據項目數量】

設定請求的數據項目數量。

【位址類型】

  • 【連續】

在下方的數據項目設定表格中只有第一個項目可以設定位址,其他項目的位址都會自動產生,使用者不能修改。

  • 【隨機】

使用者可以設定每一個數據項目的位址。

【數據項目設定】

  • 【名稱】

項目的名稱不得空白,項目名稱不能重複。

  • 【資料類型】

設定請求的資料類型。

  • 【位址】

依照數據類型,使用者可設定每一個數據項目的位址。

  • 【長度】

設定請求的資料長度。若數據類型是16-bit會佔用1個字組、32-bit會佔用2個字組;若是Ascii-String,使用者可以決定此數據項目要佔用幾個字組。每1個字組可以容納2個字元。

【自訂資料格式】

可自訂資料發送格式。

【檔案設定】

資料格式選擇form-data時可見

  • 【位置】

選擇讀取的檔案空間

  • 【目錄】

填寫檔案所在的路徑,例如:datalog/Group_1

  • 【檔案名稱】

填寫檔案名稱

【內容-回應(Body – Response)】

若向伺服器發送請求後有回應,可以使用此欄位解析,需注意若與目標結構不同將無法解析資料。

17.1.2 REST API應用範例

以下示範取得Taipai當前氣溫專案,請注意這是基於openweathermap.org的API所製作的範例,無法保證隨時能取得數值。

步驟1.

在【網址】欄位輸入

http://api.openweathermap.org/data/2.5/weather?lat=25.0481&lon=121.5170&appid=3ec3e04b911a8e4da5c834f60b00e580&units=metric

在【方法】欄位選擇【GET】,在【資料格式】欄位選擇【JSON自訂】

步驟2.

設定數據項目,【數據項目數量】設定【3】,

%1選擇32bit-float,%2及 %3選擇Ascii,長度使用預設值即可,需注意位址不能重複。

步驟3.

在自訂資料格式欄位填寫

%2,"main":{"temp":%1,%3

參數代表內容請參考https://openweathermap.org/api/one-call-3

步驟4.

將%1對應的位址使用數值輸入器放在畫面中,編譯專案後使用線上模擬或下載至HMI即可看見數值。

圖 213 【REST API客戶端】範例設定分頁

17.2 REST API伺服器

勾選【啟用REST API伺服器】,即可設定REST API伺服器各項屬性以及資源,資源指的是伺服器中可被唯一識別並進行讀取或修改的資料或服務,每一個資源都對應到一個網址。

※此功能限制使用FvRT及P5Z(G03含/以上)的設備類型才能使用

圖 214 【REST API伺服器】設定分頁

表 108 【REST API伺服器】編輯視窗設定屬性

欄位

描述

【啟用REST API伺服器】

勾選是否啟用【REST API伺服器】。

【基本】

【連接埠】

設定伺服器的連接埠。預設為8000。

【連線逾時】

伺服器在與用戶端建立連線後,若在此指定時間內沒有接收到完整的請求資料或沒有後續互動,將自動中斷該連線。目的是避免閒置或異常連線長時間佔用資源。以秒為單位,最多可設至300秒。

【最大連線數】

伺服器在同一時間內可同時處理的最大用戶端連線數量。防止連線過多耗盡資源。最多可設至20個。

【進階】

【自動啟動】

勾選後,開機後就會自動啟動伺服器的運行。

【狀態位址】

使用狀態位址可監看伺服器的運行狀態。

以下為狀態定義表,也可直接點擊 查看:

編號

數值(16Bit-INT)

定義

1

0

未啟用

2

1

已停止

3

2

運行中

4

-1

錯誤

【控制位址】

使用控制位址可控制伺服器的運行。

以下為控制定義表,也可直接點擊 查看:

編號

數值(16Bit-INT)

定義

1

0

無

2

1

停止

3

2

啟動

【啟用驗證】

欲設定伺服器使用驗證,可勾選啟用後並設定以下:

【使用者名稱】輸入登入驗證用的名稱。

【密碼】輸入完會用暗文保密。

【啟用TLS】

欲設定伺服器使用TLS加密訊息傳輸,可勾選啟用後並設定以下:

【TLS版本】目前預設使用HMI內建的自簽憑證。

(未來會再開放可匯入其他的憑證私鑰檔案)

17.2.1 新增資源列表

設定伺服器可處理的資源網址、資料項目、支援的方法,以及回傳的詳細內容。

圖 215 【REST 資源】【數據項目】設定畫面

圖 216 【REST 資源】【檔案】設定畫面

表 109 【REST資源】設定屬性

欄位

描述

【基本】

【名稱】

設定資源的名稱,作為描述說明。

【網址】

定義資源的路徑位置,例如 redfish/v1/Systems。

外部用戶端可透過此網址發送請求。

*注意網址開頭固定為"http(s)://HMI IP:Port/"

• 啟用TLS時使用https://

• 未啟用TLS時使用http://

• HMI IP:人機IP位址

• Port:伺服器設定的連接埠

【內容類型】

點選時會出現選單,用於設定資源網址接收請求時所使用的資料格式

【數據項目 (application/json)】

可透過JSON格式讀寫數據項目資料。

【檔案 (application/octet-stream)】

可上傳檔案。

【數據項目設定】

當【內容類型】選擇【數據項目 (application/json)】才會出現的欄位

【數據項目數量】

設定此資源的數據項目數量。

【位址類型】

【連續】

在下方的數據項目設定表格中只有第一個項目可以設定位址,其他項目的位址都會自動產生,使用者不能修改。

【隨機】

使用者可以設定每一個數據項目的位址。

以下是數據項目的設定說明:

【名稱】數據項目的名稱不得為空白,而且每個項目名稱必須是獨一無二的,項目名稱可以直接輸入。

【資料類型】可以選擇數據項目的資料類型。

【位址】依照資料類型,使用者可設定每一個數據項目的位址。

【長度】使用者可以決定此數據項目要佔用幾個字組(每1個字組可以容納2個字元)

【可寫入】指定該數據項目是否允許修改資料。勾選表示可寫入;未勾選則表示不可寫入、僅可讀取。

【註解】可自行填入該數據項目的說明備註,也可以留空白。

【檔案設定】

當【內容類型】選擇【檔案 (application/octet-stream)】才會出現的欄位。

【位置】

使用者可設定檔案上傳的目標位置,包含人機內部儲存、SD卡、USB。

【預設檔名】

用戶端發送請求時可以指定檔名,但若是沒有指定檔名,上傳的檔案名稱會使用此預設檔名,例如:file.bin, test.txt, img.jpg。可修改但不可為空白。

【重複檔名處理規則】

當相同名稱的檔案已存在時,可選擇要如何處理:

【取代】

直接覆寫已存在的檔案。

【略過】

跳過不處理,不會進行上傳新檔案的動作。

【重新命名加上時間戳】

將原本的檔名加上時間戳重新命名後,上傳成新的檔案。例如原本的"file.bin"變成"file_2025-12-19T16-18-48.093.bin"。

【回應設定】

【方法】

針對該資源網址可支援的請求方法:

名稱

用途

GET

讀取 (全部數據項目)

PATCH

寫入部份 (可指定單個或多個數據項目)

PUT

寫入全部 (需指定所有可以寫入項目,缺少會報錯)

POST

上傳檔案

方法可以多選,但至少要選擇一個方法。

勾選的方法會顯示對應的設定分頁,用於編輯回應訊息內容:

【GET】

欄位

詳細說明

【成功訊息】

HTTP 狀態碼:200

預設為基本的單層JSON格式:{"DataItem0":%1,"DataItem1":%2,"DataItem2":%3,"DataItem3":%4,"DataItem4":%5}

(*變數的關鍵字表示數據項目值:%n,n可為1或2或3,以此類推)也可依照需求自訂較複雜的多層資料格式,必須符合JSON格式即可。

若勾選【自動在數據項目編輯後更新訊息】,當數據項目名稱或數量有編輯修改後,就會依照基本單層JSON格式去自動更新訊息內容。

(*建議想要自訂格式就不要勾選此項,否則會回到預設的單層JSON格式)

【重設】

依照目前的數據項目設定,

重新將訊息設回基本的單層JSON格式。

【預覽】

依照資料類型顯示完整訊息範例,

須符合JSON格式才能正確顯示。

【錯誤訊息】

HTTP 狀態碼:4XX

目前的錯誤訊息皆為預設固定:

{"message":"Reject Request"}

【PATCH】

欄位

詳細說明

【成功訊息】

HTTP 狀態碼:200

預設訊息為:

{"message":" Updated Successfully"}

可修改自訂,必須符合JSON格式即可。

【重設】

重新設回預設訊息。

【預覽】

依照設定顯示完整訊息,須符合JSON格式才能正確顯示。

【錯誤訊息】

HTTP 狀態碼:4XX

目前的錯誤訊息皆為預設固定:

{"message":"Reject Request"}

【PUT】

欄位

詳細說明

【成功訊息】

HTTP 狀態碼:200

預設訊息為:

{"message":" Updated Successfully"}

可修改自訂,必須符合JSON格式即可。

【重設】

重新設回預設訊息。

【預覽】

依照設定顯示完整訊息,須符合JSON格式才能正確顯示。

【錯誤訊息】

HTTP 狀態碼:4XX

目前的錯誤訊息皆為預設固定:

{"message":"Reject Request"}

【POST】

欄位

詳細說明

【成功訊息】

HTTP 狀態碼:200

預設訊息為:

{"message":" Updated Successfully"}

可修改自訂,必須符合JSON格式即可。

【重設】

重新設回預設訊息。

【預覽】

依照設定顯示完整訊息,須符合JSON格式才能正確顯示。

【錯誤訊息】

HTTP 狀態碼:4XX

目前的錯誤訊息皆為預設固定:

{"message":"Reject Request"}

17.2.2 常見測試工具

-curl指令

curl是系統內建的命令列網路工具,可用來向伺服器發送REST請求並接收回應。

基本語法

curl -X [方法] [URL]

常見測試範例

  1. GET方法(讀取資料)

curl -X GET http://192.168.0.100:8000/data

用來確認伺服器有回應、能成功取得資料。

  1. PATCH方法(修改資料)

curl -X PATCH http://192.168.0.100:8000/data \

-H "Content-Type: application/json" \

-d "{\"status\":\"on\"}"

可用-d傳送JSON格式資料給伺服器,測試寫入功能。

  1. PUT方法(修改全部資料)

curl -X PUT http://192.168.0.100:8000/data \

-H "Content-Type: application/json" \

-d "{\"status\":\"on\" ,\"level\":3,\"enabled\":true}"

可用-d傳送JSON格式資料給伺服器,測試一次寫入全部的功能。

  1. POST方法(上傳檔案)

curl -X POST http://192.168.0.100:8000/file \

-H "Content-Type: application/octet-stream" \

–data-binary "@C:\test.bin" \

-H "X-Filename: test_upload.bin"

可用–data-binary指定欲上傳的檔案,可用-H "X-Filename"指定檔名。

  1. Basic Authentication測試

curl -u username:password -X GET http://192.168.0.100:8000/data

若伺服器啟用了帳號密碼驗證,可用-u帶入登入資訊。

  1. HTTPS(TLS)測試

curl -k -X GET https://192.168.0.100:8000/data

-k參數用來信任伺服器自簽憑證,方便在測試階段使用。

-Postman

一款常用的API測試工具,可用於發送各種REST請求,並檢視伺服器的回應結果。

  1. 在Request URL欄位輸入伺服器的資源網址,例如:https://192.168.0.100:8000/test
  2. 從下拉選單選擇請求方法(例如GET或PATCH)。
  3. 若需要身份驗證,點選Authorization分頁,選擇「Basic Auth」並輸入使用者名稱(Username)與密碼(Password)。
  4. 若啟用TLS時使用預設的HMI內建自簽憑證,請點選Settings分頁,將「Enable SSL certificate verification」選項關掉(OFF)
  5. 若需傳送資料(例如PATCH請求),可於Body分頁選擇「raw」以及「JSON」格式,輸入JSON格式的內容。
  6. 若需上傳檔案(例如POST請求),可於Body分頁選擇「binary」及匯入欲上傳的檔案,並在Headers分頁設定「Key/Value」,如下:

Key

Value

Content-Type

application/octet-stream

X-Filename

指定檔名(例如:file.bin, test.txt, img.jpg)

(若沒有特別指定Content-Type,Postman會依據副檔名自動轉換成其他內容類型導致錯誤)

  1. 按下Send按鈕,即可看到伺服器的回應內容與狀態碼。

圖 217 使用GET範例畫面

圖 218 使用POST範例畫面

這篇文件對您有幫助嗎?

提示:按 ← → 切換章節,Ctrl+K 搜尋