绊线 API 指南#

概述#

绊线是 Metropolis Analytics 微服务中的一个功能模块，用于检测物体 crossing（穿越）定义的绊线，并提供与之相关的时间序列指标和警报。

绊线 API 端点#

分析 Web API 通过 Ingress Controller 公开。

URL 前缀为 http://<INGRESS-HOST-IP>:<INGRESS-PORT>/emdx/。将 INGRESS-HOST-IP 替换为 Jetson 设备 IP。将 INGRESS-PORT 替换为 30080 或 Ingress 配置中定义的最后一个值。

绊线 API 版本 v2#

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

创建绊线配置#

HTTP POST

/api/v2/config/tripwire?sensorId=Amcrest_3

{
  "deleteIfPresent": true,
  "tripwires": [
    {
        "direction": {
          "entry": {
            "name": "Inside the room"
          },
          "exit": {
            "name": "Outside of the room"
          },
          "p1": {
            "x": 753,
            "y": 744
          },
          "p2": {
            "x": 448,
            "y": 856
          }
        },
        "id": "door1",
        "name": "Main door",
        "wire": [
          {
            "x": 321,
            "y": 664
          },
          {
            "x": 544,
            "y": 648
          },
          {
            "x": 656,
            "y": 953
          },
          {
            "x": 323,
            "y": 1067
          }
        ]
      }
  ],
  "sensorId": "Amcrest_3"
}

必需的查询参数#

sensorId

description: 需要插入绊线配置的传感器。

type: string

example: sensorId=Amcrest_3

direction.p1

description: 方向箭尾的 (x,y) 坐标。

type: Dict{x: int, y: int}

example: direction.p1={“x”: 323, “y”: 1067}

direction.p2

description: 方向箭头的 (x,y) 坐标。

type: Dict{x: int, y: int}

example: direction.p1={“x”: 448, “y”: 858}

可选的查询参数#

direction.entry.name

description: 用户友好的名称，用于描述朝向绊线入口侧的 crossing（穿越）方向

type: string

example: 房间内部

direction.exit.name

description: 用户友好的名称，用于描述朝向绊线出口侧的 crossing（穿越）方向

type: string

example: 房间外部

deleteIfPresent

description: 如果为 true，则将删除此绊线的任何现有绊线时间序列数据。

type: boolean

如果未指定或为 false，则保留绊线时间序列数据。

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

错误响应#

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

HTTP 状态代码

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

检索绊线直方图计数#

在给定的时间范围内和指定的固定间隔内，穿越绊线的人员计数的直方图。

HTTP GET

/api/v2/metrics/tripwire/histogram?sensorId=Amcrest_3&tripwireId=door1&fromTimestamp=2020-10-30T20:00:00.000Z&toTimestamp=2020-10-31T01:00:00.000Z

必需的查询参数#

sensorId

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

type: string

example: sensorId=Amcrest_3

tripwireId

description: 需要返回绊线指标的绊线。

type: string

example: door1

fromTimestamp

description: 需要返回绊线计数的 timestamp（时间戳）的下限

type: UTC / GMT timestamp 字符串

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

toTimestamp

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

type: UTC / GMT timestamp 字符串

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

可选的查询参数#

bucketSizeInSec

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

type: int

objectType

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

type: string

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

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

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

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

示例#

HTTP GET

/api/v2/metrics/tripwire/histogram?sensorId=Amcrest_3&tripwireId=door1&fromTimestamp=2020-10-30T20:00:00.000Z&toTimestamp=2020-10-30T20:05:00.000Z&bucketSizeInSec=1

5 分钟的时间范围被碎片化为 1 秒固定间隔的直方图。

响应#

{
    "bucketSizeInSec": "1",
    "tripwires": [
      {
        "id": "door_1",
        "histogram": [
          {
            "end": "2020-01-26T19:16:30.000Z",
            "start": "2020-01-26T19:16:29.000Z",
            "events": [
              {
                "type": "IN",
                "objects": [
                  {
                    "type": "Person",
                    "count": 1
                  },
                  {
                    "type": "Box",
                    "count": 4
                  }
                ]
              },
              {
                "type": "OUT",
                "objects": [
                  {
                    "type": "Person",
                    "count": 2
                  },
                  {
                    "type": "Box",
                    "count": 1
                  }
                ]
              }
            ]

          }
        ]
      }
    ]
}

响应正文属性#

tripwires[].histogram

description: 每个绊线和方向类型（IN/OUT）的所有对象类型（例如，人员、车辆等）的计数直方图

type: 对象数组

错误响应#

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

HTTP 状态代码

422：未找到请求的 sensorId 和时间范围的绊线指标。500：内部服务器错误

检索绊线总计数#

给定时间范围内穿越绊线的人员总计数

HTTP GET

/api/v2/metrics/tripwire/count?sensorId=Amcrest_3&tripwireId=door1&fromTimestamp=2020-10-30T20:00:00.000Z&toTimestamp=2020-10-31T01:00:00.000Z

必需的查询参数#

sensorId

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

type: string

example: sensorId=Amcrest_3

tripwireId

description: 需要返回绊线指标的绊线。

type: string

example: door1

fromTimestamp

description: 需要返回绊线计数的 timestamp（时间戳）的下限

type: UTC / GMT timestamp 字符串

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

toTimestamp

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

type: UTC / GMT timestamp 字符串

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

可选的查询参数#

objectType

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

type: string

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

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

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

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

示例#

HTTP GET

/api/v2/metrics/tripwire/count?sensorId=Amcrest_3&tripwireId=door1&fromTimestamp=2020-10-30T20:00:00.000Z&toTimestamp=2020-10-30T20:05:00.000Z

响应#

{

    "tripwireKpis": [
      {

        "id": "door1",
        "events": [
          {
            "type": "IN",
            "objects": [
              {
                "type": "People",
                "count": 2
              }
            ]
          },
          {
            "type": "OUT",
            "objects": [
              {
                "type": "People",
                "count": 1
              }
            ]
          }
        ]
      }
   ]

}

响应正文属性#

tripwireKpis[].id

description: 提供事件计数的绊线的 ID。

type: string

tripwireKpis[].events[].type

description: crossing（穿越）方向，例如 IN/OUT

type: string

tripwireKpis[].events[].objects[]

description: 特定对象类型的计数

type: 对象

tripwireKpis[].events[].objects[].type

description: 对象类型

type: string

tripwireKpis[].events[].objects[].count

description: 特定对象类型的计数

type: 整数

错误响应#

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

HTTP 状态代码

422：未找到请求的 sensorId 和时间范围的绊线指标。500：内部服务器错误

创建绊线警报规则#

支持两种类型的警报规则，即Increment（增量）和Flow Rate（流速）。

流速警报类型#

基于每当在 timeInterval 秒内 crossing（穿越）绊线达到 countThreshold 次时触发警报。

HTTP POST

/api/v2/config/rule/alerts/tripwire

{
  "sensorId": "Amcrest_1",
  "rules": [
    {
      "ruleId": "cd2218f6-e4d2-4ad4-9b15-3396e4336064",
      "id": "MAIN",
      "type": "tripwire",
      "ruleType": "flowrate",
      "timeInterval": 1,
      "countThreshold": 10,
      "direction": "entry"
    },
    {
      "ruleId": "6f12fd2e-42eb-41aa-b221-44c1368b747f",
      "id": "MAIN",
      "type": "tripwire",
      "ruleType": "flowrate",
      "timeInterval": 1,
      "countThreshold": 2,
      "direction": "exit"
    }
  ]
}

必需的查询参数#

ruleId

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

type: string

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

id

description: 指定绊线警报规则的绊线。

type: string

example: id: MAIN

type

description: 此警报相关的分析模块类型。固定值 'tripwire'

type: string

example: tripwire

timeInterval

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

type: 整数

example: timeInterval: 10

countThreshold

description: crossing（穿越）次数。

type: 整数

example: countThreshold: 10

ruleType

description: 警报规则类型。固定值 'flowrate'

type: string

value: flowrate

direction

description: 警报规则的方向性。规则是指向入口方向 (entry) 还是相反方向 (exit) 的对象 crossing（穿越）？

type: string

enum: entry/exit 之一

example: exit

可选规则参数#

name

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

type: string

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

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

错误响应#

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

HTTP 状态代码

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

增量警报类型#

基于在 timeInterval 秒内对象 entry/exit crossing（穿越）绊线达到 countThreshold 次时触发警报。

HTTP POST

/api/v2/config/rule/alerts/tripwire

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

必需的查询参数#

ruleId

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

type: string

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

id

description: 指定警报规则的绊线 ID。

type: string

example: id: MAIN

type

description: 分析模块类型。固定值 'tripwire'

type: string

value: tripwire

ruleType

description: 警报规则类型。固定值 'increment'

type: string

value: increment

timeInterval

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

type: 整数

example: timeInterval: 10

countThreshold

description: 警报计数数量。

type: 整数

example: countThreshold: 10

direction

description: 警报规则的方向性。规则是指向入口方向 (entry) 还是相反方向 (exit) 的对象 crossing（穿越）？

type: string

enum: entry/exit 之一

example: exit

可选规则参数#

name

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

type: string

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

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

错误响应#

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

HTTP 状态代码

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

删除绊线警报规则#

HTTP DELETE

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

必需的查询参数#

sensorId

description: 需要删除绊线警报的传感器。

type: string

example: sensorId=Amcrest_11

tripwireId

description: 要删除此警报规则的绊线的 ID

type: string

example: id=MAIN

ruleId

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

type: string

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

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

错误响应#

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

HTTP 状态代码

403：授权错误。缺少 User-Type 标头。必须存在且值为 Admin。422：未找到指定 sensorId、tripwireId 和 ruleId 的警报规则。500：内部服务器错误

检索绊线警报#

可以使用 API 系列检索警报，该 API 系列具有传感器、绊线、时间范围的过滤，并可选支持分页。

特定传感器在时间范围内的所有绊线警报#

HTTP GET

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

响应：#

{
  "alerts": [
        {
            "count": 10,
            "description": "10 people exited tripwire",
            "duration": 0.734,
            "endTimestamp": "2021-09-16T06:07:00.534Z",
            "id": "unique-alert-id",
            "ruleType": "increment",
            "ruleId": "fb298ea4-30aa-4085-b860-42e37c5bf8d1",
            "sensorId": "Amcrest_1",
            "startTimestamp": "2021-09-16T06:06:59.800Z",
            "type": "tripwire",
            "direction": "entry",
            "directionName": "Inside the room",
            "attributes": [
                {
                  "name": "tripwireId",
                  "value": "door1"
                },
                {
                  "name": "tripwireName",
                  "value": "Main Door"
                },
                {
                  "name": "directionName",
                  "value": "Inside the room"
                },
                {
                  "name": "direction",
                  "value": "entry"
                },
                {
                  "name": "objects",
                  "value": [
                     {
                           "id": "1186",
                           "type": "Person"
                     }
                  ]
               }
            ],
        },
        {
            "count": 2,
            "description": "flowrate exceeds 2 ppl/s in 5 second window",
            "duration": 0.734,
            "endTimestamp": "2021-09-16T06:07:00.534Z",
            "id": "unique-alert-id",
            "ruleId": "fb298ea4-30aa-4085-b860-42e37c5bf8d1",
            "ruleType": "flowrate",
            "sensorId": "Amcrest_1",
            "startTimestamp": "2021-09-16T06:06:59.800Z",
            "type": "tripwire",
            "direction": "exit",
            "directionName": "Out of the room",
            "attributes": [
                {
                  "name": "tripwireId",
                  "value": "door1"
                },
                {
                  "name": "tripwireName",
                  "value": "Main Door"
                },
                {
                  "name": "directionName",
                  "value": "Out of the room"
                },
                {
                  "name": "direction",
                  "value": "exit"
                }
            ],
        }
    ]
}

必需的查询参数#

sensorId

description: 需要返回绊线警报的传感器。

type: string

example: sensorId=Amcrest_11

fromTimestamp

description: 需要返回绊线警报的 timestamp（时间戳）的下限

type: UTC / GMT timestamp 字符串

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

toTimestamp

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

type: UTC / GMT timestamp 字符串

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

可选的查询参数#

limit

description: 要返回的最大警报数

type: 整数

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

响应正文属性#

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

错误响应#

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

HTTP 状态代码

422：未找到请求的 sensorId、tripwireId 和时间范围的绊线警报。500：内部服务器错误

示例#

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

删除绊线配置#

HTTP DELETE

/api/v2/config/tripwire?sensorId=Amcrest_1&tripwireId=MAIN

必需的查询参数#

sensorId

description: 需要删除绊线配置的传感器。

type: string

example: sensorId=Amcrest_11

tripwireId

description: 需要返回绊线配置的绊线。

type: string

example: tripwireId=MAIN

注意

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

错误响应#

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

HTTP 状态代码

403：授权错误。缺少 User-Type 标头。必须存在且值为 Admin。422：未找到指定 sensorId 和 tripwireId 的绊线配置。500：内部服务器错误

错误响应正文：#

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

{
   "detail": "#Detailed error string"
}
本页内容