警报 API 指南#
警报规则定义了满足条件时生成警报的情况。每个分析模块（FOV、绊线、ROI）的警报规则类型各不相同。有关详细信息，请参阅特定分析模块的 API 指南。
警报 API 版本 v2#
警报 API 有一个新的主要版本 v2，它与早期版本不向后兼容。此版本仍支持 JPS 1.0 版本随附的先前版本。但是，强烈建议采用/迁移到 v2 版本。v2 版本在路径 /api/v2 下提供。早期版本仍可在 /api 下使用。
在本节中，我们将介绍如何检索警报。
检索传感器在时间范围内的所有警报#
检索给定传感器和给定时间范围的警报。
HTTP GET
/api/v2/alerts?sensorId=Amcrest_1&fromTimestamp=2021-09-16T06:06:00.000Z&toTimestamp=2021-09-16T06:07:00.000Z
强制性查询参数#
sensorId
描述：需要返回警报的传感器。
类型：字符串。
示例：sensorId=Amcrest_1
fromTimestamp
描述：需要返回警报的时间戳的下限
类型：UTC / GMT 时间戳字符串
示例：2020-10-30T20:00:00.000Z
toTimestamp
描述：需要返回警报的时间戳的上限。如果未指定，则默认为服务器上的 UTC.NOW
类型：UTC / GMT 时间戳字符串
示例：2020-10-30T20:05:00.000Z
limit
描述：要返回的最大警报数
类型：整数
示例: 100
它遵循基于时间的简单分页。获取 2021-09-16T06:06:00.000Z（fromTimestamp）和 2021-09-16T06:07:00.000Z（endTimestamp）之间发生的最新 10 个（limit）警报。标准是 endTimestamp > fromTimestamp
示例 1：给定时间范围内的所有警报#
获取 2021-09-16T06:06:00.000Z（fromTimestamp）和 2021-09-16T06:07:00.000Z（toTimestamp）之间的所有警报。
/api/v2/alerts?sensorId=Amcrest_3&fromTimestamp=2021-09-16T06:06:00.000Z&toTimestamp=2021-09-16T06:07:00.000Z
响应：#
{ "alerts": [ { "count": 10, "description": "10 people entered fov", "duration": 0.734, "endTimestamp": "2021-09-16T06:07:00.534Z", "id": "unique-alert-id", "rule_type": "increment", "sensorId": "Amcrest_3", "startTimestamp": "2021-09-16T06:06:59.800Z", "type": "fov", "direction": "entry", "attributes": [ { "name": "objects", "value": [ { "id": "1186", "type": "Person" } ] } ] }, { "count": 1, "description": "more than 1 ppl continuously present in FOV for longer than 10 seconds", "duration": 10.734, "endTimestamp": "2021-09-16T06:07:00.534Z", "id": "unique-alert-id", "rule_type": "occupancy", "sensorId": "Amcrest_3", "startTimestamp": "2021-09-16T06:06:59.800Z", "type": "fov", "attributes": [ { "name": "objects", "value": [ { "id": "1186", "type": "Person" } ] } ] }, { "count": 5, "description": "FOV occupancy count greater than 5", "duration": 10.734, "endTimestamp": "2021-09-16T06:07:00.534Z", "id": "unique-alert-id", "rule_type": "occupancy_threshold_switch", "sensorId": "Amcrest_3", "startTimestamp": "2021-09-16T06:06:59.800Z", "type": "fov", "direction": "up", "attributes": [] } ] }
响应正文属性#
类型为 increment 和 occupancy 的警报在其属性部分还包含导致这些警报的对象列表。每个对象都由其 ID 和类型表示。例如，id=100，type=Person。
"attributes": [ { "objects": [ { "id": 100, "type": "Person" }, { "id": 200, "type": "Person" } ] } ]
示例 2：获取给定时间戳之前发生的最新 10 个警报#
获取 2021-09-16T06:07:00.000Z（toTimestamp）之前发生的最新 10 个警报（limit=10）。
/api/v2/alerts?sensorId=Amcrest_3&toTimestamp=2021-09-16T06:07:00.000Z&limit=10
示例 3：获取时间戳之后发生的最新 10 个警报#
获取 2021-09-16T06:07:00.000Z（fromTimestamp）之后发生的最新 10 个警报（limit=10）。
/api/v2/alerts?sensorId=Amcrest_3&fromTimestamp=2021-09-16T06:07:00.000Z&limit=10
错误响应#
响应正文：请参阅页面末尾的错误响应正文定义。
HTTP 状态代码
422：未找到请求的 sensorId 和时间范围的行为 500：内部服务器错误
错误响应正文#
所有 API 的错误响应都是具有以下属性的 JSON 对象。
{
"detail": "#Detailed error string",
"status": "#http-status-code",
"title": "Unprocessable Entity",
"type": "about:blank"
}
检索传感器在时间范围内的历史警报计数#
HTTP GET
/api/v2/alerts/count?sensorId=Amcrest_1&fromTimestamp=2021-09-16T06:06:00.000Z&toTimestamp=2021-09-16T06:07:00.000Z
强制性查询参数#
sensorId
描述：需要返回警报的传感器。
类型：字符串。
示例：sensorId=Amcrest_1
fromTimestamp
描述：需要返回警报的时间戳的下限
类型：UTC / GMT 时间戳字符串
示例：2020-10-30T20:00:00.000Z
toTimestamp
描述：需要返回警报的时间戳的上限。如果未指定，则默认为服务器上的 UTC.NOW
类型：UTC / GMT 时间戳字符串
示例：2020-10-30T20:05:00.000Z
limit
描述：要返回的最大警报数
类型：整数
示例: 100
它遵循基于时间的简单分页。获取 2021-09-16T06:06:00.000Z（fromTimestamp）和 2021-09-16T06:07:00.000Z（endTimestamp）之间发生的最新 10 个（limit）警报。标准是 endTimestamp > fromTimestamp
示例#
获取 2021-09-16T06:06:00.000Z（fromTimestamp）和 2021-09-16T06:07:00.000Z（toTimestamp）之间的警报计数。
响应：#
/api/v2/alerts/count?sensorId=Amcrest_3&fromTimestamp=2021-09-16T06:06:00.000Z&toTimestamp=2021-09-16T06:07:00.000Z
{ "alerts": [ { "sensorId": "Amcrest_3", "type": "fov", "rule_type": "increment", "rule_id": "78956", "rule_name": "lobby entry/exits", "direction": "enter", "count": 11, "attributes": [] }, { "sensorId": "Amcrest_3", "type": "tripwire", "rule_type": "increment", "rule_id": "12345", "rule_name": "main door crossings", "count": 5, "direction": "enter", "attributes": [] }, { "sensorId": "Amcrest_3", "type": "tripwire", "rule_type": "increment", "rule_id": "12345", "rule_name": "ain door crossings", "count": 2, "direction": "exit", "attributes": [] } ] }
响应正文属性#
类型为 increment 和 occupancy 的警报在其属性部分还包含导致这些警报的对象列表。每个对象都由其 ID 和类型表示。例如，id=100，type=Person。
错误响应#
响应正文：请参阅页面末尾的错误响应正文定义。
HTTP 状态代码
422：未找到请求的 sensorId 和时间范围的行为 500：内部服务器错误
错误响应正文#
所有 API 的错误响应都是具有以下属性的 JSON 对象。
{
"detail": "#Detailed error string",
"status": "#http-status-code",
"title": "Unprocessable Entity",
"type": "about:blank"
}
通过 WebSocket 端点通知警报#
除了通过 REST API /alerts 查询历史警报的功能外，还有一个 websocket 端点可以获取警报发生时的实时通知。
警报 WebSocket 端点#
分析 Web API 通过 Ingress Controller 公开。
URL 前缀是 http://<INGRESS-HOST-IP>:<INGRESS-PORT>/ws-emdx/api/v2/alerts/ws。
将 INGRESS-HOST-IP 替换为 Jetson 设备 IP。将 INGRESS-PORT 替换为 30080 或 Ingress 配置中定义的最后一个值。
连接到 websocket 时，客户端可以指定其希望接收的警报的筛选条件。筛选条件可以分层方式指定，如下所示
按特定 sensorId 进行顶级筛选
针对特定 tripwireId 或 roiId 的二级筛选
针对特定类型的警报规则的三级筛选。
在所有级别，都可以为通配符匹配（即所有可能的值）指定值“*”
[ { "sensorId": "Amcrest_1", "tripwires": [ { "tripwireId": "TW1", "alertRuleTypes": [ "increment", "flowrate" ] }, { "tripwireId": "TW2", "alertRuleTypes": [ "flowrate" ] } ], "rois": [ { "roiId": "cc1", "alertRuleTypes": [ "increment" ] }, { "roiId": "cc2", "alertRuleTypes": [ "occupancy" ] } ], "fov": { "alertRuleTypes": [ "occupancy" ] } }, { "sensorId": "Amcrest_2", "tripwires": [ { "tripwireId": "TW4", "alertRuleTypes": [ "increment", "flowrate" ] } ], "rois": [], "fov": { "alertRuleTypes": [] } } ]
示例 1：请求所有警报#
对于每个传感器，通知所有 fov、绊线和 roi 警报。
[ { "sensorId": "*", "tripwires": [ { "tripwireId": "*", "alertRuleTypes": ["*"] } ], "rois": [ { "roiId": "*", "alertRuleTypes": ["*"] } ], "fov": { "alertRuleTypes": ["*"] } } ]
示例 2：请求特定警报#
对于 sesnor=Amcrest_1，推送类型为 increment 的所有绊线和 roi 警报。
[ { "sensorId": "Amcrest_1", "tripwires": [ { "tripwireId": "*", "alertRuleTypes": ["increment"] } ], "rois": [ { "roiId": "*", "alertRuleTypes": ["increment"] } ], "fov": { "alertRuleTypes": [] } } ]
WebSocket 响应：#
websocket 响应正文与调用 REST API /alerts 时收到的正文相同。
{ "alerts": [ { "count": 10, "description": "10 people entered fov", "duration": 0.734, "endTimestamp": "2021-09-16T06:07:00.534Z", "id": "unique-alert-id", "rule_type": "increment", "sensorId": "Amcrest_3", "startTimestamp": "2021-09-16T06:06:59.800Z", "type": "fov", "direction": "entry", "attributes": [ { "name": "objects", "value": [ { "id": "1186", "type": "Person" } ] } ] }, { "count": 10, "description": "more than 5 ppl continuously present in FOV for longer than 10 seconds", "duration": 10.734, "endTimestamp": "2021-09-16T06:07:00.534Z", "id": "unique-alert-id", "rule_type": "occupancy", "sensorId": "Amcrest_3", "startTimestamp": "2021-09-16T06:06:59.800Z", "type": "fov", "attributes": [ { "name": "objects", "value": [ { "id": "1186", "type": "Person" } ] } ] }, { "count": 5, "description": "FOV occupancy count greater than 5", "duration": 10.734, "endTimestamp": "2021-09-16T06:07:00.534Z", "id": "unique-alert-id", "rule_type": "occupancy_threshold_switch", "sensorId": "Amcrest_3", "startTimestamp": "2021-09-16T06:06:59.800Z", "type": "fov", "direction": "up", "attributes": [] } ] }
响应正文属性#
类型为 increment 和 occupancy 的警报在其属性部分还包含导致这些警报的对象列表。每个对象都由其 ID 和类型表示。例如，id=100，type=Person。