管控中枢推送接口文档

更新时间：2024-10-21

1. 接口文档发布记录

No	版本号	修改内容简介	修改日期
1	V0.1.0	全文	2024.05.29

2. 前言

凌云平台中【数据】-【推送设置】-【新建推送任务】，进行推送地址配置；
推送地址配置上限为事件类型种类的上限。推送地址不可重复；
在配置推送地址前，贵方需要保证推送地址支持POST和GET两种请求（GET请求无条件返回200即可）；

3. 使用说明

3.1 数据响应

数据推送成功判定标准:

响应内容的 success 字段为 true，具体示例

{
"success": true,

"message": "操作成功",

"traceId": "54254243ffdafew3"
}

超时时间控制:

该接口会严格控制超时时间(响应时间超过 3s 认为超时)，超时后会被标记推送超时，做推送失败处理。

建议接收方收到数据之后进行简单校验后立即返回，异步进行业务处理，防止调用超时后触发重推。

3.2 图片获取

图片内容不通过当前接口推送，而是提供临时下载链接，接收方需自行通过下载链接进行下载。（过期时间: 1小时）

3.3 数据校验

为了确保数据的安全性和完整性，采取了一种方法来防止伪造消息的攻击。这种方法是通过对数据进行加密签名的校验。具体步骤如下：

从 Header 中获取 Vmp-Signature：首先，需要从接收到的消息的 Header 中提取出 Vmp-Signature 字段。这个字段包含了对消息体（Body）的加密签名。
使用公钥解密 Vmp-Signature：接着，使用已知的公钥对 Vmp-Signature 进行解密。解密的结果应该是消息体的 SHA256 散列值。
计算消息体的 SHA256 散列值：将接收到的消息体（Body）进行 SHA256 散列计算，得到一个散列值。
对比散列值：最后，将步骤 2 解密得到的散列值与步骤 3 计算的散列值进行对比。如果这两个散列值一致，那么就验证成功，说明数据是未被篡改的。

通过这样的校验机制，可以有效防止数据在传输过程中被篡改或伪造。

4. 接口定义

接口路径：

HTTP POST {URL 由接入方提供}

Headers：

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json;charset=UTF-8	是
Vmp-Signature		是		加密签名

BODY 参数：

参数名称	类型	是否必须	备注
traceId	string	是	追踪 ID
timestamp	long	是	timestamp，推送触发时的时间毫秒值
pushLogId	string	是	推送唯一标识，用于判断推送是否被重复接收
pushType	string	是	推送类型，决定推送的数据格式:/ HEART_BEAT/ EVENT_LOG/ PERSON_RECORD/ MOTO_RECORD/ NON_MOTO_RECORD
data	array	是	data 的格式跟 pushType 关联
taskName	String	否	任务名称，pushTyp 为 HEART_BEAT 时为空
pushText	String	否	推送文案，任务未填写该字段时为空

data 数组中元素的字段

HEART_BEAT

完整示例:

{
"traceId": "abc123xyz",

"timestamp": "2024-05-29T08:00:00Z",

"pushLogId": "msg987654321",

"data": [],

"pushType": "HEART_BEAT"
}

EVENT_LOG

字段说明:

参数名称	类型	是否必须	备注
messageId	string	是	事件记录 ID，对应平台的eventId
tenantId	string	是	租户 ID
deviceId	string	是	设备 ID
deviceChannel	string	是	设备通道
deviceName	string	是	抓拍设备(设备名称)
deviceChannelName	string	否	抓拍通道(通道名称)，AI 相机抓拍时无该字段
checkTimeDate	integer	是	抓拍时间（格式：int64）
eventTypeId	String	是	事件类型(技能类型)
eventTypeName	String	是	事件类型名称(技能类型名称)
eventDesc	String	是	事件描述
ImagePath	String	是	事件图像（链接短期有效）

完整入参示例:

{
"traceId": "abc123xyz",

"timestamp": "2024-05-29T08:00:00Z",

"pushLogId": "msg987654321",

"data": [

    {

        "messageId": "event001",

        "tenantId": "tenant001",

        "deviceId": "device123",

        "deviceChannel": "channel1",

        "deviceName": "Device Name 1",

        "deviceChannelName": "Channel Name 1",

        "checkTimeDate": 1653814800,

        "eventTypeId": "type001",

        "eventTypeName": "Event Type 1",

        "eventDesc": "Description of event 1",

        "ImagePath": "http://example.com/event1.jpg"

    },

    {

        "messageId": "event002",

        "tenantId": "tenant002",

        "deviceId": "device456",

        "deviceChannel": "channel2",

        "deviceName": "Device Name 2",

        "checkTimeDate": 1653814900,

        "eventTypeId": "type002",

        "eventTypeName": "Event Type 2",

        "eventDesc": "Description of event 2",

        "ImagePath": "http://example.com/event2.jpg"

    }

],

"taskName": "Task 1",

"pushText": "This is a push text example.",

"pushType": "EVENT_LOG"
}

PERSON_RECORD

字段说明:

参数名称	类型	是否必须	备注
messageId	string	是	识别记录 ID，对应平台的 messageId
tenantId	string	是	租户 ID
deviceId	string	是	设备 ID
deviceChannel	string	是	设备通道
deviceName	string	是	设备名称
deviceChannelName	string	否	通道名称，AI 相机抓拍时无该字段
checkTimeDate	integer	是	抓拍时间（格式：int64）
similarity	string	否	相似度(识别失败时无)
name	string	否	姓名(识别失败时无)
personId	string	否	人员编号(识别失败时无)
internalNum	string	否	内部编号(识别失败时无)
identity	integer	是	人员类型(0 未知, 1 成员, 2 访客, 3 黑名单, 4 陌生人)
groupName	array	否	分组名称(识别失败时无)
showAvatarPath	string	否	人脸照片地址
humanBodyPath	string	否	人体照片地址
avatarPath	string	否	底库照片地址

完整入参示例:

{
"traceId": "abc123xyz",

"timestamp": "2024-05-29T08:00:00Z",

"pushLogId": "msg987654321",

"taskName": "记录数据处理任务",

"pushText": "",

"data": [

    {

        "tenantId": "tenant001",

        "deviceId": "device123",

        "deviceChannel": "channel1",

        "deviceName": "Device Name 1",

        "deviceChannelName": "Channel Name 1",

        "checkTimeDate": 1653814800,

        "similarity": 95,

        "name": "John Doe",

        "personId": "person001",

        "internalNum": "internal123",

        "identity": 1,

        "groupName": ["group1", "group2"],

        "showAvatarPath": "http://example.com/face.jpg",

        "humanBodyPath": "http://example.com/body.jpg",

        "avatarPath": "http://example.com/base.jpg",

        "messageId": "msg123456"

    },

    {

        "tenantId": "tenant002",

        "deviceId": "device456",

        "deviceChannel": "channel2",

        "deviceName": "Device Name 2",

        "checkTimeDate": 1653814900,

        "similarity": 90,

        "name": "Jane Smith",

        "personId": "person002",

        "internalNum": "internal456",

        "identity": 2,

        "groupName": ["group3", "group4"],

        "showAvatarPath": "http://example.com/face2.jpg",

        "humanBodyPath": "http://example.com/body2.jpg",

        "avatarPath": "http://example.com/base2.jpg",

        "messageId": "msg654321"

    }

],

"pushType": "PERSON_RECORD"
}

MOTO_RECORD

字段说明:

参数名称	类型	是否必须	备注
messageId	string	是	识别记录 ID，对应平台的messageId
tenantId	string	是	租户 ID
deviceId	string	是	设备 ID
deviceChannel	string	是	设备通道
deviceName	string	是	设备名称
deviceChannelName	string	否	通道名称，AI 相机抓拍时无该字段
checkTimeDate	integer	是	抓拍时间（格式：int64）
carLicense	string	是	车牌号
groupName	array	是	分组名称
ImagePath	String	是	机动车照片（链接短期有效）

完整入参示例:

{
"traceId": "abc123xyz",

"timestamp": "2024-05-29T08:00:00Z",

"pushLogId": "msg987654321",

"data": [

    {

        "messageId": "moto001",

        "tenantId": "tenant001",

        "deviceId": "device123",

        "deviceChannel": "channel1",

        "deviceName": "Device Name 1",

        "deviceChannelName": "Channel Name 1",

        "checkTimeDate": 1653814800,

        "carId": "car123",

        "carLicense": "ABC123",

        "groupName": ["Group1", "Group2"],

        "ImagePath": "http://example.com/moto1.jpg"

    },

    {

        "messageId": "moto002",

        "tenantId": "tenant002",

        "deviceId": "device456",

        "deviceChannel": "channel2",

        "deviceName": "Device Name 2",

        "checkTimeDate": 1653814900,

        "carId": "car456",

        "carLicense": "XYZ789",

        "groupName": ["Group3"],

        "ImagePath": "http://example.com/moto2.jpg"

    }

],

"taskName": "Task 1",

"pushText": "This is a push text example.",

"pushType": "MOTO_RECORD"
}

NON_MOTO_RECORD

字段说明:

参数名称	类型	是否必须	备注
messageId	string	是	识别记录 ID，对应平台的messageId
tenantId	string	是	租户 ID
deviceId	string	是	设备 ID
deviceChannel	string	是	设备通道
deviceName	string	是	设备名称
deviceChannelName	string	否	通道名称，AI 相机抓拍时无该字段
checkTimeDate	integer	是	抓拍时间（格式：int64）
ImagePath	String	是	非机动车照片（链接短期有效）

完整入参示例:

{
"traceId": "abc123xyz",

"timestamp": "2024-05-29T08:00:00Z",

"pushLogId": "msg987654321",

"data": [

    {

        "messageId": "nonmoto001",

        "tenantId": "tenant001",

        "deviceId": "device123",

        "deviceChannel": "channel1",

        "deviceName": "Device Name 1",

        "deviceChannelName": "Channel Name 1",

        "checkTimeDate": 1653814800,

        "ImagePath": "http://example.com/nonmoto1.jpg"

    },

    {

        "messageId": "nonmoto002",

        "tenantId": "tenant002",

        "deviceId": "device456",

        "deviceChannel": "channel2",

        "deviceName": "Device Name 2",

        "checkTimeDate": 1653814900,

        "ImagePath": "http://example.com/nonmoto2.jpg"

    }

],

"taskName": "Task 1",

"pushText": "This is a push text example.",

"pushType": "NON_MOTO_RECORD"
}

响应数据：

字段说明:

参数名称	类型	是否必须	备注
success	boolean	是	业务数据处理状态
message	string	否	接收方自定义响应，可以为 null
traceId	string	否	日志最终 id，用于配合接收方排查问题，建议跟入参的 traceId 一致

示例:

{
"success": true,

"message": "操作成功",

"traceId": "54254243ffdafew3"
}

枚举说明

identity 枚举字段说明：

值	含义
0	未定义
1	成员
2	访客
3	黑名单
4	陌生人
5	非活体
6	其他

应用推送接口文档

权限说明