接口列表

本节包含设备消息通道服务相关接口等。

开通消息订阅有如下注意事项:
1.消息订阅是企业版服务,个人版无法开通
2.开通消息订阅的账号被标识为企业账户,将无法登录萤石云视频与萤石工作室
3.设备消息全部走消息管道后在消息列表接口中将无法获取
4.获取到的消息需要用户自己保存到服务器,再由用户自己实现管理分发
5.请仔细阅读上诉注意事项

点击此处 下载SDK

接口列表如下:

序号 接口功能 描述
1 创建消费者 创建消费者
2 消费者获取消息 消费者获取消息
3 消费者提交偏移量 消费者提交偏移量
  • 公共返回码:
code msg 备注
200 操作成功
10001 参数错误
10002 accessToken过期或异常
10004 用户不存在
10005 appKey异常
10013 无权限调用 请升级企业版
10029 接口调用太频繁
49999 操作异常 接口调用异常
50000 服务器异常
70101 consumer不存在 请重新获取consumerId
70103 提交offset失败
70105 group数量已达上限, 每个租户最多使用 5 个消费组名 group1-5
70106 consumerId错误, 请使用返回的正确的consumeId
70107 读取消息出现异常
70108 缓存出现异常
70109 消费者没有订阅任何topic 需申请开通后,才可以使用
70110 参数不合法
70111 consumer已存在,请勿重复创建
70112 consumer 创建失败
70117 consume数量超出上限
70120 超时回滚,消息已重置到最近一次commit的位置 消费超时,需要重新消费

创建消费者

  • 接口功能 该接口用于在消费组中创建消费者,每个租户对应一个消息Topic,与消息通道建立连接。

租户:使用消息订阅的用户。消息通道服务建议使用单实例单线程消费的方式。如果考虑采用分布式,建议使用规则如下:

  1. 创建consumer、订阅及提交都必须在一个线程中;
  2. 单个消费组consumer创建数量存在上限,达到上限后consumer创建将失败;
  3. 单个消费组目前只有一个consumer可以订阅到消息。
  • 请求地址

    https://open.ys7.com/api/lapp/mq/v1/consumer/{consumerName}

  • 请求方式

    POST

  • 子账户token请求所需最小权限

  • 请求参数
参数名 类型 描述 是否必选
accessToken String 授权过程获取的access_token Y

注:consumerName表示租户组名,名称固定为group1至group5,传入其他参数报错

  • HTTP请求报文
POST /api/lapp/mq/v1/consumer/group1  HTTP/ 1.1
Host: open.ys7.com
Content-Type: application/x-www-form-urlencoded

accessToken=at.dunwhxt2azk02hcn7phqygsybbw0wv6p
  • 返回数据
{
    "code": "200",
    "msg": "操作成功",
    "data": {
        "consumerId": "fab41dc1ea1043e3ad7285c96df05517"
    }
}
  • 返回字段
字段名 类型 描述
consumerId String 消费者在组中唯一标识,5分钟内未使用将自动删除,断开和消息通道的链接
  • 返回码

参见 公共返回码

消费者获取消息

  • 接口功能

    消息者使用该接口进行消息消费

  1. consumer第一次读取消息时因建立连接耗时可能导致获取不到消息
  2. 消费消息后30秒内需调用提交偏移量接口或调用提交读取模式的接口,若30秒内未提交,当前consumerId即会断开和消息管道的链接,其他的consumerId就可以读取到消息,如果想立即读取到消息,可以通过新建consumerId的方式读取(依然存在1的情况)
  3. 5分钟内消费者没有消费消息,消费者将被删除
  4. 一次请求返回的最大字节数默认为1Mbytes
  • 请求地址

    https://open.ys7.com/api/lapp/mq/v1/consumer/messages

  • 请求方式

    POST

  • 子账户token请求所需最小权限

  • 请求参数
参数名 类型 描述 是否必选
accessToken String 授权过程获取的access_token Y
consumerId String 消费者在组中唯一标识,5分钟内未使用将自动删除,断开和消息通道的链接 Y
preCommit int 是否开启读-提交模式:0-关闭,1-开启。非必选参数,默认关闭 N
  1. consumerId表示消费者在组中唯一标识,5分钟内未使用将自动删除,断开和消息通道的链接
  2. 读-提交模式即读取一次消息自动提交上一次消息,默认情况是需要手动提交。 3.消息通道服务的告警消息由设备上报、平台透传,平台不做任何存储,因此无法再通过萤石各客户端收取告警消息。
  • HTTP请求报文
POST /api/lapp/mq/v1/consumer/messages  HTTP/ 1.1
Host: open.ys7.com
Content-Type: application/x-www-form-urlencoded

accessToken=at.dunwhxt2azk02hcn7phqygsybbw0wv6p&consumerId=fab41dc1ea1043e3ad7285c96df05517
  • 返回数据
{
    "code": "200",
    "msg": "操作成功",
    "data": [
        {
            "header": {
                "channelNo": 0,
                "type": "ys.alarm",
                "deviceId": "152368387"
            },
            "body": {
                "payload": "123"
            }
        },
        {
            "header": {
                "channelNo": 0,
                "type": "ys.alarm",
                "deviceId": "152368387"
            },
            "body": {
                "payload": "123"
            }
        }
    ]
}
  • 返回字段

type为ys.alarm即表示萤石云告警消息,以下是告警消息结构体:

字段名 类型 描述
header Object 设备信息
type String 消息类型:ys.alarm表示设备告警消息
deviceId String 设备序列号
channelNo String 设备通道号
messageId String 消息唯一ID
body Object 设备上传的消息
devSerial String 设备序列号
channel Integer 设备通道号
channelType Integer 设备通道类型: 1-视频通道信息; 2-IO通道
alarmType String 告警类型, 见 附录
alarmId String 设备自己生成的UUID, 用来标识唯一的告警,统一告警的开始、结束采用统一alarmId
relationId String 告警关联ID,由发起联动方产生,用来表示联动的关联关系
status Integer 告警状态 1-开始
location String 告警位置信息:长度不能超过80字节
describe String 告警描述,需要推送给客户的信息
alarmTime String 告警时间,格式: yyyy-MM-ddTHH:mm:ss
customType String 自定义协议类型,命名规则:设备型号_协议标识 如:CS-A1-32W_XX
crypt Integer 图片加密类型:0-不加密,1-用户加密,2-平台加密
requestTime Long 服务端记录的请求时间
pictureList List 告警图片相关信息
shortUrl String 告警图片短地址
id String 平台生成的告警Id
url String 告警图片URL

type为ys.onoffline即表示萤石云上下线消息,以下是上下线消息结构体:

字段名 类型 描述
header Object 设备信息
type String 消息类型:ys.onoffline表示设备上下线消息
deviceId String 设备序列号
channelNo String 设备通道号
messageId String 消息唯一ID
body Object 设备上传的消息
subSerial String 设备序列号
occurTime String 设备上线(离线)时间,格式: yyyy-MM-dd HH:mm:ss
regTime String 设备上一次注册时间,格式: yyyy-MM-dd HH:mm:ss
natIp String 设备外网IP
devType String 设备类型
deviceName Integer 设备名称
msgType String 消息类型:OFFLINE-设备离线消息,ONLINE-设备上线消息
  • 返回码

参见 公共返回码

消费者提交偏移量

  • 接口功能

    该接口用户提交到目前为止读取的消息偏移量。

  • 请求地址

    https://open.ys7.com/api/lapp/mq/v1/consumer/offsets

  • 请求方式

    POST

  • 子账户token请求所需最小权限

  • 请求参数
参数名 类型 描述 是否必选
accessToken String 授权过程获取的access_token Y
consumerId String 消费者在组中唯一标识,5分钟内未使用将自动删除,断开和消息通道的链接 Y
  1. consumerId表示消费者在组中唯一标识,5分钟内未使用将自动删除,断开和消息通道的链接
  • HTTP请求报文
POST /api/lapp/mq/v1/consumer/offsets  HTTP/ 1.1
Host: open.ys7.com
Content-Type: application/x-www-form-urlencoded

accessToken=at.dunwhxt2azk02hcn7phqygsybbw0wv6p&consumerId=fab41dc1ea1043e3ad7285c96df05517
  • 返回数据
{
    "code": "200",
    "msg": "操作成功"
}
  • 返回码

参见 公共返回码

附录:告警消息类型

注:除特殊注明的告警类型以外,其他告警类型都受1分钟最小告警间隔限制,即一分钟最大收到一条告警消息

告警类型 告警描述 备注
pir 人体感应事件
callhelp 紧急遥控按钮事件 不受1分钟间隔限制
motiondetect 移动侦测告警
babycry 婴儿啼哭
magnetometer 门磁告警 不受1分钟间隔限制
fire 烟感告警 不受1分钟间隔限制
gas 可燃气体告警 不受1分钟间隔限制
waterlogging 水浸告警 不受1分钟间隔限制
emergency 紧急按钮告警 不受1分钟间隔限制
infrared 人体感应告警 不受1分钟间隔限制
shelteralarm 遮挡告警
videoloss 视频丢失
linedetection 越界侦测
fielddetection 区域入侵
facedetection 人脸检测事件
doorbell 智能门铃告警
curtain 幕帘告警 不受1分钟间隔限制
move_magnetometer 单体门磁告警 不受1分钟间隔限制
scenechangedetection 场景变更侦测
defocus 虚焦侦测
audioexception 音频异常侦测
leftdetection 物品遗留侦测
takedetection 物品拿取侦测
parkingdetection 非法停车侦测
highdensitydetection 人员聚集侦测
loiterdetection 徘徊检测侦测
rundetection 快速移动侦测
enterareadetection 进入区域侦测
exitareadetection 离开区域侦测
mag_gim 磁干扰告警 不受1分钟间隔限制
UnderVoltage 电池电量低告警 不受1分钟间隔限制
intrusion 闯入告警 不受1分钟间隔限制
baby_motion 婴儿大动作告警
PowerChange 电源切换告警
hightemperature 温度过高告警
lowtemperature 温度过低告警
highhumidity 湿度过高告警
lowhumidity 湿度过低告警
thermalimagingfire 热成像火点告警
whitelistface 陌生人告警
DoorLock-FingerprintOpenDoor 指纹开门
DoorLock-PasswordOpenDoor 密码开门
DoorLock-SwipeOpenDoor 刷卡开门
DoorLock-CenterRemoteOpenDoor 中心远程开门
DoorLock-AppRemoteOpenDoor APP远程开门
DoorLock-KeyOpenDoor 钥匙开门
DoorLock-FingerprintInfoChange 指纹信息改动
DoorLock-RemoteDeviceOpenDoor 遥控器开门
DoorLock-CardInfoChange 卡信息改动
DoorLock-PasswordInfoChange 密码信息改动
DoorLock-UserInfoChange 用户信息改动
DoorLock-SystemInfoChange 系统信息改动
DoorLock-AntiHijackingFingerprint 防劫持指纹告警
DoorLock-AntiHijackingPassword 防劫持密码告警
DoorLock-PryDoor 撬门告警
DoorLock-Locked 门锁锁定告警
DoorLock-BatteryLow 电量不足告警
DoorLock-Blacklist 黑名单告警
DoorLock-Offline 掉线告警
callmsg 呼叫消息
hangupmsg 挂断消息
DoorLock-DoorOpenAlarm 智能锁开门提醒
DoorLock-ConfigChangeAlarm 智能锁配置改动提醒
DoorLock-DoorbellAlarm 门铃提醒
DoorLock-Reset 智能锁复位
DoorLock-DataClear 智能锁数据清空
opendoormsg 开门消息
nothomemsg 未回家消息 不受1分钟间隔限制
lowbattery 电量不足告警
abnormalopendoor 异常开门告警
unclosed 门未关告警
hijack 挟持告警
pry 开门消息
io IO告警
io-1 IO-1告警
io-2 IO-2告警
io-3 IO-3告警
io-4 IO-4告警
io-5 IO-5告警
io-6 IO-6告警
io-7 IO-7告警
io-8 IO-8告警
io-9 IO-9告警
io-10 IO-10告警
io-11 IO-11告警
io-12 IO-12告警
io-13 IO-13告警
io-14 IO-14告警
io-15 IO-15告警
io-16 IO-16告警
VMD 移动侦测告警开始
tamperdetection IO告警
io 遮挡告警开始
alarmTrig 即时防区告警
alarmRest 即时防区恢复
audio24Trig 24小时有声防区告警
audio24Rest 24小时有声防区恢复
enterexitTrig 延时防区告警
enterexitRest 延时防区恢复
internalTrig 内部延时防区告警
internalRest 内部延时防区恢复
fireTrig 火警防区告警
fireRest 火警防区恢复
perimeterTrig 周界防区告警
perimeterRest 周界防区恢复
silent24Trig 24小时无声防区告警
silent24Rest 24小时无声防区恢复
aux24Trig 24小时辅助防区告警
aux24Rest 24小时辅助防区恢复
vib24Trig 24小时震动防区告警
vib24Rest 24小时震动防区恢复
sensorDemol 防区感应器被拆
sensorRecov 防区感应器被拆恢复
softEmergTrig 软防区紧急告警
softFireTrig 软防区火警
softBanditTrig 软防区匪警
hostageReport 挟持报告
devTampering 设备防拆
devTamperRecov 设备防拆恢复
ACDown 交流电掉电
ACRecov 交流电恢复
lowBatVol 蓄电池电压低
norBatVol 蓄电池电压正常
telDiscon 电话线断开
telRecov 电话线连接
XBUSDiscon 扩展总线模块掉线
XBUSRecov 扩展总线模块掉线恢复
keyboardDisconn 键盘掉线
keyboardRecov 键盘恢复
KBUSTrigDiscon 键盘总线上触发器掉线
KBUSTrigRecov 键盘总线上触发器恢复
autoArmFail 自动布防失败
autoDisarmFail 自动撤防失败
wirelessExcep 无线网络异常
wirelessRecov 无线网络恢复正常
SIMExcep SIM卡异常
SIMRecov SIM卡恢复正常
hostReset 主机复位
disarm 撤防
arm 布防
autoDisarm 自动撤防
autoArm 自动布防
clear 消警
instantArm 即时布防
keyDisarm 钥匙防区撤防
keyArm 钥匙防区布防
stayArm 留守布防
forcedArm 强制布防
bypass 旁路
bypassRecov 旁路恢复
grpBypass 子系统组旁路
grpBypassRecov 子系统组旁路恢复
manualRep 手动测试报告
timingRep 定时测试报告
singleDisarm 单防区撤防
singleArm 单防区布防
keypadLock 键盘锁定
keypadUnlock 即时布防
instantArm 键盘解锁
printerOff 打印机掉线
printerOn 打印机恢复
instantDisarm 即时撤防
stayDisarm 留守撤防
triggerScheOn 定时开启触发器
triggerScheOff 定时关闭触发器
acTrigFail 定时开启触发器失败
deacTrigFail 定时关闭触发器失败
enterProgram 进入编程
exitProgram 退出编程
GPKDiscon 键盘总线上GP/K掉线
GPKRecov 键盘总线上GP/K恢复
MNKDiscon 键盘总线上MN/K掉线
MNKRecov 键盘总线上MN/K恢复
IPConflict IP冲突
IPRecov IP正常
netDiscon 网线断开
netRecov 网线正常
VMDRecov 移动侦测告警结束
tamperRecov 遮挡告警结束
videoRecov 视频信号恢复
viIOUnmatch 输入/输出视频制式不匹配
viIORecov 输入/输出视频制式恢复正常
viInputExc 视频输入异常
viInputRecov 视频输入恢复正常
HDDfull 硬盘满
HDDfree 硬盘空闲
HDDexception 硬盘出错
HDDRecov 硬盘恢复正常
uploadPicFail 图片上传失败
DetOffline 探测器离线
DetOnline 探测器恢复在线
DetLowBattery 探测器电量欠压
DetBatteryRecov 探测器电量恢复正常
zoneAddDet 防区添加探测器
zoneDeleteDet 防区删除探测器
wifiException WIFI通信异常
wifiRecov WIFI通信恢复正常
rfException RF信号异常
rfRecov RF信号恢复正常
MINOR_HOST_DESMANTLE_ALARM 主机防拆告警
MINOR_HOST_DESMANTLE_RESUME 主机防拆恢复
MINOR_CARD_READER_DESMANTLE_ALARM 读卡器防拆告警
MINOR_CARD_READER_DESMANTLE_RESUME 读卡器防拆恢复
MINOR_CASE_SENSOR_ALARM 事件输入告警
MINOR_CASE_SENSOR_RESUME 事件输入恢复
MINOR_SECURITY_MODULE_DESMANTLE_ALARM 门控安全模块防拆告警
MINOR_SECURITY_MODULE_DESMANTLE_RESUME 门控安全模块防拆恢复
MINOR_NET_BROKEN 网络断开
MINOR_NET_RESUME 网络恢复
MINOR_DEV_POWER_ON 设备上电启动
MINOR_DEV_POWER_OFF 设备掉电关闭
MINOR_DOOR_OPEN_ABNORMAL 门异常打开(门磁)
emergHelp 紧急呼叫求助告警
emergHelpRecov 紧急呼叫求助恢复
consulting 业务咨询开始
consulted 业务咨询结束
overAlarm 超时告警
overAlarmRecov 超时告警恢复
singleCancelArm 单防区消警
BUSQuery 总线搜索
BUSOpen 总线开路告警
BUSOpenRecov 总线开路告警恢复
BUSShort 总线短路告警
BUSShortRecov 总线短路告警恢复
exModuleExcep 扩展模块异常
exModuleRecov 扩展模块恢复
exModuleLowVol 扩展模块电压低
exModuleVolRecov 扩展模块电压正常
exModuleTamp 扩展模块防拆触发
exModuleTampRecov 扩展模块防拆恢复
exModuleAcDown 扩展模块交流电掉电
exModuleAcOn 扩展模块交流电恢复
repeaterTamp 无线中继器防拆触发
repeaterTampRecov 无线中继器防拆恢复
zoneOpenAlarm 防区开路提醒
zoneShortAlarm 防区短路提醒
telConTest 电话链路测试
exModuleDiscon 扩展模块掉线
exModuleCon 扩展模块掉线恢复
wlModuleDiscon 无线扩展模块掉线
wlModuleCon 无线扩展模块掉线恢复
repeaterDiscon 无线中继器掉线
repeaterCon 无线中继器掉线恢复
netExceed 流量超额
delExModule 删除扩展模块
addExModule 添加扩展模块
delRepeater 删除无线中继器
addRepeater 添加无线中继器
BUSRegistration 总线注册
DoorLock-UnClosed 门锁虚掩告警
audiomsg 语音留言消息 不受1分钟间隔限制
videomsg 视频留言消息 不受1分钟间隔限制
offline 设备下线
ThirdCaption 第三方抓图
Linkage 互联互通 不受1分钟间隔限制

results matching ""

    No results matching ""