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

您想了解什么？

第一次触发之前​

触发检测​

读取结果​

其他调用​

登录与安全​

后续步骤​