IPC设备产生的实时消息客户端可通过两种方式获得:一是用户通过订阅相关事件并给出回调地址,IPC产生相关消息时会向对应回调地址发送一个POST消息; 二是用户可通过与IPC建立长连接来传递 。
1. 消息推送
消息推送是客户端向IPC订阅相关的消息事件,当IPC产生消息事件是,会像订阅的回调地址发送一条http post消息,通知客户端,其实现的功能与消息通道一节一致。
1. 1 签名规则
与签名规则一节一致。
1.2 订阅管理
1.2.1 订阅消息
描述
订阅消息接口用于向IPC设备端订阅相关的消息,一旦订阅了消息,当设备端产生了相关消息的时候,便会向订阅时传入的回调接口发送一个HTTP POST消息,从而达到通知订阅者的目的。
请求地址
https://192.168.0.1/openapi/hook/add,192.168.0.1需要替换成实际的IPC地址。
请求参数
这里只列出接口的私有参数,公共参数见公共参数一节描述。
参数名称 | 类型 | 描述 | 是否必须 |
event_list | array[string] | 事件类型,可以是[“face_recog_event”,”dynamic_detect_event”]或者其中一个,其中” face_recog_event “仅FM020支持 | Y |
http_callback | string | 回调含函数地址,当IPC产生相关消息时,会向该地址发送一个http post消息 | Y |
响应参数
字段名称 | 类型 | 描述 |
code | int | 返回码,表示操作的结果; 本接口返回码有0、1、2、5、310、311,见错误码的描述 |
请求示例
POST openapi/hook/add HTTP/1.1 Host: 192.168.0.1 Content-Type: application/x-www-form-urlencoded app_id=mdk923idkf&random=289192×tamp=15930292837&sign=IDKNFLK392038KDS932K& event_list=[“face_recog_event”,”dynamic_detect_event”]&http_callback=http://192.168.0.100/msg |
返回示例
{ ‘code’: 0, } |
1.2.2 取消已订阅消息
描述
用于取消已经向IPC设备端订阅过的消息,取消订阅后,当设备端产生相关消息时,便不会向对应的回调地址发送HTTP POST消息。
请求地址
https://192.168.0.1/openapi/hook/delete,192.168.0.1需要替换成实际的IPC地址。
请求参数
这里只列出接口的私有参数,公共参数见公共参数一节描述。
参数名称 | 类型 | 描述 | 是否必须 |
event_list | array[string] | 事件类型,可以是[“face_recog_event”,”dynamic_detect_event”]或者其中一个,其中” face_recog_event “仅FM020支持 | Y |
http_callback | string | 之前订阅的回调函数地址,指定此参数,设备端只取消此地址的订阅,不指定此参数,设备端将取消所有地址的订阅 | N |
响应参数
字段名称 | 类型 | 描述 |
code | int | 返回码,表示操作的结果; 本接口返回码有0、1、2、5、310,见错误码的描述 |
请求示例
POST openapi/hook/delete HTTP/1.1 Host: 192.168.0.1 Content-Type: application/x-www-form-urlencoded app_id=mdk923idkf&random=289192×tamp=15930292837&sign=IDKNFLK392038KDS932K& event_list=[“dynamic_detect_event”,”face_recog_event”]&http_callback=http://192.168.0.100/msg |
返回示例
{ ‘code’: 0, } |
1.2.3 查询所有已订阅消息
描述
用于查询IPC设备端所有订阅的消息,当设备端产生相关消息时,会向对应的回调地址发送HTTP POST消息。
请求地址
https://192.168.0.1/openapi/hook/query,192.168.0.1需要替换成实际的IPC地址。
请求参数
此接口不需要私有参数,公共参数见公共参数一节描述。
响应参数
字段名称 | 类型 | 描述 |
code | int | 返回码,表示操作的结果; 本接口返回码有0、1、5,见错误码的描述 |
sub_event | array | 订阅列表 |
event | string | 订阅的事件类型 |
http_callback | array | 订阅该事件的所有回调地址列表 |
num | string | 订阅事件的个数 |
请求示例
POST openapi/hook/query HTTP/1.1 Host: 192.168.0.1 Content-Type: application/x-www-form-urlencoded app_id=mdk923idkf&random=289192×tamp=15930292837&sign=IDKNFLK392038KDS932K& |
返回示例
{ “data”: { “num”: 2, “sub_event”: [ { “event”: “face_recog_event”, “http_callback”: [ “10.10.61.206:8000” ] }, { “event”: “dynamic_detect_event”, “http_callback”: [ “10.10.61.206:8000” ] } ] }, “code”: 0 } |
1.3 推送消息
IPC通过HTTP POST的方式推送消息,会提交form表单,Content-Type为multipart/form-data,消息内容封装在payload中。
动态侦测消息
动态侦测消息如下:
POST / HTTP/1.1 Host: 10.10.61.206:8000 User-Agent: libcurl/7.52.1 OpenSSL/1.0.2p Accept: */* Content-Length: 826 Expect: 100-continue Content-Type: multipart/form-data; boundary=————————c83c36cd4ee4082f ————————–c83c36cd4ee4082f Content-Disposition: form-data; name=”app_id” 123 ————————–c83c36cd4ee4082f Content-Disposition: form-data; name=”random” 692777 ————————–c83c36cd4ee4082f Content-Disposition: form-data; name=”timestamp” 1579158766 ————————–c83c36cd4ee4082f Content-Disposition: form-data; name=”sign” 372F669601E8347737744FFC88B74665 ————————–c83c36cd4ee4082f Content-Disposition: form-data; name=”payload” {“event_id”:1,”detect_type”:2,”video_url”:”https://10.10.63.19/mnt/sd-card/sunmi_video/video_detect/1579158761.flv?auth_key=1579158765-d701e761fecf0df84853440d4dbc3fe1″,”event_type”:”dynamic_detect_event”,”sn”:”SS101D8BS00080″,”report_time”:1579158765} ————————–c83c36cd4ee4082f– |
消息有效载荷在payload中,各字段内容如下:
参数名称 | 类型 | 描述 |
event_id | long | 事件ID |
event_type | string | 事件类型 |
report_time | long | 事件发生的时间戳 |
detect_type | int | 动态侦测检测到的类型,1表示画面变化,2表示声音变化,3表示既有画面变化,也有声音变化 |
video_url | string | 视频下载路径 |
sn | string | 发出此消息的IPC序列号 |
人脸识别消息
人脸识别消息如下:
POST / HTTP/1.1 Host: 192.168.103.173:8010 User-Agent: libcurl/7.52.1 OpenSSL/1.0.2p Accept: */* Content-Length: 906 Content-Type: multipart/form-data; boundary=————————7faeecefd4fb5aaf ————————–7faeecefd4fb5aaf Content-Disposition: form-data; name=”app_id” KJQJ89V956U9O9UI ————————–7faeecefd4fb5aaf Content-Disposition: form-data; name=”random” 956429 ————————–7faeecefd4fb5aaf Content-Disposition: form-data; name=”timestamp” 1597894809 ————————–7faeecefd4fb5aaf Content-Disposition: form-data; name=”sign” 004B3CD3FACB562E06CC04A0935410A5 ————————–7faeecefd4fb5aaf Content-Disposition: form-data; name=”payload” {“event_id”:2,”faceid”:”358526″,”group_name”:”db_0″,”age”:0,”age_range”:5,”gender”:0,”arrive_times”:3,”pic_url”:”https://192.168.103.117/mnt/sd-card/sunmi_image/snap/1597894624456_7.jpg?auth_key=1597894624-f88c2f9a6e69834430648c2f4931ffae”,”event_type”:”face_recog_event”,”sn”:”FS101D8BS00080″,”report_time”:1597894809} ————————–7faeecefd4fb5aaf– |
消息有效载荷在payload中,各字段内容如下:
参数名称 | 类型 | 描述 |
event_id | long | 事件ID |
event_type | string | 事件类型 |
sn | string | 发出此消息的IPC序列号 |
report_time | long | 事件发生的时间戳 |
faceid | string | 人脸ID |
group_name | string | 所在分组名称 |
age | int | 年龄,为空则表示用户没有设置过此人脸的年龄 |
age_range | int | 所属年龄段,1表示1~6岁,2表示7~12岁,3表示13~18岁,4表示19~28岁,5表示29~35岁,6表示36~45岁,7表示45~55岁,8表示55岁~100 |
gender | int | 性别,0表示未知,1表示男性,2表示女性 |
arrive_times | int | 到达过的总次数 |
pic_url | string | 人脸照片下载地址 |
item1 | string | 自定义属性1,用户添加过才会返回 |
item2 | string | 自定义属性2,用户添加过才会返回 |
item3 | string | 自定义属性3,用户添加过才会返回 |
item4 | string | 自定义属性4,用户添加过才会返回 |
item5 | string | 自定义属性5,用户添加过才会返回 |
2. 消息通道
消息通道是客户端与IPC设备维持的一条长连接,用于IPC设备主动向客户端实时推送消息事件。其实现的功能与消息推送一节一致。
2.1. 消息协议
通信协议端口
通信协议采用TCP连接,同时为了保证数据的安全性,采用SSL套接字,是C/S模式,IPC设备是Server。Server端的端口暂时固定为10021。
通信格式
本节简述报文格式,主要由头部、载荷和CRC校验和构成;如下图所示。
- 头部
Flag
为协议标识符,暂定为0xFF3E3EFF。
Version
本协议的版本号,目前为0x01,高版本兼容低版本。
Packet Type
包类型,目前支持如下:
类型 | 值 | 方向 | 描述 |
保留 | 0 | 禁止 | 保留 |
CONNECT | 1 | 客户端到服务端 | 客户端发起建立消息通道的报文 |
CONNACK | 2 | 服务端到客户端 | 连接确认报文,报文内容会标志连接是否合法 |
PINGREQ | 3 | 客户端到服务端 | 心跳请求 |
PINGRESP | 4 | 服务端到客户端 | 心跳响应 |
SUBSCRIBE | 5 | 客户端到服务端 | 客户端订阅消息事件 |
SUBACK | 6 | 服务端到客户端 | 订阅请求确认 |
UNSUBSCRIBE | 7 | 客户端到服务端 | 客户端取消订阅消息事件 |
UNSUBACK | 8 | 服务端到客户端 | 取消订阅请求确认 |
PUBLISH | 9 | 两个方向都可以 | 目前来说只支持服务端到客户端的消息发布 |
PUBACK | 10 | 两个方向都可以 | 发布消息收到确认 |
DISCONNECT | 11 | 客户端到服务端 | 断开连接 |
Length
为载荷长度,范围是0 ~ N,N最大是65535。
- 载荷Payload
载荷就是实际的报文内容,采用json格式。根据Packet Type的不同而不一样。
- CRC校验和
是Payload的CRC校验和,占用4B。
2.2 建立连接
由客户端发起到IPC服务端的连接。
- 发起连接
报头包类型为0x01,报文载荷格式如下,客户端带上一些参数,并用secret key做签名,详见签名规则一节的介绍。服务端会采用同样的规则来检查客户端的连接是否合法。
{ “app_id”:”mdk923idkf”, “timestamp”:”15930292837″, “random”:”289192″, “sign”:”IDKNFLK392038KDS932K”, “keep_alive”:30 } |
keep_alive:心跳包的周期,以秒为单位,有客户端根据实际情况指定心跳周期。
- 响应连接
报头包类型为0x02,报文内容如下。code 为返回码,表示操作的结果。本接口返回码有 0、1、2、3、5、7,见错误码描述。
{ “code”:0 } |
2.3 心跳
客户端根据预定好的心跳周期,周期性地向服务端发送心跳报文,服务端会在3次都没有收到心跳报文后,断开连接。
- 心跳请求
报头类型为0x03,没有载荷。
- 心跳响应
报头类型为0x04,没有载荷。
2.4 订阅消息
由客户端向服务端订阅消息事件。
- 发起订阅(或取消订阅)
报头类型为0x05(或0x07),载荷内容如下:
{ “event_list”:[ “dynamic_detect_event”, “face_recog_event” ] } |
字段解释如下
参数名称 | 类型 | 描述 |
event_list | string | 需要订阅的消息事件列表 |
目前支持事件列表如下
事件类型 | 描述 |
dynamic_detect_event | 动态侦测消息 |
face_recog_event | 人脸识别消息(仅FM020支持) |
- 响应订阅(或响应取消订阅)
报头类型为0x06(或0x07),载荷内容如下。code 为返回码,表示操作的结果。本接口返回码有 0、1、2、3、5、7、310、311,见错误码描述。
{ “code”:0 } |
2.5 发布消息
- 发布消息
由IPC服务端推送消息到客户端,报头类型为0x09,内容因事件类型不同而有所不同。
- 动态侦测消息
报文载荷内容如下:
{ “event_id”:1, “event_type”:”dynamic_detect_event”, “sn”:”FS101D8BS00106″, “report_time”:15930292837, “detect_type”:1, “video_url”:”https://192.168.0.1/mnt/sd-card/sunmi_video/video_detect/1565535983.flv?auth_key=1564129415215f61f3c5f552c5bf8f43ccef5c66a9″ } |
各字段如下:
参数名称 | 类型 | 描述 |
event_id | long | 事件ID |
event_type | string | 事件类型 |
report_time | long | 事件发生的时间戳 |
detect_type | int | 动态侦测检测到的类型,1表示画面变化,2表示声音变化,3表示既有画面变化,也有声音变化 |
video_url | string | 视频下载路径 |
sn | string | 发出此消息的IPC序列号 |
- 人脸识别消息
报文内容如下:
{ “event_id”:2, “event_type”:”face_recog_event”, “sn”:”FS101D8BS00106″, “report_time”:15930292837, “group_name”:”vip”, “faceid”:”00000001″, “age”:10, “gender”:2, “arrive_times”:4, “pic_url”:”https://192.168.103.117/mnt/sd-card/sunmi_image/snap/1597894545153_5.jpg?auth_key=1597894545-acb4f1ba497caeef146de1d4a0e926d9″, “vip_level”:”1″, //自定义属性,用户定义了才会有,这里是举例 “hobby”:”tennis”, //自定义属性 “weight”:”60″, //自定义属性 “height”:”180″ //自定义属性 } |
各字段描述如下
参数名称 | 类型 | 描述 |
event_id | long | 事件ID |
event_type | string | 事件类型 |
sn | string | 发出此消息的IPC序列号 |
report_time | long | 事件发生的时间戳 |
faceid | string | 人脸ID |
group_name | string | 所在分组名称 |
age | int | 年龄,为空则表示用户没有设置过此人脸的年龄 |
age_range | int | 所属年龄段,1表示1~6岁,2表示7~12岁,3表示13~18岁,4表示19~28岁, 5表示29~35岁,6表示36~45岁,7表示45~55岁,8表示55岁~100 |
gender | int | 性别,0表示未知,1表示男性,2表示女性 |
arrive_times | int | 到达过的总次数 |
pic_url | string | 人脸照片下载地址 |
item1 | string | 自定义属性1,用户添加过才会返回 |
item2 | string | 自定义属性2,用户添加过才会返回 |
item3 | string | 自定义属性3,用户添加过才会返回 |
item4 | string | 自定义属性4,用户添加过才会返回 |
item5 | string | 自定义属性5,用户添加过才会返回 |
- 发布消息确认
如果订阅者收到此消息,则返回确认。报头类型为0x0a,内容如下。
{ “event_id”:1 } |
报文字段描述如下:
参数名称 | 类型 | 描述 |
event_id | long | 正常接收的消息ID |
2.6 断开连接
报头类型为0x11,载荷内容为空。