AI 驅動文件

您想了解什麼？

HTTP API

HTTP API 讓 MES、SCADA 系統或您自己的軟體可以通過網路直接與相機互動，無論是否使用 PLC。通過該 API，您可以：

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

進入 Integration → HTTP API：

OV Spark 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 會被拒絕，並且錯誤資訊會指出失敗的那一項。

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

External triggering 下的 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，將影象和結果傳送到檔案伺服器

您想了解什麼？

第一次觸發之前​

觸發檢測​

讀取結果​

其他呼叫​

登入與安全​

後續步驟​