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，将图像和结果发送到文件服务器

您想了解什么？

第一次触发前​

触发检测​

读取结果​

其他调用​

登录与安全​

后续步骤​