文档

室内安防设备对接边缘服务器接口定义

更新时间:
一键部署

1 方案介绍

室内各传感器的数据都汇总到室内机上,室内机通过小区局域网直连物业管理一体机,即边缘服务器。传感器产生的报警事件由室内机上报到边缘服务器。边缘服务生成物模型事件并同步到物联网平台

image

2 接口说明

室内机对接边缘服务器,访问10070端口。

边缘服务器访问室内机的端口由设备厂商自定义,定义后固定不变。

所有HTTP 报文的首部信息中,不能带有Connection: Keep-Alive字段,可以设置为Connection:Close。

物业管理一体机,以下简称“边缘服务器”。

3 服务接口

3.1 服务检测

调用此接口检查服务是否可用。

URL:http://[边缘服务器IP 或 室内机IP]:[端口]/alarm/ping
Method:GET
Content-Type:application/json

说明

服务启动后开始监听端口数据,当收到ping消息后,立刻回复pong,以表示服务状态正常,否则无消息返回。

请求参数

无。

返回参数

名称

类型

示例值

描述

code

Integer

0

调用成功时,返回0。固定内容。

message

String

pong

调用成功时,返回“pong”。固定内容。

示例

正常返回示例

{
    "code": 0,
    "message": "pong"
}

3.2 建立连接

室内机向边缘服务器发送连接请求。

URL:http://[边缘服务器IP]:[端口]/alarm/connect
Method:POST
Content-Type:application/json

说明

前置条件:

室内机先预置安全密钥(RSA公钥),再进行连接。

建立连接交互流程:

  1. 室内机携带下面的请求参数向边缘服务器发起连接请求。

  2. 边缘服务器校验IP参数是否已经配置,如未配置,拒绝连接请求。设备信息配置需要预先在云端配置好,并部署到边缘。

  3. 如果配置校验通过,边缘服务器返回成功消息给室内机。响应消息中包含一个有效的token。

  4. 边缘服务器向室内机发送“服务检测”ping请求,室内机返回pong消息给边缘服务器,连接建立完成。

  5. 如果室内机没有收到成功消息和token,等待一分钟后,再次发起连接请求。

connect请求里,如果参数encrypted为1,那么参数ciphertext的内容为使用RSA公钥加密的密文。下面是生成密文和发送密文的方法:

  1. 室内机先随机生成一个长度为16字节的AES Secret Key,再使用预置的RSA公钥对AESSecret Key进行加密,把生成的密文发送给边缘服务器。

  2. 边缘服务器使用RSA私钥解密出AES Secret Key并保存,在后续通信中,用它对数据进行加解密。

  3. 连接建立成功后,室内机发送的数据都使用AES Secret Key进行加密,室内机收到的数据也是使用AES Secret Key加密的。

说明:

RSA的加密模式为:ECB;填充模式为:PKCS1Padding。(JAVA为:RSA/ECB/PKCS1Padding)

AES长度128位加密模式为:ECB;填充模式为:PKCS7Padding。(JAVA为:AES/ECB/PKCS5Padding)

限制

调用该接口的每秒请求数(QPS)最大限制为10。

请求参数

名称

类型

是否必选

示例值

描述

version

String

2021-01-01

API版本号,为日期形式:YYYY-MM-DD,最新版本为2021-01-01 。接口可能存在多个版本。

protocol

String

2021-01-01

设备的通信协议的版本号,为日期形式:YYYY-MM-DD,固定值为2021-01-01

边缘服务器发起请求时,使用此参数作为version,即version为2021-01-01

sn

String

123456789

设备的唯一编码。长度为4-32个字符,可以包含英文字母、数字和特殊字符:连字符(-)、下划线(_)、at符号(@)、点号(.)、和英文冒号(:)。

vendor

String

DEV

设备厂商名称。

model

String

DEV-HW-210

设备硬件型号。

time

Integer

1589472000

请求的时间戳。以秒为单位,需要使用UTC时间。

ip

String

192.168.1.128

连接发起方的IPv4地址。

mac

String

00-16-EA-AE-3D-40

连接发起方的MAC地址。

port

int

10000

边缘服务器访问设备服务的端口,如果不提供,填写-1。

keepalive

Integer

30

心跳最大间隔。单位:秒,合法取值范围[10,120]。

encrypted

Integer

1

是否采用数据加密模式。

  • 0:不加密。

  • 1:加密。

ciphertext

String

mrmZ2Amm5TNDjlxA+ssNt23QTcbcQNKxzMc+YDoewHkR1eOT2+fk=

如果encrypted为1,需要传递此参数。先随机生成一个长度为16字节的AES Secret Key,再使用预置的RSA公钥对Secret Key进行加密,再把密文进行Base64编码得到的结果就是ciphertext的内容。

返回参数

名称

类型

示例值

描述

code

Integer

0

调用成功时,返回0。失败时,返回的错误码。详见错误码表。

message

String

success

调用结果描述。

data

JSONObject

调用成功时,返回内容定义如下。

名称

类型

示例值

描述

token

String

6f2a-***-1-128

连接成功后,由接收连接的server端颁发的连接成功标识,代表一个有效连接,最大长度位64字节。在后续client的请求中需要携带,如“心跳保活”。

示例

请求示例

{
    "version": "2021-01-01",
    "protocol": "2021-01-01",
    "sn": "123456789",
    "vendor": "DEV",
    "model": "DEV-HW-210",
    "time": 1589472000,
    "ip": "192.168.1.128",
    "mac": "00-16-EA-AE-3D-40",
    "port": 10000,
    "keepalive": 30,
    "encrypted": 1,
    "ciphertext": "hlbtFix0/wrcca8SqUcy+5Q8J76xOM29fp4itQhstZhAQRRi+RITQPupSSnrZCXAGzPHYUdbKWijcMa0FGwAoPqw4m0Mot1HT3qKxMBHTvSGuOEayozZJMj18FL0tceGZ2V5BxkethBDsRTfn2qaDEMCaS9+go0dqj1aP0IjrYg="
}

正常返回示例

{
    "code": 0,
    "message": "success",
    "data":{
        "token": "6f2ae65e-d7f3-11ea-9a16-6c96cfdfd355-192-168-1-128"
    }
}

3.3 心跳保活

室内机向边缘服务器定期发送心跳消息,以确保消息通道的连通性,维持设备的在线状态。

URL:http://[边缘服务器IP]:[端口]/alarm/keepalive
Method:POST
Content-Type:application/json

说明

建立连接后,服务器会向客户端颁发一个token,心跳消息中需要携带此token。当发送心跳时,返回token无效,那么需要重新建立连接,获取有效token。

成功时,返回的消息体中包含一个时间参数,可以用来同步双方时间。

限制

调用该接口的每秒请求数(QPS)最大限制为100。

请求参数

名称

类型

是否必选

示例值

描述

version

String

2021-01-01

API版本号,为日期形式:YYYY-MM-DD,最新版本为2021-01-01 。接口可能存在多个版本。

token

String

6f2a-***-1-128

有效连接的标识。

返回参数

名称

类型

示例值

描述

code

Integer

0

调用成功时,返回0。失败时,返回的错误码。详见错误码表。

message

String

success

调用结果描述。

data

JSONObject

调用成功时,返回内容定义如下。

名称

类型

示例值

描述

time

String

1591069176000

响应消息生成的时间,时间戳以毫秒为单位,需要使用UTC时间。

示例

请求示例

{
    "version": "2021-01-01",
    "token": "6f2ae65e-d7f3-11ea-9a16-6c96cfdfd355-192-168-1-128"
}

正常返回示例

{
    "code": 0,
    "message": "success",
    "data":{
        "time": "1591069176000"
    }
}

3.4 上报防区信息和状态

室内机上报主机下的防区信息和防区状态给边缘服务器。

URL:http://[边缘服务器IP]:[端口]/alarm/reportZoneInfo
Method:POST
Content-Type:application/json

说明

每次建立连接后,上报一次防区信息和状态。当防区信息或状态变化时,立即上报实时的防区信息和状态。

限制

调用该接口的每秒请求数(QPS)最大限制为100。

请求参数

名称

类型

是否必选

示例值

描述

version

String

2021-01-01

API版本号,为日期形式:YYYY-MM-DD,最新版本为2021-01-01 。接口可能存在多个版本。

token

String

6f2a-***-128

有效连接标识。

zoneInfo

JSONArray

防区信息。

  • zoneID

String

01

防区的唯一标识。

  • zoneDeviceType

Integer

1

防区下的探测器类型,枚举值见附录。

  • zoneState

Integer

1

防区布防状态,枚举如下:

  • 0:未知

  • 1:撤防

  • 2:布防

加密的

名称

类型

是否必选

示例值

描述

version

String

2021-01-01

API版本号,为日期形式:YYYY-MM-DD,最新版本为2021-01-01 。接口可能存在多个版本。

token

String

6f2a-***-128

有效连接标识。

ciphertext

String

ewogICAgJ2EiJzoiYiIKfQ==

先将zoneInfo对应的内容转换为JSON字符串,再使用AES密钥进行加密,最后把密文Base64编码。

例如:

"zoneInfo":abc,abc就是需要加密的内容。

返回参数

名称

类型

示例值

描述

code

Integer

0

调用成功时,返回0。失败时,返回的错误码。详见错误码表。

message

String

success

调用结果描述。

示例

请求示例

{
    "version":"2021-01-01",
    "token":"6f2ae65e-d7f3-11ea-9a16-6c96cfdfd355-192-168-1-128",
    "zoneInfo":[
        {
            "zoneID":"01",
            "zoneDeviceType":1,
            "zoneState":1
        },
        {
            "zoneID":"02",
            "zoneDeviceType":3,
            "zoneState":2
        }
    ]
}

加密的

{
    "version":"2021-01-01",
    "token":"6f2ae65e-d7f3-11ea-9a16-6c96cfdfd355-192-168-1-128",
    "ciphertext":"ewogICAgJ2EiJzoiYiIKfQ=="
}

正常返回示例

{
    "code": 0,
    "message": "success"
}

3.5 设置防区布防状态

边缘服务器对室内机下的指定防区进行设防或撤防操作。

URL:http://[室内机IP]:[端口]/alarm/setZoneAlertState
Method:POST
Content-Type:application/json

说明

可以对一个或多个防区进行布防或撤防操作。

限制

调用该接口的每秒请求数(QPS)最大限制为100。

请求参数

名称

类型

是否必选

示例值

描述

version

String

2021-01-01

为connect接口传递的protocol参数值。

zoneInfo

JSONArray

防区信息。

  • zoneID

String

01

防区的唯一标识。

  • zoneState

Integer

1

防区状态,枚举如下:

  • 1:撤防

  • 2:布防

  • time

String

1591069176000

设置操作的时间,时间戳以毫秒为单位,需要使用UTC时间。

为了防止重放攻击,室内机需要记录这个时间,如果收到请求的时间参数等于或小于最后记录的时间,则抛弃这个请求。

加密的

名称

类型

是否必选

示例值

描述

version

String

2021-01-01

为connect接口传递的protocol参数值。

ciphertext

String

ewogICAgJ2EiJzoiYiIKfQ==

先将zoneInfo对应的内容转换为JSON字符串,再使用AES密钥进行加密,最后把密文Base64编码。

例如:

"zoneInfo":abc,abc就是需要加密的内容。

返回参数

名称

类型

示例值

描述

code

Integer

0

调用成功时,返回0。失败时,返回的错误码。详见错误码表。

message

String

success

调用结果描述。

示例

请求示例

{
    "version":"2021-01-01",
    "zoneInfo":[
        {
            "zoneID":"01",
            "zoneState":1,
            "time":"1591069176000"
        },
        {
            "zoneID":"02",
            "zoneState":2,
            "time":"1591069176000"
        }
    ]
}

加密的

{
    "version":"2021-01-01",
    "ciphertext":"ewogICAgJ2EiJzoiYiIKfQ=="
}

正常返回示例

{
    "code": 0,
    "message": "success"
}

3.6 防区报警

室内机发送防区设备报警信息给边缘服务器。

URL:http://[边缘服务器IP]:[端口]/alarm/reportAlarm
Method:POST
Content-Type:application/json

说明

当防区设备触发报警时,根据报警触发规则,室内机上报报警信息给边缘服务器。

限制

调用该接口的每秒请求数(QPS)最大限制为100。

请求参数

名称

类型

是否必选

示例值

描述

version

String

2021-01-01

API版本号,为日期形式:YYYY-MM-DD,最新版本为2021-01-01 。接口可能存在多个版本。

token

String

6f2a-***-128

有效连接标识。

alarmInfo

JSONArray

报警信息。

  • zoneID

String

01

防区的唯一标识。

  • alarmTime

String

1591069176000

报警事件发生的历史时间,如果无此参数,表示事件发生在当前时间。

时间戳以毫秒为单位,需要使用UTC时间。

加密的

名称

类型

是否必选

示例值

描述

version

String

2021-01-01

API版本号,为日期形式:YYYY-MM-DD,最新版本为2021-01-01 。接口可能存在多个版本。

token

String

6f2a-***-128

有效连接标识。

ciphertext

String

ewogICAgJ2EiJzoiYiIKfQ==

先将alarmInfo对象转换为JSON字符串,再使用AES密钥进行加密,最后把密文Base64编码。

例如:

"alarmInfo":abc,abc就是需要加密的内容。

返回参数

名称

类型

示例值

描述

code

Integer

0

调用成功时,返回0。失败时,返回的错误码。详见错误码表。

message

String

success

调用结果描述。

示例

请求示例

{
    "version":"2021-01-01",
    "token":"6f2ae65e-d7f3-11ea-9a16-6c96cfdfd355-192-168-1-128",
    "alarmInfo":[
        {
            "zoneID":"01"
        },
        {
            "zoneID":"02",
            "alarmTime":"1591069176000"
        }
    ]
}

加密的

{
    "version":"2021-01-01",
    "token":"6f2ae65e-d7f3-11ea-9a16-6c96cfdfd355-192-168-1-128",
    "ciphertext":"ewogICAgJ2EiJzoiYiIKfQ=="
}

正常返回示例

{
    "code": 0,
    "message": "success"
}

附录

探测器类型

1.SOS紧急按钮
2.红外
3.门磁
4.窗磁
5.瓦斯
6.烟雾
7.水浸
8.震动
9.气压