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時可選,點選後在介面上可設定監控的檔案路徑。 |
||||||||||||||||||||||||
|
【方法】 |
常用的資料傳送方法,說明如下:
|
||||||||||||||||||||||||
|
【資料格式】 |
【JSON】 常用的標準格式,格式範例:
(注意:如格式內容與上面範例不同時,請選擇使用【自訂】) 【自訂】 可自行定義格式,需注意自訂資料所使用的格式是【Text】。 【form-data】 可設定讀取的目錄及檔案名稱,將檔案POST到目標位置。 |
||||||||||||||||||||||||
|
【狀態位址】 |
此處可將執行結果顯示於暫存器中
|
||||||||||||||||||||||||
|
【標頭 (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個。 |
|||||||||||||||||||||||||||
|
【進階】 |
【自動啟動】 勾選後,開機後就會自動啟動伺服器的運行。 【狀態位址】 使用狀態位址可監看伺服器的運行狀態。 以下為狀態定義表,也可直接點擊
【控制位址】 使用控制位址可控制伺服器的運行。 以下為控制定義表,也可直接點擊
|
|||||||||||||||||||||||||||
|
【啟用驗證】 |
欲設定伺服器使用驗證,可勾選啟用後並設定以下: 【使用者名稱】輸入登入驗證用的名稱。 【密碼】輸入完會用暗文保密。 |
|||||||||||||||||||||||||||
|
【啟用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】
|
17.2.2 常見測試工具
-curl指令
curl是系統內建的命令列網路工具,可用來向伺服器發送REST請求並接收回應。
基本語法
curl -X [方法] [URL]
常見測試範例
- GET方法(讀取資料)
curl -X GET http://192.168.0.100:8000/data
用來確認伺服器有回應、能成功取得資料。
- PATCH方法(修改資料)
curl -X PATCH http://192.168.0.100:8000/data \
-H "Content-Type: application/json" \
-d "{\"status\":\"on\"}"
可用-d傳送JSON格式資料給伺服器,測試寫入功能。
- 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格式資料給伺服器,測試一次寫入全部的功能。
- 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"指定檔名。
- Basic Authentication測試
curl -u username:password -X GET http://192.168.0.100:8000/data
若伺服器啟用了帳號密碼驗證,可用-u帶入登入資訊。
- HTTPS(TLS)測試
curl -k -X GET https://192.168.0.100:8000/data
-k參數用來信任伺服器自簽憑證,方便在測試階段使用。
-Postman
一款常用的API測試工具,可用於發送各種REST請求,並檢視伺服器的回應結果。
- 在Request URL欄位輸入伺服器的資源網址,例如:https://192.168.0.100:8000/test
- 從下拉選單選擇請求方法(例如GET或PATCH)。
- 若需要身份驗證,點選Authorization分頁,選擇「Basic Auth」並輸入使用者名稱(Username)與密碼(Password)。
- 若啟用TLS時使用預設的HMI內建自簽憑證,請點選Settings分頁,將「Enable SSL certificate verification」選項關掉(OFF)
- 若需傳送資料(例如PATCH請求),可於Body分頁選擇「raw」以及「JSON」格式,輸入JSON格式的內容。
- 若需上傳檔案(例如POST請求),可於Body分頁選擇「binary」及匯入欲上傳的檔案,並在Headers分頁設定「Key/Value」,如下:
|
Key |
Value |
|
Content-Type |
application/octet-stream |
|
X-Filename |
指定檔名(例如:file.bin, test.txt, img.jpg) |
(若沒有特別指定Content-Type,Postman會依據副檔名自動轉換成其他內容類型導致錯誤)
- 按下Send按鈕,即可看到伺服器的回應內容與狀態碼。

圖 217 使用GET範例畫面

圖 218 使用POST範例畫面
提示:按 ← → 切換章節,Ctrl+K 搜尋
查看:
查看: