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，载荷内容为空。
