AI 驅動文件

您想了解什麼？

HTTP API

HTTP API 讓 MES、SCADA 系統或您自己的軟體無需 PLC 即可直接通過網路與相機互動。通過 API 您可以：

觸發檢測並在同一次呼叫中獲取結果
讀取歷史結果，或在檢測完成時實時跟蹤，附帶其影象、熱圖和分割掩碼
列出程式並切換當前啟用的程式
在設定模式和執行模式之間切換
讀取和重置通過/失敗計數器

進入 Integration → HTTP API：

OV Spark Pro HTTP API 介面，顯示 Base URL、API 版本和認證資訊、Ready to trigger 檢查清單，以及 Endpoints 和 Examples 標籤頁

區域	功能
Connection	每次呼叫的起始 Base URL，例如 `http://10.250.0.100/api/integration/v1`、API 版本，以及呼叫是否需要使用者名稱和密碼
Download OpenAPI spec	每個端點的機器可讀描述，包含其引數和響應。可提供給開發人員，或載入到 Postman 或任何 OpenAPI 工具中
Ready to trigger?	一個實時檢查清單，列出 `POST /trigger` 工作所必須滿足的條件
Endpoints 和 Examples	按功能分組的所有端點，以及可直接複製使用的示例呼叫

第一次觸發前

Ready to trigger? 面板會檢查三項內容。在三項全部通過之前，POST /trigger 會被拒絕，錯誤資訊會指明失敗的那一項。

執行模式。 從頂部欄將相機切出設定模式，或呼叫 POST /mode/run。
活動程式。 必須有一個處於活動狀態的程式。可從 All Recipes 啟用一個程式，或呼叫 POST /recipes/{id}/activate。
接受 HTTP 觸發。 在活動程式中，開啟 Step 2: Triggering，選擇 External，並在 Enabled sources 下勾選 HTTP。

External 觸發下的 Enabled sources：GPIO、PLC / Fieldbus，以及 POST /trigger 對應的 HTTP

HTTP 只是多種觸發源之一

您可以勾選多個觸發源。一個程式可以同時接受來自產線上的硬體觸發和來自您軟體的 HTTP 觸發。未勾選的觸發源會被忽略，即使有訊號傳送給它。

觸發檢測

curl -X POST http://10.250.0.100/api/integration/v1/trigger \
  -H "Content-Type: application/json" \
  -d '{"wait_ms": 5000}'

該呼叫最多等待 wait_ms 毫秒（預設 5000，最大 30000）以等待檢測完成：

響應	含義	應對措施
200	已完成的結果	讀取 `judgment`：`pass`、`fail` 或 `not_inspected`
202	已接受，但未在 `wait_ms` 內完成	使用返回的 `trigger_id` 輪詢 `GET /results?trigger_id=`
409	相機未就緒	修復 `code` 指明的問題：執行模式、活動程式或 HTTP 觸發源
503	臨時情況，例如檢測仍在執行	重試

每次只傳送一個觸發

相機一次只處理一個觸發。在前一個觸發仍在執行時傳送的新觸發會被 503 拒絕，除非程式的 Image trigger buffer 允許其等待。請在收到前一個響應後再傳送下一個觸發。

將 not_inspected 視為拒絕

not_inspected 意味著所有檢測工具都被跳過，通常是因為對齊未能找到部件。由於什麼都沒有檢查，請將其作為拒絕處理，絕不能作為通過。

讀取結果

呼叫	返回
`GET /results/latest`	最新的結果
`GET /results`	結果列表，最新的在前，可按程式或觸發過濾
`GET /results/{id}`	單個結果，包含每個工具的判定
`GET /results/{id}/image`	被檢測的影象，以 JPEG 格式返回
`GET /results/{id}/tools/{tool_id}/heatmap`	某個區域的熱圖，以 PNG 格式返回
`GET /results/{id}/tools/{tool_id}/mask`	某個區域的分割掩碼，以 PNG 格式返回
`GET /results/stream`	檢測完成時的實時結果流，涵蓋所有觸發源

GET /results/stream 使用 Server-Sent Events：保持一個連線開啟，每個完成的檢測都會在發生時到達，無論它是通過 HTTP、PLC 還是感測器觸發的。這通常比輪詢更簡單。

每個工具報告 ok、ng、indeterminate 或 not_applicable，整個結果報告 pass、fail 或 not_inspected。

其他呼叫

分組	呼叫
Device	`GET /health`、`GET /device`、`GET /status`、`GET /whoami`、`GET /openapi.yaml`
Recipes	`GET /recipes`、`GET /recipes/active`、`POST /recipes/{id}/activate`
Statistics	`GET /statistics`、`POST /statistics/reset`、`GET /statistics/stream`
Control	`POST /mode/run`、`POST /mode/setup`
Fieldbus	`GET /fieldbus`、`GET /fieldbus/descriptor`（當前協議對應的 EDS 或 GSDML 檔案）

程式通過其編號來標識，與 PLC 用來選擇程式的 PLC recipe ID 相同，在 Step 5: Outputs 中設定。

等待模式切換完成

在 POST /mode/run 之後，持續輪詢 GET /status 直到 mode 為 run 且 mode_changing 為 false，再傳送觸發。模式切換需要片刻時間載入程式。

登入與安全

當相機還沒有 Admin 使用者時，API 無需憑據。一旦存在 Admin，除 /health、/whoami 和 /openapi.yaml 外的每次呼叫都需要相機賬戶的使用者名稱和密碼，以 HTTP Basic 認證方式傳送：

curl -u line3-mes:PASSWORD http://10.250.0.100/api/integration/v1/results/latest

為每個連線的系統分配獨立賬戶

在 Users and Permissions 中為每個系統建立一個賬戶，這樣 Audit Logs 會顯示哪個系統做了什麼。為其賦予能完成工作的最低角色；使用該賬戶憑據呼叫 GET /whoami 會列出它被允許呼叫的所有內容。請在 System Settings 中啟用 HTTPS，使密碼不以明文形式在網路上傳輸。

API 僅在 /api/integration/v1 範圍內擴充套件：可以增加新的端點和欄位，但現有的端點和欄位永遠不會改變含義或消失。今天針對它編寫的程式碼在韌體更新後仍能繼續工作。

後續步驟

Step 2: Triggering，啟用 HTTP 觸發源
Users and Permissions，為每個系統建立賬戶
Industrial Ethernet，如果同時涉及 PLC
Remote Storage，將影象和結果傳送到檔案伺服器

您想了解什麼？

第一次觸發前​

觸發檢測​

讀取結果​

其他呼叫​

登入與安全​

後續步驟​