视场 (FOV) API 指南

可通过 Web API 访问 FOV 计数、警报和警报规则。

FOV API 端点

分析 Web API 通过 Ingress 控制器公开。

URL 前缀为 http://<INGRESS-HOST-IP>:<INGRESS-PORT>/emdx/。

将 INGRESS-HOST-IP 替换为 Jetson 设备 IP。将 INGRESS-PORT 替换为 30080 或 Ingress 配置中定义的最后一个值。

FOV API 版本 v2

FOV API 有一个新的主要版本 v2，它与早期版本不向后兼容。此版本仍然支持 JPS 1.0 版本附带的先前版本。但是，强烈建议采用/迁移到 v2 版本。v2 版本在路径 /api/v2 下提供。早期版本仍然在 /api 下运行。

FOV 计数

检索 FOV 计数直方图

给定时间范围内和指定的固定间隔内，摄像机视场中人数的计数直方图。

HTTP GET

/api/v2/metrics/occupancy/fov/histogram?sensorId=Amcrest_1&fromTimestamp=2020-10-30T20:00:00.000Z&toTimestamp=2020-10-31T01:00:00.000Z

强制查询参数

sensorId

description: 需要返回 FOV 指标的传感器。

type: 字符串。

example: sensorId=Amcrest_1

fromTimestamp

description: 需要返回 fov 计数的起始时间戳下限。

type: UTC / GMT 时间戳字符串

example: 2020-10-30T20:00:00.000Z

toTimestamp

description: 需要返回 fov 计数和警报的时间戳上限。如果未指定，则默认为服务器上的 UTC.NOW。

type: UTC / GMT 时间戳字符串

example: 2020-10-30T20:05:00.000Z

可选查询参数

bucketSizeInSec

description : 请求的时间范围（fromTimestamp - toTimestamp）被分段为 interval bucketSizeInSec 秒的直方图。最小值 1 秒。最大值 864000 秒（1 天）

type: 整数

objectType

description: 可选的 objectType 参数，用于按对象类型（例如人、车辆等）细分直方图计数

type: 字符串

按对象类型细分计数的可能方式如下

1) 除了所有对象类型的累计计数外，还返回仅针对特定对象类型的计数。objectType=People,Vehicle

2) 除了所有对象类型的累计计数外，还返回所有对象类型的计数。objectType=*

3. 当未指定 objectType 时，它仅返回所有对象类型的累计计数。

响应

{

   "bucketSizeInSec": "1",
   "histogram": [
      {
      "end": "2020-01-26T19:16:30.000Z",
      "start": "2020-01-26T19:16:29.000Z",
      "objects": [
            {
               "type": "Person",
               "avgCount": 1,
               "minCount": 0,
               "maxCount": 2
            },
            {
               "type": "Vehicle",
               "avgCount": 1,
               "minCount": 1,
               "maxCount": 4
            }
         ]
      },
      {
      "end": "2020-01-26T19:16:29.000Z",
      "start": "2020-01-26T19:16:28.000Z",
      "objects": [
            {
               "type": "Person",
               "avgCount": 1,
               "minCount": 0,
               "maxCount": 2
            },
            {
               "type": "Vehicle",
               "avgCount": 1,
               "minCount": 1,
               "maxCount": 4
            }
         ]
      }
   ]
}

响应正文属性

histogram

description: 每种对象类型（例如人、车辆等）的计数直方图

type: 对象数组

错误响应

响应正文：请参阅页面末尾的错误响应正文定义。

HTTP 状态代码

422：未找到请求的传感器和时间范围的 FOV 指标 500：内部服务器错误

示例

查询 5 分钟时间范围的 FOV 计数，并将结果聚合到 10 秒的非重叠固定间隔中。

HTTP GET

/api/v2/metrics/occupancy/fov/histogram?sensorId=Amcrest_1&fromTimestamp=2020-10-30T20:00:00.000Z&toTimestamp=2020-10-30T20:05:00.000Z&fixedInterval=10

检索 FOV 总计数

给定时间范围内摄像机视场中人数的总计数。

HTTP GET

/api/v2/metrics/occupancy/fov/count?sensorId=Amcrest_1&fromTimestamp=2020-10-30T20:00:00.000Z&toTimestamp=2020-10-31T01:00:00.000Z

强制查询参数

sensorId

description: 需要返回 FOV 指标的传感器。

type: 字符串。

example: sensorId=Amcrest_1

fromTimestamp

description: 需要返回 fov 计数的起始时间戳下限。

type: UTC / GMT 时间戳字符串

example: 2020-10-30T20:00:00.000Z

toTimestamp

description: 需要返回 fov 计数和警报的时间戳上限。如果未指定，则默认为服务器上的 UTC.NOW。

type: UTC / GMT 时间戳字符串

example: 2020-10-30T20:05:00.000Z

可选查询参数

objectType

description: 可选的 objectType 参数，用于按对象类型（例如人、车辆等）细分计数

type: 字符串

按对象类型细分计数的可能方式如下

1) 除了所有对象类型的累计计数外，还返回仅针对特定对象类型的计数。objectType=People,Vehicle

2) 除了所有对象类型的累计计数外，还返回所有对象类型的计数。objectType=*

3. 当未指定 objectType 时，它仅返回所有对象类型的累计计数。

响应

{
    "fovOccupancy": [
      {
        "sumCount": 10
        "averageCount": 2
        "type": "People"
      },
      {
        "sumCount": 20
        "averageCount": 3
        "type": "Vehicle"
      }
   ]
}

响应正文属性

fovOccupancy：计数项的数组。其中每个项都包含特定对象类型（“人”、“车辆”）的计数

以下是每个项的属性

sumCount

description: 类型对象的总唯一计数（例如人、车辆等）

type: 整数

averageCount

description: 类型对象的平均计数（例如人、车辆等）

type: 整数

type

description: 对象类型（例如人、车辆等）

type: 字符串。

错误响应

响应正文：请参阅页面末尾的错误响应正文定义。

HTTP 状态代码

422：未找到请求的传感器和时间范围的 FOV 指标 500：内部服务器错误

示例

查询 5 分钟时间范围的 FOV 总计数。

/api/v2/metrics/occupancy/fov/count?sensorId=Amcrest_1&fromTimestamp=2020-10-30T20:00:00.000Z&toTimestamp=2020-10-30T20:05:00.000Z

FOV 警报

检索 FOV 警报

可以使用 API 检索 FOV 警报，该 API 具有传感器、时间范围的筛选功能，并可选支持基于时间的 pagination。

HTTP GET

/api/v2/alerts/fov?sensorId=Amcrest_1&fromTimestamp=2021-09-16T06:06:00.000Z&toTimestamp=2021-09-16T06:07:00.000Z

强制查询参数

sensorId

description: 需要返回 FOV 指标的传感器。

type: 字符串。

example: sensorId=Amcrest_1

fromTimestamp

description: 需要返回 fov 警报的起始时间戳下限

type: UTC / GMT 时间戳字符串

example: 2020-10-30T20:00:00.000Z

toTimestamp

description: 需要返回 fov 警报的时间戳上限。如果未指定，则默认为服务器上的 UTC.NOW

type: UTC / GMT 时间戳字符串

example: 2020-10-30T20:05:00.000Z

limit

description: 要返回的最大警报数

type: 整数

example: 100

它遵循基于时间的简单分页。获取在 2021-09-16T06:06:00.000Z (fromTimestamp) 和 2021-09-16T06:07:00.000Z (endTimestamp) 之间发生的最新 10 个（限制）警报。标准是 endTimestamp > fromTimestamp

示例

获取 2021-09-16T06:06:00.000Z (fromTimestamp) 和 2021-09-16T06:07:00.000Z (toTimestamp) 之间的所有警报。

HTTP GET

/api/v2/alerts/fov?sensorId=Amcrest_1&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",
               "ruleType": "increment",
               "sensorId": "Amcrest_3",
               "startTimestamp": "2021-09-16T06:06:59.800Z",
               "type": "fov",
               "direction": "entry",
               "attributes": [
                  {
                     "name": "objects",
                     "value": [
                        {
                              "id": "1186",
                              "type": "People"
                        }
                     ]
                  }
               ]
         },
         {
               "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",
               "ruleType": "occupancy",
               "sensorId": "Amcrest_3",
               "startTimestamp": "2021-09-16T06:06:59.800Z",
               "type": "fov",
               "attributes": [
                  {
                     "name": "objects",
                     "value": [
                        {
                              "id": "1186",
                              "type": "People"
                        }
                     ]
                  }
               ]
         },
         {
               "count": 5,
               "description": "FOV occupancy count greater than 5",
               "duration": 10.734,
               "endTimestamp": "2021-09-16T06:07:00.534Z",
               "id": "unique-alert-id",
               "ruleType": "occupancy_threshold_switch",
               "sensorId": "Amcrest_3",
               "startTimestamp": "2021-09-16T06:06:59.800Z",
               "type": "fov",
               "direction": "up",
               "attributes": []
         }
      ]
}

响应正文属性

增量和占用类型的警报在其属性部分也包含导致这些警报的对象列表。每个对象都由其 ID 和类型表示。例如，id=100，type=People。

错误响应

响应正文：请参阅页面末尾的错误响应正文定义。

HTTP 状态代码

422：未找到请求的传感器和时间范围的 FOV 警报 500：内部服务器错误

获取 2021-09-16T06:06:00.000Z (fromTimestamp) 和 2021-09-16T06:07:00.000Z (toTimestamp) 之间最新的 10 个（限制）警报。

HTTP GET

/api/v2/alerts/fov?sensorId=Amcrest_1&fromTimestamp=2021-09-16T06:06:00.000Z&toTimestamp=2021-09-16T06:07:00.000Z&limit=10

配置 FOV 警报规则

支持三种类型的警报规则，即增量、占用、占用阈值切换。

占用警报类型

当 FOV 中存在的人数countThreshold 持续时间超过 timeInterval 秒时发出警报

示例：当 FOV 中持续存在 100 人或更多人超过 10 秒时，发出警报的警报规则。

HTTP POST

/api/v2/config/rule/alerts/fov

{
   "sensorId": "Amcrest_1",
   "rules": [
      {
         "ruleId": "d8f0484f-b464-4a92-a5a9-649a14160b53",
         "id": "Amcrest_1",
         "type": "fov",
         "ruleType": "occupancy",
         "name": "Overcrowding scenario rule",
         "timeInterval": 10,
         "countThreshold": 100
      }
   ]
}

强制正文参数

sensorId

description: 要为其创建警报规则的传感器。

type: 字符串

example: Amcrest_1

rules

description: 警报规则数组。

type: 数组

example:

{
   "ruleId": "cd2218f6-e4d2-4ad4-9b15-3396e4336064",
   "id": "Amcrest_1",
   "name": "Over crowding scenario rule",
   "type": "fov",
   "ruleType": "occupancy",
   "timeInterval": 10,
   "countThreshold": 100
}

每个警报规则由以下参数组成

强制规则参数

ruleId

description: 此警报规则的唯一 ID。这在所有警报规则中应该是唯一的

type: 字符串

example: UUID 例如 cd2218f6-e4d2-4ad4-9b15-3396e4336064

id

description: 指的是应用警报规则的 FOV。由于 FOV 不需要显式配置。对于 FOV 警报规则，这可以包含传感器本身的名称。

type: 字符串

example: Amcrest_1

type

description: 此警报相关的分析模块的类型。固定值“fov”

type: 字符串

example: fov

ruleType

description: 警报规则的类型。固定值“occupancy”

type: 字符串

value: occupancy

timeInterval

description: 时间窗口。以秒为单位指定。

type: 浮点数

example: 10

countThreshold

description: 计数数量的阈值。

type: 整数

example: 100

可选规则参数

name

description: 警报规则的用户友好名称。用于在客户端侧显示

type: 字符串

example: “过度拥挤场景规则”

注意

您需要在 HTTP POST 请求的 HTTP 标头中设置 User-Type=Admin。

错误响应

响应正文：请参阅页面末尾的错误响应正文定义。

HTTP 状态代码

403：授权错误。缺少 User-Type 标头。必须存在且值为 Admin 500：内部服务器错误

占用阈值切换警报类型

基于视野中检测到的对象数量高于或低于 countThreshold 的变化发出警报。最简单的用例是当 FOV 状态从空闲（占用 == 0）变为占用（占用 >= 1）时。反之，当占用从占用（占用 >= 1）变为空闲（占用 == 0）时。

HTTP POST

/api/v2/config/rule/alerts/fov

{
   "sensorId": "Amcrest_1",
   "rules": [
      {
         "ruleId": "ae511b25-a57d-483f-b4c5-c30e039cc375",
         "id": "Amcrest_1",
         "type": "fov",
         "ruleType": "occupancy_threshold_switch",
         "timeInterval": 1,
         "countThreshold": 1,
         "parameters": [
            {
               "name":"time_interval_up",
               "value":1,
            },
            {
               "name":"time_interval_down",
               "value":2,
            }
         ]
      }
   ]
}

强制正文参数

sensorId

description: 要为其创建 FOV 警报规则的传感器。

type: 字符串

example: Amcrest_1

rules

description: 警报规则数组。

type: 数组。

example:

{
   "ruleId": "ae511b25-a57d-483f-b4c5-c30e039cc375",
   "id": "Amcrest_1",
   "type": "fov",
   "ruleType": "occupancy_threshold_switch",
   "timeInterval": 1,
   "countThreshold": 1,
   "parameters": [
      {
         "name":"time_interval_up",
         "value":1,
      },
      {
         "name":"time_interval_down",
         "value":2,
      }
   ]
}

警报规则

每个警报规则由以下参数组成

强制规则参数

ruleId

description: 此警报规则的唯一 ID。这在所有警报规则中应该是唯一的

type: 字符串

example: UUID 例如 ae511b25-a57d-483f-b4c5-c30e039cc375

id

description: 指的是应用警报规则的 FOV。由于 FOV 不需要显式配置。对于 FOV 警报规则，这可以包含传感器本身的名称。

type: 字符串

example: Amcrest_1

type

description: 分析模块的类型。固定值“fov”

type: 字符串

value: fov

ruleType

description: 警报规则的类型。固定值“occupancy_threshold_switch”

type: 字符串

value: occupancy_threshold_switch

timeInterval

description: 时间窗口。以秒为单位指定。指示计数需要高于或低于阈值多长时间才能发出警报。它用于处理占用计数中的抖动，并在发生此类抖动时平滑警报的发布。

type: 浮点数

example: 1

countThreshold

description:

用于确定状态的计数阈值

1. 零 countThreshold 表示当占用从零变为大于零时发出警报。反之，当占用从大于零的正数降至零时，则发出警报。

2. 正非零 countThreshold (N) 表示我们希望在占用超过 N 时发出 UP 警报 (direction=up)，而在占用降至 N 或以下时发出 DOWN (direction=down) 警报。

type: 整数

example: 1

可选规则参数

parameters

description: 规则特定参数，指定为名称、值对的数组。

type: 名称、值对的数组

example: 以下是 occupancy_threshold_switch 警报类型支持的有效参数

parameters: [
  {
     "name":"time_interval_up",
     "value":1,
  },
  {
     "name":"time_interval_down",
     "value":2,
  }
]

time_interval_up：从空闲状态到占用状态变化的时间间隔

time_interval_down：从占用状态到空闲状态变化的时间间隔

name

description: 警报规则的用户友好名称。用于在客户端侧显示

type: 字符串

example: “过度拥挤场景规则”

注意

您需要在 HTTP POST 请求的 HTTP 标头中设置 User-Type=Admin。

错误响应

响应正文：请参阅页面末尾的错误响应正文定义。

HTTP 状态代码

403：授权错误。缺少 User-Type 标头。必须存在且值为 Admin 500：内部服务器错误

增量警报规则类型

基于在 timeInterval 秒内视野中进入/退出的对象countThreshold 发出警报。

创建新的警报规则

HTTP POST

/api/v2/config/rule/alerts/fov

{
   "sensorId": "Amcrest_1",
   "rules": [
      {
         "ruleId": "fb298ea4-30aa-4085-b860-42e37c5bf8d1",
         "id": "Amcrest_1",
         "type": "fov",
         "ruleType": "increment",
         "timeInterval": 1,
         "countThreshold": 1,
         "direction": "entry"
      },
      {
         "ruleId": "9c5632af-ba68-46bc-a997-858bdadc6856",
         "id": "Amcrest_1",
         "type": "fov",
         "ruleType": "increment",
         "timeInterval": 5,
         "countThreshold": 10,
         "direction": "exit"
      }
   ]
}

强制正文参数

sensorId

description: 要为其创建警报规则的传感器。

type: 字符串。

example: Amcrest_1

rules

description: 警报规则数组。

type: 数组。

example:

{
   "rules": [
      {
         "ruleId": "fb298ea4-30aa-4085-b860-42e37c5bf8d1",
         "id": "Amcrest_1",
         "type": "fov",
         "ruleType": "increment",
         "timeInterval": 1,
         "countThreshold": 1,
         "direction": "entry"
      },
      {
         "ruleId": "9c5632af-ba68-46bc-a997-858bdadc6856",
         "id": "Amcrest_1",
         "type": "fov",
         "ruleType": "increment",
         "timeInterval": 5,
         "countThreshold": 10,
         "direction": "exit"
      }
   ]
}

每个警报规则由以下参数组成

强制规则参数

ruleId

description: 此警报规则的唯一 ID。这在所有警报规则中应该是唯一的

type: 字符串

example: UUID 例如 fb298ea4-30aa-4085-b860-42e37c5bf8d1

id

description: 指的是应用警报规则的 FOV。由于 FOV 不需要显式配置。对于 FOV 警报规则，这可以包含传感器本身的名称。

type: 字符串

example: Amcrest_1

type

description: 分析模块的类型。固定值“fov”

type: 字符串

value: fov

ruleType

description: 警报规则的类型。固定值“increment”

type: 字符串

value: increment

timeInterval

description: 时间窗口。以秒为单位指定。

type: 浮点数

example: 5

countThreshold

description: 考虑用于警报规则的人数阈值。

type: 整数

example: 10

direction

description: 警报规则的方向性。规则是指离开 FOV (exit) 或进入 FOV (entry) 的对象数量吗

type: 字符串

enum: entry/exit 之一

example: exit

可选规则参数

name

description: 警报规则的用户友好名称。用于在客户端侧显示

type: 字符串

example: “过度拥挤场景规则”

注意

您需要在 HTTP POST 请求的 HTTP 标头中设置 User-Type=Admin。

错误响应

响应正文：请参阅页面末尾的错误响应正文定义。

HTTP 状态代码

403：授权错误。缺少 User-Type 标头。必须存在且值为 Admin 500：内部服务器错误

删除 FOV 警报规则

HTTP DELETE

/api/v2/config/rule/alerts/fov?sensorId=Amcrest_1&ruleId=fb298ea4-30aa-4085-b860-42e37c5bf8d1

强制查询参数

sensorId

description: 要删除 FOV 警报的传感器。

type: 字符串

example: Amcrest_1

ruleId

description: 要删除的警报规则的唯一 ruleId

type: 字符串

example: fb298ea4-30aa-4085-b860-42e37c5bf8d1

注意：（将需要在 HTTP DEL 请求的 HTTP 标头中设置 User-Type: Admin。）

错误响应

响应正文：请参阅页面末尾的错误响应正文定义。

HTTP 状态代码

403：授权错误。缺少 User-Type 标头。必须存在且值为 Admin 422：指定的传感器和规则 ID 不存在警报规则 500：内部服务器错误

检索 FOV 警报规则

HTTP GET

/api/v2/config/rule/alerts/fov?sensorId=Amcrest_1

sensorId

description: 需要返回 fov 警报规则的传感器。

type: 字符串

example: sensorId=Amcrest_1

错误响应

响应正文：请参阅页面末尾的错误响应正文定义。

HTTP 状态代码

422：指定的传感器不存在警报规则 500：内部服务器错误

检索所有历史 FOV 警报规则

/api/v2/config/rule/alerts/fov/history?sensorId=Amcrest_1

强制查询参数

sensorId

description: 需要返回历史 fov 警报规则的传感器。

type: 字符串

example: sensorId=Amcrest_1

错误响应

响应正文：请参阅页面末尾的错误响应正文定义

HTTP 状态代码

422：指定的传感器不存在警报规则 500：内部服务器错误

错误响应正文:

所有 API 的错误响应都是具有以下属性的 JSON 对象。

{
   "error": "#Detailed error string",
}