智能 Ipc Openapi参考手册 - v0.95

智能 IPC OpenAPI 参考手册
V0.95
0 / 55
变更版本变更日期变更内容
V 0.6 2019-06-05 创建基础版本，包含应用数据和设
备管理接口
V0.7 2019-06-28 适配 1.2.5 版本
V0.8 2019-07-02 Resnapthr 0 表示 disable
V0.9 2019-07-03 移除设备管理部分
V0.91 2019-07-08 Imgtype 值改为 0
V0.92 2019-08-04 补充版本信息
V0.93 2019-08-27 中性版本
V0.94 2019-09-10 基于 MQTT 协议的客户 SaaS 的设
备管理接口初始版本；
V0.95 2019-09-16 变更导入导出接口
1
目录
1. 概述........................................................................................................................................................................................ 3
2. 产品架构............................................................................................................................................................................... 4
2.1. 产品部署..................................................................................................................................................................... 4
3. 应用数据推送...................................................................................................................................................................... 4
3.1. 应用数据推送............................................................................................................................................................ 5
3.2. 数据推送配置............................................................................................................................................................ 5
3.2.1. 身份信息配置 ................................................................................................................................................. 6
3.2.2. 数据推送配置 ................................................................................................................................................. 7
3.3. 数据推送 API ............................................................................................................................................................. 7
3.3.1. 请求 API ........................................................................................................................................................... 7
3.3.2. 请求方法 .......................................................................................................................................................... 8
3.3.3. 请求参数 .......................................................................................................................................................... 8
3.3.4. 参数说明 .......................................................................................................................................................... 8
3.3.5. 响应参数 ........................................................................................................................................................ 11
3.3.6. 报文示例 ........................................................................................................................................................ 12
4. 设备管理............................................................................................................................................................................. 20
4.1. 设备管理服务器配置 ............................................................................................................................................ 20
4.2. 详细接口描述.......................................................................................................................................................... 22
4.2.1. Topic 以及相关 payload 定义.................................................................................................................. 22
4.2.2. 属性定义 ........................................................................................................................................................ 27
4.2.3. 服务指令 ........................................................................................................................................................ 42
2
1. 概述
本文档适用于智能人脸抓拍摄像机，智能人脸识别摄像机和智能客流识别一体摄像机。
本文档主要包括两个部分，应用数据推送以及设备管理数据推送。其中，设备管理部分
IPC 基于 MQTT 协议的封装来提供相关管理功能，数据推送部分，IPC 通过 HTTP 协议将
数据推送到用户的应用服务器。
设备管理部分描述 IPC 与设备管理服务器对接所需的协议。IPC 侧使用 DM 进程，通
过基于 MQTT 封装的 SDK 来与设备管理服务器进行交互，主要完成对设备管理服务器向
IPC 下发命令的响应。命令主要包括：智能参数设置及获取，远程 OTA 升级，远程重启，
设备截图以及本地建库等。
应用数据推送部分描述如何配置摄像机，把智能数据推送到客户 SaaS 的指定接收地址。
智能摄像机将人脸抓拍，人脸识别，客流统计等数据通过 JSON 格式推送，数据类型包含但
不限于以下数据：
➢ 客流人次统计
➢ 人脸抓拍图片及其时间戳、人脸框坐标等信息
➢ 人脸结构化数据（年龄、性别等）
➢ 人脸识别结果，包含特征及用户 id，相似度，人脸库照片等信息
本文档对应的摄像机固件版本为：
版本备注
智能人脸抓拍摄像机 1.3.2
智能客流分析摄像机 1.3.2
智能人脸识别摄像机 1.3.2
3
2. 产品架构
2.1. 产品部署
HTTP 应用服务器
摄像机
MQTT 设备管理服务
图 2-1 产品部署示意图
摄像机支持跨公共网络的部署。
根据获得的应用服务器的地址和端口，摄像机将分析的智能数据通过 HTTP 协议推送到运
行有 HTTP Server 的应用服务器，应用服务器接收 HTTP 数据并做进一步的处理。
根据获得的设备管理服务器的地址和端口，摄像机通过 MQTT 协议与设备管理服务器通讯，
从设备管理服务器得到指令；摄像机根据指令的内容完成相应的处理，并将处理结果上报给
设备管理服务器。
3. 应用数据推送
应用数据包括智能人脸抓拍数据、识别数据和客流分析数据。
4
3.1. 应用数据推送
图 3-1 应用数据推送交互时序图
3.2. 数据推送配置
数据推送相关配置需要通过使用智能摄像机展示客户端进行配置。
图 3-2 智能摄像机展示端工具界面
1. 通过 IP 地址连接目标 IPC，确认设备在线;
2. 点击设备 IP 右侧配置按钮，进入配置页面。
5
3.2.1. 身份信息配置
图 3-3 摄像机身份设置界面
设置摄像机身份信息，摄像机在推送数据时会将身份信息加入到推送消息中，应用服务器可
以根据摄像机的身份信息来区分连接的摄像机。
名称说明消息定义示例必选
一级 ID 数字，用于标识摄像一级分类 ID，如组织 ID。 LevelOneId 123 是
一级 ID 名称字符，用于标识摄像机一级分类名称，如组织名称。 LevelOneName site 是
二级 ID 数字，用于标识摄像二级分类 ID，如组织 ID LevelTwoId 123 是
二级 ID 名称字符，用于标识摄像机二级分类名称，如组织名称 LevelTwoName division 是
设备 ID 标识摄像机的唯一 ID DeviceID 123 是
设备名称标识摄像机的唯一名称 DeviceName IPC-Entrance 是
6
3.2.2. 数据推送配置
图 3-4 摄像机应用服务器地址设置页面
名称说明示例必选
服务器地址接收数据推送的服务器地址 http://example.com 是
端口服务器的端口号，默认 80 端口 8080 否
url 接收数据推送的服务器 url /api/xxx 否
3.3. 数据推送 API
数据推送服务需要用户通过 IPC 的配置工具配置服务器的 URL 后使用，参见 3.2 数据推送
配置。
3.3.1. 请求 API
接收数据的 URL 由上图“数据推送服务器后缀 url”指定的配置。
7
3.3.2. 请求方法
标准 HTTP POST
注意：有限支持 HTTPS 推送，具体牵涉到证书等交互，需另外协商。
3.3.3. 请求参数
Headers
参数类型说明
Content-Type String application/json
3.3.4. 参数说明
注意：
1、这里的数据内容，会不断更新，再提供更多维度信息的同时确保向下兼容。
2、以下时区等信息，在 WebUI 上修改后，需要重启 IPC，相应的信息才能在数据推送中得
到更新
参数类型是否必描述
填
Properties 是 IPC 设备基本信息的父节点
LevelOneId String 是可用作 IPC 安装地所属 SiteId，由管理工具配置
LevelOneName String 是可用作 IPC 安装地所属 Site 名称，由管理工具配
置
LevelTwoId String 否可用作 IPC 安装所属部门，由管理工具配置
LevelTwoName String 否可用作 IPC 设备 ID，由管理工具配置
DeviceId String 否 IPC 设备 ID，由管理工具配置
DeviceName String 否 IPC 设备名称，由管理工具配置
TransmitTime String 是本条数据发送的时间戳，相对于 UTC 1970 年 1
月 1 日 0 时 0 分 0 秒的总毫秒数
MacAddress String 是 IPC 的 Mac 地址
IPv4Address String 是 IPC 的 IPV4 地址
TimeZone String 是 IPC 的时区信息
TimezoneName String 是 IPC 的时区名字
8
BaseVer String 是 IPC 的基础版本信息
OTAVer String 是 IPC 的 OTA 版本
ModelVer String 是 IPC 的模型版本
FirmwareVer String 是 IPC 的固件版本
SDKVer String 是 IPC 的 SDK 版本
SmartVer String 是 IPC 的智能版本
SerialNumber String 是 IPC 的序列号
SmartData String 是智能数据父节点
Face String 否智能数据类型为抓拍的根节点
TimeStamp Number 是抓拍数据时间戳，相对于 UTC 1970 年 1 月 1 日
0 时 0 分 0 秒的总毫秒数
PersonId Number 是抓拍人脸 Id
SnapShot Base64 是抓拍图片数据
ImgType Number 是图片类型
PicBox [Numbe 是抓拍框的坐标，参见 “图 3-5 人脸抓拍图片坐
r, Numb 标示意图
er, Num “
ber, Nu
mber]
FaceBox [Numbe 是人脸框中的坐标, 参见” 图 3-5 人脸抓拍图片
r, Numb 坐标示意图
er, Num ”
ber, Nu
mber]
Gender Number 是性别，数值型 1 男性 0 女性
Age Number 是年龄区间，1: [0-18], 2: [19-35], 3: [36-55], 4
56+
LivingScore Number 是活体打分：0 ~ 100
Pose Number 是三轴角度归一化值：-2000 ~ 2000
Yaw Number 是绕 Y 轴旋转偏角：-90 ~ 90
Pitch Number 是绕 X 轴旋转偏角：-90 ~ 90
Roll Number 是绕 Z 轴旋转偏角：-90 ~ 90
Quality Number 是图片质量：-200 ~ 200
FlowEvent 否过线事件
Timestamp Number 是过线时间戳，相对于 UTC 1970 年 1 月 1 日 0 时
0 分 0 秒的总毫秒数
PersonId Number 是过线人员 ID
FlowType Number 是过线事件类型，0 表示进线，1 表示出线
FlowStats 否客流统计数据
Timestamp Number 是开始统计时间，相对于 UTC 1970 年 1 月 1 日 0
时 0 分 0 秒的总毫秒数
Interval Number 是统计时长
InNumber Number 是进线人次
9
OutNumber Number 是出线人次
LineId Number 是线 ID
LineType Number 是线类型, 0 表示进出线；1 表示途径线
TotalNumber Number 是总人数，过线（进出线/途径线）人次之和
FrontNumber Number 是正脸抓拍人数
InFemaleNumber Number 是进线总女性人数
InMaleNumber Number 是进线总男性人数
InMale06Number Number 是进线 0-6 岁总男性人数
InMaleGt56Number Number 是进线大于等于 56 岁总男性人数
InFemale06Number Number 是进线 0-6 岁总女性人数
InFemale712Numbe Number 是进线 7-12 岁总女性人数
r
InFemale1318Numb Number 是进线 13-18 岁总女性人数
er
er
er
er
er
InFemaleGt56Numb Number 是进线大于等于 56 岁总女性人数
er
OutFemaleNumber Number 是出线总女性人数
OutMaleNumber Number 是出线总男性人数
OutMale06Number Number 是出线 0-6 岁总男性人数
OutMale712Number Number 是出线 7-12 岁总男性人数
OutMale1318Numb Number 是出线 13-18 岁总男性人数
er
er
er
er
10
er
OutMaleGt56Numbe Number 是出线大于等于 56 岁总男性人数
r
OutFemale06Numbe Number 是出线 0-6 岁总女性人数
r
OutFemale712Numb Number 是出线 7-12 岁总女性人数
er
OutFemale1318Num Number 是出线 13-18 岁总女性人数
ber
ber
ber
ber
ber
OutFemaleGt56Num Number 是出线大于等于 56 岁总女性人数
ber
Feature 否识别数据
Timestamp Number 是抓拍时间戳，相对于 UTC 1970 年 1 月 1 日 0 时
0 分 0 秒的总毫秒数
trackId Number 是被识别的人的 Id，与抓拍图的 PersonId 对应
FeatureInfo Byte 是人脸特征值 128 位
MatchedImg Base64 是被识别的底库照片，Base64 编码
MatchedId String 是人脸特征库存中匹配的 ID，与增改 ID 接口中传
入的参数 uid 一致
MatchedRate Number 是人脸特征匹配相似度
DatabaseId Number 是人脸特征数据库 ID
CropImg Base64 是被识别的抓拍照片，Base64 编码
Name String 是人脸对应 Name 字段
Ext1 String 是人脸对应 Ext1 字段
3.3.5. 响应参数
参数类型是否必填描述示例值
RequestId String 是用于区分每一次请求的唯一的字符串。除非发生
404(API_NOT_FOUND)错误，否则此字段必定返回
11
Code Number 是当前 request 返回状态码，0 表示成功，其他详见错
误码
Message String 是当前 request 返回描述信息
Data object 是当前 request 返回的数据
背景图框
人脸框
抓拍框
图 3-5 人脸抓拍图片坐标示意图
3.3.6. 报文示例
3.3.6.1. 人脸抓拍请求示例
适用于抓拍机，识别机人脸抓拍但未识别，客流机人脸抓拍数据推送。
请求 api
POST 数据推送服务器的配置
请求 body
{
"Properties": {
"LevelOneId": "level1Id",
"LevelOneName": "level1Name",
"LevelTwoId": "level2Id",
"LevelTwoName": "level2Name",
"DeviceId": "deviceId",
12
"DeviceName": "deviceName",
"TransmitTime":"1557061092",
"MacAddress":"ff:ff:ff:ff:ff:ff",
"Ipv4Address":"127.0.0.1",
"TimeZone":"UTC+8",
"TimezoneName": "GMT+08 Taipei, Beijing, Chongqing, Urumqi, Hong Kong,
Perth, Singapore",
"BaseVer":"3519V101_IMX385_H_BASE_W_9.1.21.3",
"OTAVer":"HR-IPC2XX5-X1B-V1.2.2-FLOW-20190430",
"ModelVer":"MD-0.2.12",
"FirmwareVer":"FW-1.7.2-01.01.01",
"SDKVer":"SDK-1.3.8-01.01.01-02",
"SmartVer":"SMART-2.1.1-beta.pa1-01.01.05-01",
"SerialNumber":"068B3001010110077L"
},
"SmartData": {
"Face":{
"TimeStamp":"1557061092",
"PersonId":"xxxxxxxx",
"SnapShot":"aaaasdfasfsafsafsadf",
"ImgType":"1",
"PicBox":"10,10,30,30",
"FaceBox":"15,15,45,45",
"Gender":"0",
"Age":"1",
"LivingScore":"1",
"Pose":"0",
"Yaw":"0",
"Pitch":"0",
"Roll":"1",
"Quality":"1"
}
}
}
3.3.6.2. 人脸识别请求示例
适用于识别机比对成功的数据推送。此时，识别结果，和识别对应的抓拍图会分成两个报文
上报。
请求 url
13
请求 body
{
"Properties": {
"Ipv4Address":"127.0.0.1",
"TimeZone":"UTC+8",
Perth, Singapore",
"FirmwareVer":"FW-1.7.2-01.01.01",
"SDKVer":"SDK-1.3.8-01.01.01-02",
},
"SmartData": {
"Face":{
"TimeStamp":"1557061092",
"ImgType":"1",
"PicBox":"10,10,30,30",
"FaceBox":"15,15,45,45",
"Gender":"0",
"Age":"1",
"LivingScore":"1",
"Pose":"0",
"Yaw":"0",
"Pitch":"0",
"Roll":"1",
"Quality":"1"
}
}
14
}
以及识别结果
{
"Properties": {
"Ipv4Address":"127.0.0.1",
"TimeZone":"UTC+8",
Perth, Singapore",
"FirmwareVer":"FW-1.7.2-01.01.01",
"SDKVer":"SDK-1.3.8-01.01.01-02",
},
"SmartData": {
"Feature":{
"MatchedImg":"aaaaaaaaaaaa…"
"Timestampe":"1557061092",
"FeatureInfo":"1.0000,10000,10000 ...",
"MatchedId":"xxxx-xxxx-xxxx-xxxx",
"MatchedRate":0.80,
"DatabaseId":"123",
"CropImg":"bbbbbbbbbbbb…"
}
}
}
15
3.3.6.3. 客流统计结果请求示例
适用于客流机设置为按时间段统计结果的推送。
请求 url
请求 body
{
"Properties": {
"Ipv4Address":"127.0.0.1",
"TimeZone":"UTC+8",
Perth, Singapore",
"FirmwareVer":"FW-1.7.2-01.01.01",
"SDKVer":"SDK-1.3.8-01.01.01-02",
},
"SmartData": {
"FlowStats":{
"TimeStamp":1558685462, //开始统计时间,相对于 UTC1970 年 1 月 1 日 0 时 0
分 0 秒的总秒数"LineId":1,
"LineType":0,
"Interval":1800, //单位秒
16
"TotalNumber":530,
"InNumber":300,
"OutNumber":230,
"TotalNumber":1
"FrontNumber":1
"InFemaleNumber":1
"InMaleNumber":1
"InMale06Number":1
"InMale712Number":1
"InMale1318Number":1
"InMaleGt56Number":1
"InFemale06Number":1
"InFemaleGt56Number":1
"OutFemaleNumber":1
"OutMaleNumber":1
"OutMale06Number":1
"OutMale712Number":1
"OutMaleGt56Number":1
"OutFemale06Number":1
"OutFemaleGt56Number":1
}，
17
}
3.3.6.4. 客流统计事件请求示例
适用于客流机统计时间设置为 0，即实时客流事件的统计数据推送。
请求 url
请求 body
{
"Properties": {
"Ipv4Address":"127.0.0.1",
"TimeZone":"UTC+8",
Perth, Singapore",
"FirmwareVer":"FW-1.7.2-01.01.01",
"SDKVer":"SDK-1.3.8-01.01.01-02",
},
"SmartData": {
"Face":{
"TimeStamp":"1557061092",
"ImgType":"1",
"PicBox":"10,10,30,30",
"FaceBox":"15,15,45,45",
"Gender":"0",
18
"Age":"1-18"
},
"FlowEvent":{
"TimeStamp":"1557061092",
"LineId":1,
"LineType":0,
"PersonId":1558685460,
"FlowType":0
},
}
}
客流事件
{
"Properties":{
"LevelOneId":"level1Id",
"LevelOneName":"level1Name",
"LevelTwoId":"level2Id",
"LevelTwoName":"level2Name",
"DeviceId":"deviceId",
"DeviceName":"deviceName",
"Ipv4Address":"127.0.0.1",
"TimeZone":"UTC+8",
"DST":0,
"OTAVer":"",
"ModelVer":"",
"FirmwareVer":"",
"SDKVer":"",
"SmartVer":"",
"SerialNumber":"xxxxxxxx"
},
"SmartData":{
"FlowEvent":{
"TimeStamp":"1557061092",
"FlowType":1
}
}
}
返回成功示例
19
{
"request_id":"911b9802-732c-4a4c-a3f4-e2735ab59bc0",
"message":"success",
"code":0,
"data":null
}
返回失败示例
{
"request_id":"911b9802-732c-4a4c-a3f4-e2735ab59bc0",
"message":"缺少必须的参数",
"code":10003,
"data":null
}
4. 设备管理
4.1. 设备管理服务器配置
摄像机与设备管理服务器的交互时序简单表示如下：
图 4-2 摄像机与设备管理服务器交互时序示意图
1. 客户 SaaS 通过 MQTT Broker 把需要下发的控制信息通过相应 Topic Pub 出来；
2. 摄像机通过 Sub 接收从客户 SaaS 下发的各种指令和信息
3. 摄像机执行指控信息后，通过相应的 Topic 上报应答；
在 IPC 的配置工具打开设备设置页面，选择快速接入页进行接入 token 配置：
20
图 4-1 设备管理接入设置
注意：这里主要是让 IPC 能够被服务器发现并注册（注册信息需要客户来指定，比如，
3.2.1 身份信息设置中提到的），然后获得需要配置的各种服务信息。
目前使用 iot-sdk 进行设备管理的相关对接及命令和属性的通信。iot-sdk 提供
mqtt 相关服务，定义了下述接入流程和服务、属性接口的 Topic 以及数据格式。
使用 iot-sdk，接入 mqtt broker 的逻辑如下：
接入 token 为 base64 编码，解码后的格式如下：
{
"activation":{
"url":"xxxxxxxx",
"http_method":"POST",
"headers":{},
"body":{}
}
}
sdk 内部解码该 token 为如上格式，根据解码后的参数请求对应 url，请求返回体格式
如下：
21
⚫ 参数 mqtt_broker 为 broker 地址，连接成功后，即订阅、发布主题消息；
⚫ thing_id 是 IPC 与 broker 通信的唯一标志
{
"thing_id":"xxx", //IPC 在 broker 上唯一标识
"app_id":"xxxx",
"space_id":"xxxxxxxx",
"connection":{
"mqtt_broker":"tcp://10.64.35.117:1883" //broker 地址
},
"oss_infos":[
{
"vendor_list":[
"aliyunoss"
],
"bucket":"bucket",
"endpoint":"xxx",
"region":"region",
"access_key":"xxx",
"secret_key":"xxx"
}
]
}
4.2. 详细接口描述
以下描述具体的 IPC 和客户 SaaS 之间的关键交互 Topic 以及 Payload 定义，IPC 通过以
下 Topic 的 Pub/Sub 来完成相互的交互。
4.2.1. Topic 以及相关 payload 定义
4.2.1.1. 属性相关
属性是用来对 IPC 的相关配置与服务端进行上报及设置。
22
Topic
topic
发布/订阅用途
hobot/{ClientId}/property/report IPC 发布属性周期上报，30s
hobot/{ClientId}/property/asyncupd/req
IPC 订阅属性变更（异步请求）
uest
hobot/{ClientId}/property/asyncupd/res
IPC 发布属性变更应答
ponse
hobot/{ClientId}/property/syncupd/requ
IPC 订阅属性变更（同步请求）
est
hobot/{ClientId}/property/syncupd/{Req
IPC 发布属性变更应答
uestId}/response
Payload
属性周期上报
⚫ Topic：$hobot/${ClientId}/property/report //IPC 订阅（Saas 发布）
⚫ Payload：
{
"reported_version":0,
"reported":{
},
"timestamp": 1568016834606 //精确到毫秒
}
⚫ 参数说明：
reported_version：int 类型，IPC 当前属性版本，设备从 PropertyUpdate 消
息体中获取，初始状态默认 0
reported：map[string]interface{}类型，IPC 当前改模块属性，格式见属性定
义
timestamp：int 类型，发送该消息体的时间戳，精确到毫秒
属性变更相关操作：
⚫ 请求下发至 IPC 端：
⚫ Topic：$hobot/${ClientId}/asyncupd/request //IPC 订阅（Saas 发布）
23
$hobot/${ClientId}/syncupd/request //IPC 订阅（Saas 发布）
⚫ Payload：
{
"request_id":"",
"desired_version":1,
"desired":{
},
"timestamp":0
}
⚫ 参数说明：
request_id：string 类型，作为该次请求标志
desired_version：int 类型，属性版本，下发 desired_version 须大于等于
IPC 当前属性版本
desired：map[string]interface{}类型，更改属性，格式见属性定义
timestamp：int 类型，可选，下发该 request 的时间戳
⚫ IPC 端应答：
⚫ Topic：$hobot/${ClientId}/asyncupd/response //IPC 发布（Saas 订阅）
$hobot/${ClientId}/syncupd/${RequestID}/response //IPC 发
布（Saas 订阅）
⚫ Payload：
{
"code":0,
"message":"",
"reported_version":0:
"reported":{
},
"timestamp":0
}
⚫ 参数说明：
code：int 类型，返回码，非 0 表示属性更新失败
message： string 类型，返回信息
reported_version：int 类型，IPC 当前属性版本
reported：map[string]interface{}类型，IPC 当前改模块属性，格式见属性定
义
timestamp：int 类型，可选，发送该消息体的时间戳
4.2.1.2. 服务相关
服务是用来从服务端主动要求 IPC 进行一些操作，如重启、升级、本地建库等，具体见服务
24
指令中描述。
Topic
topic
发布/订阅用途
hobot/{ClientId}/service/async/request IPC 订阅异步服务下发
hobot/{ClientId}/service/async/response IPC 发布异步服务应答
hobot/{ClientId}/service/sync/request IPC 订阅同步服务下发
hobot/{ClientId}/service/sync/{RequestId}/r
IPC 发布同步服务应答
esponse
Payload
⚫ 请求下发至 IPC 端：
⚫ Topic：$hobot/${ClientId}/service/async/request //IPC 订阅（Saas
发布）
$hobot/${ClientId}/service/sync/request //IPC 订阅（Saas 发
布）
⚫ Payload：
{
"request_id":"",
"service_id":"",
"payload":{
},
"timestamp":0
}
⚫ 参数说明：
request_id：string 类型，作为该次请求标志，指令 id
service_id：string 类型，指令类型，表示操作类型
payload：[]byte 类型，指令内容，格式见服务指令
timestamp：int 类型，发送该消息体的时间戳
⚫ IPC 端应答：
25
异步服务应答
（重启，升级后的应答通过该 topic 发布）
⚫ Topic：$hobot/${ClientId}/service/async/response //IPC 发布（Saas

订阅）
⚫ Payload：
{
"request_id":"",
"payload":{
},
"timestamp":0
}
同步服务应答
⚫ Topic：$hobot/${ClientId}/service/sync/${requestid}/response
//IPC 发布（Saas 订阅）
⚫ Payload：
{
"payload":{
},
"timestamp":0
}
参数说明：
payload：interface{}类型，包括 code，status 等信息
• $ClientId 是每个设备的唯一标识，与 4.1 设备管理服务器配置中 thing_id 一致
4.2.1.3. 事件相关
事件用来提供给 IPC 主动上报相关的内容
26
Topic
topic
发布/订阅用途
hobot/{ClientId}/event/post IPC 发布 IPC 上报事件，暂未使用
Payload
⚫ Topic：$hobot/${ClientId}/event/post //IPC 发布（Saas 订阅）

⚫ Payload：
{
"request_id":"",
"event_id":"",
"payload":{
},
"timestamp":0
}
⚫ 参数说明：
event_id：string 类型，上报事件类型
payload：map[string]interface{}类型，事件内容
4.2.2. 属性定义
以下各个操作的内容与 4.3.2.3 属性相关的格式相对应
属性定义用来机型 IPC 参数配置/查询，范围包括智能人脸参数、客流参数。IPC 通过
Pub/Sub 相应的 Topic 获取到参数配置/查询任务，执行相应的操作，并告知设备管理服务
器指令执行状态和最新模块参数值。
27
4.2.2.1. Smart 版本信息
仅周期上报，不支持更新
参数名值类型有效范围含义

ota string 0~255 位 ASCII 可打印字符 OTA 版本
model string 0~31 位 ASCII 可打印字符 Model 版本
firmware string 0~31 位 ASCII 可打印字符 Firmware
sdk string 0~31 位 ASCII 可打印字符 SDK 版本
smart string 0~31 位 ASCII 可打印字符 Smart 版本
{
"smartinfo":{
"model":"",
"firmware":"",
"sdk":"",
"ota":"",
"smart":""
}
}
4.2.2.2. 设备信息

SerialNo string 0~127 位 ASCII 可打印字符设备序列号
DeviceType string 0~127 位 ASCII 可打印字符设备类型
FirmwareVer string 0~127 位 ASCII 可打印字符 Firmware 版本
sion
{
"deviceInfo":{
"SerialNo":"",
"DeviceType":"",
"FirmwareVersion":""
}
}
28
4.2.2.3. 网络信息

MacAddress string 0~127 位 ASCII 可打印字符 Mac 地址
LocalIp string 0~127 位 ASCII 可打印字符 Ip 地址
NetMask string 0~127 位 ASCII 可打印字符子网掩码
GateWay string 0~127 位 ASCII 可打印字符网关
Dns1 string 0~127 位 ASCII 可打印字符 Dns
Dns2 string 0~127 位 ASCII 可打印字符 Dns
{
"network":{
"MacAddresss":"",
"LocalIp":"",
"NetMask":"",
"GateWay":"",
"Dns1":"",
"Dns2":""
}
}
4.2.2.4. 抓拍参数

snapsizethr int 抓拍机/客流机抓拍的最小人脸大小(单位像素)
32~256；
识别机 64~256
frontthr int 1~10 正脸阈值
beginpostframethr double 抓拍机/识别机有效抓拍优选时间（捕获对象连续出现多长时间上报抓拍图）
有效值 0.5、1、2、
3、4、5、10、20、
30、40
resnapthr int 抓拍机/识别机有效再次抓取（时间 0 表示 disable）
有效值 0、0.5、1、
2、3、4、5、10、
20、30、40；
0：表示关闭；
29
注意：仅抓拍机，识
别机可设置；
若 resnapthr 非
disable 时，限制
resnapthr>=
beginpostframethr
；
snapscale double 1.0~4.0 人脸外廓系数
firstnumavailthr int 抓拍机有效单个 trackID 抓拍数
1~3
仅抓拍机可设置
numaftervanish int 1~100 消失帧数（捕获对象连续消失若干帧后，停止追踪）
switchregion bool 抓拍机/识别机有效是否仅在指定区域中抓拍
false, true,
captregion array 抓拍机/识别机有效抓拍区域坐标
x: 0~1920
y : 0~1080
captbackground bool false, true, 是否抓拍人脸出现时的背景图
track_score_eliminate uint 1~10 灵敏度
snap_mode uint 客流机有效开关，是否开启全量抓拍
0~1
living_en bool False,true 是否使能 x1 侧活体模型
0：默认活体模型不开启；
1：使能活体模型
living_thr int 1-100 活体阈值
win int 默认 25 活体检测滑动窗口大小，只读
sel_face_mode uint 0-1 大脸模式
0-正常优选识别
1-大脸模式优选识别
hieldregion_working bool true，false 是否开启隐私区域
shieldgion array x: 0~1920 隐藏区域坐标，最大支持 4 个区域
y : 0~1080
默认值为（-1，-1，-
1，-1）表示未开启
q_factor uint 0 – 低，1 – 中，2 – 背景图压缩 QFactor
高
resolution uint 0 – 1920 * 1080，背景图分辨率
1 – 1280 * 720，
2 – 720 * 480
30
"capecfg":{
"snapsizethr":64,
"frontthr":1,
"beginpostframethr":1,
"snapscale":1,
"resnapthr":1,
"firstnumavailthr":2,
"numaftervanish":1,
"switchregion":true,
"captregion":[
{
"id":0,
"type":0,
"x1":402,
"x2":707,
"y1":160,
"y2":315
}
],
"captbackground":true,
"track_score_eliminate":3,
"snap_mode":true,
"hieldregion_working":false,
"living_en":false,
"living_thr":0,
"sel_face_mode":0,
"shieldgion":[
{
"d":0,
"type":0,
"x1":-1,
"x2":-1,
"y1":-1,
"y2":-1
}
]
}
}
4.2.2.5. 客流参数
客流参数定义如下：
31
type int 0~1 0 - 仅做过线
1 - 过线+年龄+性别
lines array x1, x2: 0~1920 越界线设置
y1, y2: 0~1080 x1, y1, x2, y2: 线段坐标
type:0~1 线的两个点坐标,左上为坐标原点,右下为(1920,1080),
linetype:0~1 其他分辨率映射到该区域
每种线最多设置一条，可 type：越线判定类型
以有折现，一条线的折现 0 – 从左到右,从上到下为进入
最多 6 条，且下条折线的 1 - 从左到右,从上到下为出去
起点和上条折线的终点 linetype: 线的类型
一致 0 - 客流线
1 - 途径线
crontab string 1~127 位 ASCII 可任务的开始时间转为 crontab 格式"秒分时日月周
打印字符 "，时间为 UTC 时间，如任务开始时间为每天 2:30 CST，
转为 crontab 格式为"0 30 18 * * *"。客流起始时间不能跨
天。不允许出现？ /等符号
duration int 0-86340 任务持续时长，单位秒，如任务周期 2：30-8：20，则
duration 为 21000
start_time string string 12:44 格式的时间字符串，为当地时间，该参数不为空时，
忽略 crontab 参数，start_time+ duration 不能超出一天
upload_interval int 0~1440 0 表示不输出统计数据 N(非 0 值)表示客流统计上报间
隔，单位为分钟
upload_event bool true, false 是否上报客流事件
表 4-2 客流参数列表
{
"passflow":{
"type":1,
"lines":[],
"crontab":"",
"duration":"",
"start_time":"",
"upload_interval":9,
"upload_event":true
}
}
32
4.2.2.6. 识别参数
识别参数定义如下：

recog_switch bool true, false 客流识别机用，是否开启识别
recog_snap bool true, false 抠图消息和识别消息推送；true 只推送识别消息；false 同
时推送抠图识别消息
send_origin_img bool true, false 识别消息中是否携带底库图片
表 4-3 识别参数列表
{
"RecogApp":{
"recog_switch":true,
"recog_snap":true,
"send_origin_img":true
}
}
4.2.2.7. 商业部署

reserved string 0~127 位 ASCII 可打印字符预留信息，可以不传
app_svr string 0~127 位 ASCII 可打印字符应用服务器地址
app_port int 1-65535 应用服务器端口
app_path string 0~127 位 ASCII 可打印字符应用服务器后缀路径
dm_svr string 0~127 位 ASCII 可打印字符设备管理服务器地址
dm_port int 1-65535 设备管理服务器端口
{
"commdeploy":{
"app_port":117,
"app_svr":"10.64.35.117",
"app_path":"",
"dm_port":80,
"dm_svr":"",
"reserved":""
}
}
33
4.2.2.8. FTP 参数
FTP 参数定义如下：

serveraddr string 1~127 位可打印字符, IPv4 格式地址服务器地址
port int 1~65535 服务器端口
path string 1~31 位 ASCII 可打印字符服务器目录
【允许 ASCII：32-126 字符】
user string 1~31 位 ASCII 可打印字符账户名
password string 1~31 位 ASCII 可打印字符账户名
switch bool true, false 是否打开 FTP 上传
savebackground bool true, false 是否上传背景图
istest bool true, false 该模块参数设置是否用于测试，若是，则不
会正式保存
configresult int 有效值：0~2; 0：unknown, 1:成功，2: 正式设置的 ftp server 能否连接并上传图片
失败。Read only
testresult int 有效值：0~2; 0：unknown, 1:成功，2: 测试用的 ftp server 能否连接并上传图片
失败。Read only
表 4-4 ftp 参数列表
{
"ftpupload":{
"serveraddr":"",
"port":80,
"user":"",
"password":"",
"savebackground":true,
"istest":true,
"configresult":0,
"testresult":0
}
}
4.2.2.9. 人脸曝光参数
enable Bool false,true

人脸曝光使能
34
luminance int 1-100
参考亮度
duration int 1-60

最短持续时间(分钟)
{
"face_exposure":{
"enable":true,
"luminance":18,
"duration":28
}
}
4.2.2.10. 补光参数

lighting int 0：自动补光模式
_mode 1: 白天
2：黑夜
3：定时
int 0-7 补光灵敏度
lg_sensitivit
y
int 3-10 补光过滤时间
lg_filtration
time
lg_gain int 0-100 补光模式在黑夜下灯光亮度
lg_lighthou int 0-23 定时模式下，天亮时间 “时”参数
r
lg_lightmin int 0-59 定时模式下，天亮时间“分”参数
lg_darkhou int 0-23 定时模式下，天黑时间 “时”参数
r
lg_darkmin int 0-59 定时模式下，天黑时间“分”参数
{
"image_lighting":{
"lighting_mode":0,
"lg_sensitivity":0,
"lg_filtrationtime":8,
"lg_gain":10,
35
"lg_lighthour":10,
"lg_lightmin":10,
"lg_darkhour":10,
"lg_darkmin":10
}
}
4.2.2.11. 曝光参数

exposure_ int 0: 自动曝光模式
mode 1：手动
aegain int 0-255 目标亮度
shutter int 0:1/8 电子快门

1:1/15
2:1/25
3:1/30
4:1/50
5:1/60
6:1/75
7:1/100
8:1/120
9:1/125
10:1/150
11:1/250
12:1/300
13:1/500
14:1/1000
15:1/2000
{
"image_exposure":{
"exposure_mode":0,
"aegain":0,
"shutter":8
}
}
36
4.2.2.12. 聚焦

focus_mod int 0: 半自动聚焦聚焦模式
e 1：自动
2：手动
focus_contr int 0:ZOOM_WIDE（调焦+）聚焦控制
ol 1：ZOOM_TELE（调焦-）
2:focus_far（聚焦+）
3:focus_near（聚焦-）
4：oneshotfocus
{
"image_focus":{
"focus_mode":0,
"focus_control":0
}
}
4.2.2.13. 视频调节

dnr_mode int 0：关闭数字降噪模式
1：2D 数字降噪
2：3D 数字降噪
3：全开手动
dnr_3d_val int 0-255 3D 数字降噪
ue
dnr_2d_val int 0-255 2D 数字降噪

ue
{
"image_dnr":{
"dnr_mod":1,
"dnr_3d_value":0，
"dnr_2d_value":0
}
}
37
4.2.2.14. 背光

backlight_e int 0：关闭背光开关
nable 1：开启
backlight_l Int 0-2 背光等级
evel 0：最小
1 适中
2 最大
{
"image_backlight":{
"backlight_enable":0,
"backlight_level":0
}
}
4.2.2.15. 去雾

defog_ena int 0：关闭去雾开关
ble 1：开启
defog_level Int 0-255 去雾等级
{
"image_defog":{
"defog_enable":0,
"defog_level":0
}
}
4.2.2.16. 白平衡

whitebalan int 0：自动白平衡模式
ce_mode 1：手动
wbred_gain int 0-255 红色增益
38
wbgreen_g int 0-255 绿色增益
ain
wbblue_gai int 0-255 蓝色增益
n
{
"image_whitebalance":{
"whitebalance_mode":0,
"wbred_gain":0
"wbgreen_gain":0
"wbblue_gain":0
}
}
4.2.2.17. 图像增强
参数名值类有效范围含义
型
flicker_contr int 0：室内 NTSC 抗闪控制
ol 1：室内 PAL
2：室外
wdr_enable int 0：关闭宽动态设置
1：自动
2：弱
3：适中
4：强
5：超强
6: 数字宽动态
drc_strength Int 0-100 数字宽动态等级
{
"image_enhance":{
"flicker_control":0,
"wdr_enable":0
"drc_strength":0
}
}
39
4.2.2.18. 图像调节参数

brightness int 0-255 图像亮度
contrast int 0-255 图像对比度
saturation int 0-255 饱和度

sharpness int 0-255 锐度
{
"image_adjust":{
"brightness":128,
"contrast":128,
"saturation":128,
"sharpness":128
}
}
4.2.2.19. 视频流参数
模块名：
主码流 video_config_main
子码流 video_config_sub
三码流 video_config_third

bit_rate int 64-15000 比特率单位 Kbps
frame_rate int 1-25 帧率单位 fps
iframe_interval int 1-5 i 帧间隔，单位秒
is_variable_rate int 0-1 主码流码率类型
0 静码率
1 变码率
encodetype int 2-4 编码格式
H264 =2
H265 = 3
MJPEG=4
40
profile int 0-2 profile
0 baseline
1 main
2 high
resolution int 0-3 分辨率类型
0:D1,720*480
1:CIF 352*288
2:1080P 1920*1080
3:720P 1280*720
{
"video_config":{
"bit_rate":128,
"frame_rate":12,
"iframe_interval":1,
"is_variable_rate":1,
"encodetype":1,
"profile":1,
"resolution":1
}
}
4.2.2.20. 身份认证参数

device_id String 0~127 位 ASCII 可打印字符设备 ID
device_name String 0~127 位 ASCII 可打印字符设备名称
levelone_id String 0~127 位 ASCII 可打印字符一级 ID，客户自定义的字段，该值会在数据推送时使用
levelone _name String 0~127 位 ASCII 可打印字符一级名称，客户自定义的字段，该值会在数据推送时使用
leveltwo_id String 0~127 位 ASCII 可打印字符二级 ID，客户自定义的字段，该值会在数据推送时使用
leveltwo _id String 0~127 位 ASCII 可打印字符二级名称，客户自定义的字段，该值会在数据推送时使用
{
"identification":{
"device_id":"",
"device_name":"",
"levelone_id":"",
"levelone_name":"",
"leveltwo_name":"",
"leveltwo_id":""
41
}
}
4.2.3. 服务指令
以下各个指令的内容与的服务相关格式相对应
service_id 意义备注
8210
测试应用服务器通路将当前 IPC 画面截屏发送至
应用服务器
1025
设备升级
8208
设备截图将当前 IPC 画面截屏发送至
指定地址
8209
历史数据上报智能数据上报至应用服务器
8211
设备日志上传设备传统日志上报
8193
设备重启
8801
创建底库
8802
删除底库
8813
更新底库
8804
添加图片
底库管理相关
8805
删除图片
8806
删除底库所有图片保留特征等信息
8810
查询用户信息
8812
查询所有底库信息
42
9904
批量添图
4.2.3.1. 测试应用服务器通路
将当前 IPC 画面截屏以 multipart/form-data 形式的文件上传至应用服务器，属性名为“data”，
文件名格式为：SN + 时间戳 + "_test_snapshot" + ".jpg"
{
"request_id":"xxx",
"service_id":"8210",
"payload":{}
}
返回应答示例：
{
"code":0,
"message":"",
"status":""
}
4.2.3.2. OTA 升级
1. 服务 Pub OTA 升级 Topic；
a) 包含 OTA 升级信息，该指令的 artifact 字段里给出 ota 升级包的名称，uri
等；
2. 摄像机 Sub OTA 升级 Topic；
a) 收到 OTA 升级信息之后，开始进行 OTA 升级并陆续上报升级的状态
{
"request_id":"xxx",
"payload":{
"artifact": {
"source": {
43
"uri": "http://xxxx"
}
},
"version": "xxxxx"
}
}
返回应答示例：
{
"code":0,
"message":"",
"status":""
}
4.2.3.3. 设备截图
将当前 IPC 画面截屏以 multipart/form-data 形式的文件上传至 instructions 中 callback 字
段指定 url，属性名为“data”，文件名格式为：时间戳 + request_id + ".jpg"
注意 url 中末尾的字符
{
"request_id":"xxx",
"payload":{"instructions": "{\"callback\"：\"http://xx/:thing_id\"}"}
} //图片上传地址中:thing_id 固定，由 IPC 封装为当前 IPC 唯一标志
返回应答示例
{
"code":0,
"message":"",
"status":""
}
4.2.3.4. 历史数据上报
向应用服务器上报历史数据，仅用于 sd 卡设备
{
"request_id":"xxx",
44
"payload":{
"instructions": "{\"start_time\":xxx, \"end_time\":xxx, \"type\":xx}"
}
}
参数说明：
start_time, end_time: 起始时间、结束时间，表示为 1970 年 1 月 1 日开始的秒数
type: 1、抓拍数据 2、识别数据 4、过线事件 8、客流统计结果
应答示例：
{
"code":0,
"message":"",
"status":""
}
4.2.3.5. 设备重启
{
"request_id":"xxx",
"payload":{}
}
应答示例：
{
"code":0,
"message":"",
"status":""
}
4.2.3.6. 设备日志上传
{
"request_id":"xxx",
45
"payload":{
"instructions": "{\"start_time\":xxx, \"end_time\":xxx, \"type\":xx}"
}
}
参数说明：
start_time, end_time: 起始时间、结束时间，表示为 1970 年 1 月 1 日开始的秒数
type: 1、IPC 系统日志 2、运行时诊断日志
{
"code":0,
"message":"",
"status":""
}
4.2.3.7. 底库管理相关
IPC 通过 Pub/Sub 相关 Topic 去接收客户 SaaS 下发得各种与底库相关得命令，相关得 Topic
遵从服务相关定义。
底库操作参数说明：
底库参数定义备注
libid
底库 id 唯一标志；
仅支持大小写字母，数字，下划线，短划
线；
有效长度 1-45
name
底库名称仅支持中文，大小写字母，数字，下划线，
短划线；
有效长度 1-16
46
threshold
底库阈值整数，有效范围 0-100
图片参数定义备注
uid
用户 id 唯一标志；
仅支持大小写字母，数字，下划线，短划
线；
有效长度 1-45
name
图片名称支持所有可输入字符；
有效长度 1-32
extra
自定义字段支持大小写字母，数字，下划线，短划线，
中文
有效长度 0-32
base64
图片编码支持 jpg 格式；
图片大小不超过 100kb；
像素不小于 100*100，不大于 1080*1920
4.2.3.7.1. 创建底库
{
"request_id":"xxx",
"payload":{"libid": "xxxx", "name": "xxxx", "threshold" : xx}
}
47
4.2.3.7.2. 删除底库
{
"request_id":"xxx",
"payload":{"libid": "xxxx"}
}
4.2.3.7.3. 全量更新底库
{
"request_id":"xxx",
"payload":{"libid": "xxxx", "name": "xxxx", "threshold" : xx}
}
4.2.3.7.4. 增改图片
内部流程为：添加图片（包括 uid，name，base64）、添加 extra 信息、提取特征；
若添加 extra 信息失败，则不继续提取特征，并将已入库的图片（uid，name，base64）
删除。
{
"request_id":"xxx",
"payload":{
"libid": "xxxxxxx",
"user_info":{
"uid": "xxxx",
"name": "xxxx",
"base64":["xxxx"],
"img_url": "xxxx",
"extra": ["xxx","xxx"]
}
48
}
}
4.2.3.7.5. 删除图片
{
"request_id":"xxx",
"payload":{"libid": "xxxxxxx","uid": "xxxx"}
}
4.2.3.7.6. 删除底库所有图片
说明：仅删除 IPC 上图片，保留用户其他信息，如特征，uid，name 等
{
"request_id":"xxx",
"payload":{"libid": "xxxxxxx"}
}
4.2.3.7.7. 查询用户信息
{
"request_id":"xxx",
"payload":{"libid": "xxxxxxx","uid": "xxxx"}
}
4.2.3.7.8. 查询所有底库信息
{
"request_id":"xxx",
"payload":{}
49
}
4.2.3.7.9. 批量添图
采用与 OTA 升级类似的方式通过 url 接收批量图片。该接口只能接收 zip 格式文件，且图片
文件应放在 zip 文件的第一级目录下，图片命名与 uid 一致。单次批量上传最多支持 100 幅图。
在收到指令开始执行后，会上报添加图片进度。最后上报指令最终结果为错误码列表。错误码列
表如下：
success 0
uid 或 name 无效 1
附加信息无效 2
查询 ID 失败 3
删除原 uid 失败 4
图片文件无效 5
添加图片失败 6
添加 extra 信息失败 7
抽取特征失败 8
查询特征状态失败 9
其他错误 10
{
"request_id":"xxx",
"payload":{
"libid":"repo",
"user_info":{
"uid_list": ["11","22","33"],
"name_list": ["11","22","33"],
"img_url": "http://10.64.33.40:17901/static/test.zip",
"extra_list":[["xxxxxx", "xxxxx"], ["xxxxx"],["xxxxx"]]
}
}
}
50
4.2.3.7.10. 导入指定用户信息
{
"request_id":"xxx",
"payload":{
"libid":"repo",
"user_info":[
{
"uid": "001",
"name":"string",
"ext1": "string",
"ext2": "string",
"ext3": "string",
"ext4": "string",
"ext5": "string",
"status": 0,
"feature": "string",
"img_url":"string", //S3 address
"url": "string",
"feature_attr":"string",
"model_version":"string"
},
{
"uid": "002",
"name":"string",
"ext1": "string",
"ext2": "string",
"ext3": "string",
"ext4": "string",
"ext5": "string",
"status": 0,
"url": "string",
},
{
"uid": "003",
"name":"string",
"ext1": "string",
"ext2": "string",
51
"ext3": "string",
"ext4": "string",
"ext5": "string",
"status": 0,
"url": "string",
},
{
"uid": "004",
"name":"string",
"ext1": "string",
"ext2": "string",
"ext3": "string",
"ext4": "string",
"ext5": "string",
"status": 0,
"url": "string",
}
]
}
}
导入结果：(错误码参考 4.2.3.7.9 批量添图)

{
"request_id":"xxx",
"code": 0,
"payload":[
{
"uid": "001",
"code": 0,
},
{
"uid": "002",
"code": 5,
},
{
"uid": "003",
52
"code": 0,
},
{
"uid": "004",
"code": 0,
}
],
"timestamp":"12345467"
}
4.2.3.7.11. 导出指定用户信息
{
"request_id":"xxx",
"payload":"{"libid": "xxxxxxx"，”uids”: [”001”,”002”,”003”,”004”]"}"
}
导出 uids 数组中对应的所有信息如下：
{
"request_id": "xxx",
"code": 0,
"payload":[
{
"uid": "001",
"status": 0,
"url": "string",
},
{"uid": "002",
"status": 0,
"url": "string",
},
{"uid": "003",
"status": 0,
53
"url": "string",
},
{"uid": "004",
"status": 0,
"url": "string",
}
],
"timestamp":"12345467"
}
注意：
1. 一次调用最多支持导出 50 人信息（其中不包括底库图片，该信息依赖客户管理）
2. 导出的信息需要用户全部保存下来, 在导入到其它 IPC 时，需要用到
54

智能 Ipc Openapi参考手册 - v0.95

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

智能 Ipc Openapi参考手册 - v0.95

Uploaded by

Copyright:

Available Formats

智能 IPC OpenAPI 参考手册

3.2.1. 身份信息配置 ................................................................................................................................................. 6

3.2.2. 数据推送配置 ................................................................................................................................................. 7

3.3. 数据推送 API ............................................................................................................................................................. 7

3.3.1. 请求 API ........................................................................................................................................................... 7

3.3.2. 请求方法 .......................................................................................................................................................... 8

3.3.3. 请求参数 .......................................................................................................................................................... 8

3.3.4. 参数说明 .......................................................................................................................................................... 8

3.3.5. 响应参数 ........................................................................................................................................................ 11

3.3.6. 报文示例 ........................................................................................................................................................ 12

4.1. 设备管理服务器配置 ............................................................................................................................................ 20

4.2.1. Topic 以及相关 payload 定义.................................................................................................................. 22

4.2.2. 属性定义 ........................................................................................................................................................ 27

4.2.3. 服务指令 ........................................................................................................................................................ 42

IPC 基于 MQTT 协议的封装来提供相关管理功能，数据推送部分，IPC 通过 HTTP 协议将

设备管理部分描述 IPC 与设备管理服务器对接所需的协议。IPC 侧使用 DM 进程，通

过基于 MQTT 封装的 SDK 来与设备管理服务器进行交互，主要完成对设备管理服务器向

IPC 下发命令的响应。命令主要包括：智能参数设置及获取，远程 OTA 升级，远程重启，

应用数据推送部分描述如何配置摄像机，把智能数据推送到客户 SaaS 的指定接收地址。

智能摄像机将人脸抓拍，人脸识别，客流统计等数据通过 JSON 格式推送，数据类型包含但

根据获得的应用服务器的地址和端口，摄像机将分析的智能数据通过 HTTP 协议推送到运

行有 HTTP Server 的应用服务器，应用服务器接收 HTTP 数据并做进一步的处理。

根据获得的设备管理服务器的地址和端口，摄像机通过 MQTT 协议与设备管理服务器通讯，

2. 点击设备 IP 右侧配置按钮 ，进入配置页面。

3.3. 数据推送 API

数据推送服务需要用户通过 IPC 的配置工具配置服务器的 URL 后使用，参见 3.2 数据推送

接收数据的 URL 由上图“数据推送服务器后缀 url”指定的配置。

注意：有限支持 HTTPS 推送，具体牵涉到证书等交互，需另外协商。

2、 以下时区等信息，在 WebUI 上修改后，需要重启 IPC，相应的信息才能在数据推送中得

"TimeStamp":1558685462, //开始统计时间,相对于 UTC1970 年 1 月 1 日 0 时 0

1. 客户 SaaS 通过 MQTT Broker 把需要下发的控制信息通过相应 Topic Pub 出来；

2. 摄像机通过 Sub 接收从客户 SaaS 下发的各种指令和信息

3. 摄像机执行指控信息后，通过相应的 Topic 上报应答；

在 IPC 的配置工具打开设备设置页面，选择快速接入页进行接入 token 配置：

注意：这里主要是让 IPC 能够被服务器发现并注册（注册信息需要客户来指定，比如，

3.2.1 身份信息设置 中提到的），然后获得需要配置的各种服务信息。

目前使用 iot-sdk 进行设备管理的相关对接及命令和属性的通信。iot-sdk 提供

mqtt 相关服务，定义了下述接入流程和服务、属性接口的 Topic 以及数据格式。

使用 iot-sdk，接入 mqtt broker 的逻辑如下：

接入 token 为 base64 编码，解码后的格式如下：

sdk 内部解码该 token 为如上格式，根据解码后的参数请求对应 url，请求返回体格式

⚫ thing_id 是 IPC 与 broker 通信的唯一标志

以下描述具体的 IPC 和客户 SaaS 之间的关键交互 Topic 以及 Payload 定义，IPC 通过以

下 Topic 的 Pub/Sub 来完成相互的交互。

4.2.1. Topic 以及相关 payload 定义

属性是用来对 IPC 的相关配置与服务端进行上报及设置。

hobot/{ClientId}/property/report IPC 发布 属性周期上报，30s

"timestamp": 1568016834606 //精确到毫秒

服务是用来从服务端主动要求 IPC 进行一些操作，如重启、升级、本地建库等，具体见服务

hobot/{ClientId}/service/async/request IPC 订阅 异步服务下发

hobot/{ClientId}/service/async/response IPC 发布 异步服务应答

hobot/{ClientId}/service/sync/request IPC 订阅 同步服务下发

（重启，升级后的应答通过该 topic 发布）

⚫ Topic：$hobot/${ClientId}/service/async/response //IPC 发布（Saas

• $ClientId 是每个设备的唯一标识，与 4.1 设备管理服务器配置中 thing_id 一致

事件用来提供给 IPC 主动上报相关的内容

hobot/{ClientId}/event/post IPC 发布 IPC 上报事件，暂未使用

⚫ Topic：$hobot/${ClientId}/event/post //IPC 发布（Saas 订阅）

以下各个操作的内容与 4.3.2.3 属性相关 的格式相对应

属性定义用来机型 IPC 参数配置/查询，范围包括智能人脸参数、客流参数。IPC 通过

Pub/Sub 相应的 Topic 获取到参数配置/查询任务，执行相应的操作，并告知设备管理服务

参数名 值类型 有效范围 含义

参数名 值类型 有效范围 含义

2. 点击设备 IP 右侧配置按钮，进入配置页面。

2、以下时区等信息，在 WebUI 上修改后，需要重启 IPC，相应的信息才能在数据推送中得

3.2.1 身份信息设置中提到的），然后获得需要配置的各种服务信息。

hobot/{ClientId}/property/report IPC 发布属性周期上报，30s

hobot/{ClientId}/service/async/request IPC 订阅异步服务下发

hobot/{ClientId}/service/async/response IPC 发布异步服务应答

hobot/{ClientId}/service/sync/request IPC 订阅同步服务下发

以下各个操作的内容与 4.3.2.3 属性相关的格式相对应

参数名值类型有效范围含义

参数名值类型有效范围含义

参数名值类型有效范围含义

参数名值类型有效范围含义

参数名值类型有效范围含义

参数名值类型有效范围含义

参数名值类型有效范围含义

参数名值类型有效范围含义

参数名值类型有效范围含义

参数名值类型有效范围含义

参数名值类型有效范围含义

参数名值类型有效范围含义

参数名值类型有效范围含义

参数名值类型有效范围含义

参数名值类型有效范围含义

参数名值类型有效范围含义

参数名值类型有效范围含义

frame_rate int 1-25 帧率单位 fps

is_variable_rate int 0-1 主码流码率类型

参数名值类型有效范围含义

device_name String 0~127 位 ASCII 可打印字符设备名称

levelone_id String 0~127 位 ASCII 可打印字符一级 ID，客户自定义的字段，该值会在数据推送时使用

levelone _name String 0~127 位 ASCII 可打印字符一级名称，客户自定义的字段，该值会在数据推送时使用

leveltwo_id String 0~127 位 ASCII 可打印字符二级 ID，客户自定义的字段，该值会在数据推送时使用

leveltwo _id String 0~127 位 ASCII 可打印字符二级名称，客户自定义的字段，该值会在数据推送时使用

start_time, end_time: 起始时间、结束时间，表示为 1970 年 1 月 1 日开始的秒数

start_time, end_time: 起始时间、结束时间，表示为 1970 年 1 月 1 日开始的秒数

像素不小于 100100，不大于 10801920

1. 一次调用最多支持导出 50 人信息（其中不包括底库图片，该信息依赖客户管理）