全部产品

梯控数据同步服务API

使用说明

  • 本文档提供的接口用于触发梯控设备呼梯,为设备联动或呼梯行为提供所需的数据。

  • 本文档提供的接口需要使用应用服务平台的项目appKey调用,否则可能会导致查询不到对应的边缘集群,数据无法正常下发。

  • 相关的门禁设备和梯控设备需要绑定到边缘集群所在的项目。

接口列表

梯控设备数据管理

接口名称

接口路径

当前版本

新增设备数据

/elevator/entrance/device/add

1.0.1

更新设备数据

/elevator/entrance/device/update

1.0.1

删除设备数据

/elevator/entrance/device/delete

1.0.1

查询设备数据

/elevator/entrance/device/query

1.0.1

梯控用户数据管理

接口名称

接口路径

当前版本

保存用户数据

/elevator/entrance/user/save

1.0.1

删除用户数据

/elevator/entrance/user/delete

1.0.1

查询用户数据

/elevator/entrance/user/query

1.0.1

梯控操作接口

接口名称

接口路径

当前版本

远程呼梯

/elevator/control/elevator/call

1.0.1

API: 新增设备数据

新增梯控设备的联动配置。

path

版本

/elevator/entrance/device/add

1.0.1

入参

名称

类型

是否必填

说明

controlMode

String

梯控联动模式枚举值

CALL_ONLY:呼梯到起始楼层

CALL_WITH_TARGET:呼梯到起始楼层,并指定一个或多个目标楼层

RELEASE_ONLY:轿厢内,释放一个或多个目标楼层

ACTIVATE_ONLY:轿厢内,点亮单个目标楼层

elevatorIotId

String

梯控设备id

triggerIotId

String

触发联动场景的设备id,比如门禁设备

triggerFloor

String

触发联动场景的设备所在楼层,对于轿厢外的联动模式(CALL_ONLY和CALL_WITH_TARGET),该参数必填

triggerRoomNo

String

触发联动场景的设备所在楼层的房间号(多门电梯使用)

triggerElevatorId

String

触发联动场景的设备所在的轿厢编号,用于轿厢内的联动场景,对于轿厢内的联动模式(RELEASE_ONLY和ACTIVATE_ONLY),该参数必填

delaySeconds

Integer

延迟执行的秒数,不填则表示立即执行,最大支持300秒

executionNode

String

执行节点,当前仅支持EDGE,即边缘执行

出参

名称

类型

说明

code

Integer

响应码

message

String

响应消息

data

String

数据项id

API: 更新设备数据

新增或更新门禁设备和梯控设备的联动关系,并指定门禁设备所在的楼层和联动呼梯的延迟执行时间。

path

版本

/elevator/entrance/device/update

1.0.1

入参

入参

类型

是否必填

说明

dataId

String

新增设备数据接口返回的数据项id

triggerFloor

String

触发联动场景的设备所在楼层

triggerRoomNo

String

触发联动场景的设备所在楼层的房间号(多门电梯使用)

triggerElevatorId

String

触发联动场景的设备所在的轿厢编号,用于轿厢内的联动场景

delaySeconds

Integer

延迟执行的秒数

出参

出参

类型

说明

code

Integer

响应码

message

String

响应消息

API: 删除设备数据

删除门禁设备和梯控设备的联动关系。

path

版本

/elevator/entrance/device/delete

1.0.1

入参

入参

类型

是否必填

说明

dataId

String

代表联动关系的数据项id

出参

字段

类型

备注

code

Integer

返回码

message

String

返回信息

API: 查询设备数据

查询门禁设备和梯控设备的联动关系。

path

版本

/elevator/entrance/device/query

1.0.1

入参

入参

类型

是否必填

说明

dataId

String

代表联动关系的数据项id

出参

出参

类型

说明

code

Integer

响应码

message

String

响应消息

data

JSONObject

响应数据

- dataId

String

代表联动关系的数据项id

- controlMode

String

梯控联动模式

- elevatorIotId

String

梯控设备id

- triggerIotId

String

触发联动场景的设备id

- triggerFloor

String

触发联动场景的设备所在楼层

- triggerRoomNo

String

触发联动场景的设备所在楼层的房间号

- triggerElevatorId

String

触发联动场景的设备所在的轿厢编号

- delaySeconds

Integer

延迟执行的秒数

- executionNode

String

执行节点,当前仅支持EDGE,即边缘执行

API: 保存用户数据

在指定的联动关系下,保存用户权限以及用户目标楼层和参数过期时间。

注意:该接口不会把权限下发给对应的门禁设备,调用方需另外使用门禁服务的接口下发门禁权限,否则无法实现联动。

path

版本

/elevator/entrance/user/save

1.0.1

入参

入参

类型

是否必填

说明

dataId

String

代表联动关系的数据项id

paramType

String

用户参数类型,支持IDENTITY/QRCODE/CARD,分别表示人脸、二维码、刷卡权限

paramValue

String

用户参数值,由paramType决定其取值含义:

IDENTITY - 人脸用户的identityId

QRCODE - 二维码

CARD - 卡号

最大长度支持1024位。

expiryTime

String

参数过期时间,过期后参数自动失效,用于门禁权限(如二维码)带有效期的使用场景,不填则表示永久有效。格式:YYYY-MM-DD hh:mm:ss

userTargetList

List

用户的目标楼层列表:

在ACTIVATE_ONLY模式下,只支持1条记录;其他模式最多支持100条记录

-targetFloor

String

目标楼层

-targetRoomNo

String

目标楼层房间号

出参

字段

类型

备注

code

Integer

返回码

message

String

返回信息

API: 删除用户数据

在指定的联动关系下,删除门禁用户权限以及用户目标楼层和参数过期时间。该接口不会删除已经下发给门禁设备的权限数据。

path

版本

/elevator/entrance/user/delete

1.0.1

入参

入参

类型

是否必填

说明

dataId

String

代表联动关系的数据项id

paramType

String

用户参数类型,支持IDENTITY/QRCODE/CARD,分别表示人脸、二维码、刷卡权限

paramValue

String

用户参数值,由paramType决定其取值含义:

IDENTITY - 人脸用户的identityId

QRCODE - 二维码

CARD - 卡号

出参

字段

类型

备注

code

Integer

返回码

message

String

返回信息

API: 查询用户数据

在指定的联动关系下,查询门禁用户权限以及用户目标楼层和参数过期时间。

path

版本

/elevator/entrance/user/query

1.0.1

入参

入参

类型

是否必填

说明

dataId

String

代表联动关系的数据项id

paramType

String

用户参数类型,支持IDENTITY/QRCODE/CARD,分别表示人脸、二维码、刷卡权限

paramValue

String

用户参数值,由paramType决定其取值含义:

IDENTITY - 人脸用户的identityId

QRCODE - 二维码

CARD - 卡号

出参

出参

类型

说明

code

Integer

响应码

message

String

响应消息

data

JSONObject

响应数据

- dataId

String

代表联动关系的数据项id

- paramType

String

用户参数类型

- paramValue

String

用户参数值

- expiryTime

String

参数过期时间

- userTargetList

List

用户的目标楼层列表

-- targetFloor

String

目标楼层

-- targetRoomNo

String

目标楼层房间号

API: 远程呼梯

指定起始楼层和目标楼层进行呼梯操作。

path

版本

/elevator/control/elevator/call

1.0.1

入参

入参

类型

是否必填

说明

iotId

String

梯控设备id

startFloor

String

起始楼层

startRoomNo

String

起始楼层房间号

targetFloor

String

目标楼层

targetRoomNo

String

目标楼层房间号

出参

字段

类型

备注

code

Integer

返回码

message

String

返回信息

使用场景示例

场景1:轿厢内的身份验证与自动点亮目标楼层

场景描述:

电梯轿厢内装有刷卡设备,当用户进入轿厢刷卡时,系统自动为用户点亮目标楼层。

相关数据:

梯控系统iotId:A

轿厢编号:X

刷卡设备iotId:B

用户卡号:123

用户楼层房间号:10-01

使用接口:

1、新增设备数据,指定梯控设备与刷卡设备的联动关系,获取dataId

{
  "controlMode": "ACTIVATE_ONLY",
  "elevatorIotId": "A",
  "triggerIotId": "B",
  "triggerElevatorId": "X"
}

2、保存用户数据,指定用户的目标楼层(该场景下至多为用户指定1个目标楼层)

{
  "dataId": "xxx",
  "paramType": "CARD",
  "paramValue": "123",
  "userTargetList": [
    {
      "targetFloor": "10",
      "targetRoomNo": "01"
    }
  ]
}

场景2:轿厢内的身份验证与自动释放目标楼层

场景描述:

电梯轿厢内装有刷二维码设备,当用户进入轿厢刷二维码时,系统自动为用户释放多个目标楼层,用户可以按需点选需要到达的目标楼层。

相关数据:

梯控系统iotId:A

轿厢编号:X

刷二维码设备iotId:C

用户二维码:abc

用户楼层房间号:10-01、11-02、12(房间号未知或不需要指定)

使用接口:

1、新增设备数据,指定梯控设备与刷二维码设备的联动关系,获取dataId

{
  "controlMode": "RELEASE_ONLY",
  "elevatorIotId": "A",
  "triggerIotId": "C",
  "triggerElevatorId": "X"
}

2、保存用户数据,指定用户的目标楼层(该场景下至多为用户指定100个目标楼层)

{
  "dataId": "xxx",
  "paramType": "QRCODE",
  "paramValue": "abc",
  "userTargetList": [
    {
      "targetFloor": "10",
      "targetRoomNo": "01"
    },
    {
      "targetFloor": "11",
      "targetRoomNo": "02"
    },
    {
      "targetFloor": "12"
    }
  ]
}

场景3:单元门禁的身份验证与联动呼梯

场景描述:

楼栋单元内装有人脸识别门禁,用户需要先通过门禁才能进入电梯。此时,定义门禁设备所在的楼层为起始楼层,用户居住或办公需要到达的楼层为目标楼层。

该场景下当用户刷脸通过门禁设备时,门禁自动向梯控系统发送呼梯指令,梯控系统自动把其中一部电梯呼叫到起始楼层,并在电梯到达后自动点亮轿厢内的目标楼层或者释放轿厢内的多个目标楼层权限。

注意:在电梯到达后,梯控系统的具体行为是“点亮”还是“释放”,这取决于梯控系统的本地化配置,且在一般情况下,如果本地配置为“点亮”,那么不支持用户录入多个目标楼层。

相关数据:

梯控系统iotId:A

人脸识别门禁iotId:D

人脸识别门禁所在楼层:1

用户ID:500eopb710fa6e2af4e85fcae3388cdb3dad2900

用户楼层房间号:10-01

使用接口:

1、新增设备数据,指定梯控设备与刷二维码设备的联动关系,获取dataId

{
  "controlMode": "CALL_WITH_TARGET",
  "elevatorIotId": "A",
  "triggerIotId": "D",
  "triggerFloor": "1"
}

2、保存用户数据,指定用户的目标楼层

{
  "dataId": "xxx",
  "paramType": "IDENTITY",
  "paramValue": "500eopb710fa6e2af4e85fcae3388cdb3dad2900",
  "userTargetList": [
    {
      "targetFloor": "10",
      "targetRoomNo": "01"
    }
  ]
}

场景4:单元门禁的身份验证与联动呼梯到起始楼层

场景描述:

楼栋单元内装有人脸识别门禁,用户需要先通过门禁才能进入电梯。此时,定义门禁设备所在的楼层为起始楼层,用户居住或办公需要到达的楼层为目标楼层。

该场景下当用户刷脸通过门禁设备时,门禁自动向梯控系统发送呼梯指令,梯控系统自动把其中一部电梯呼叫到起始楼层。该场景下通过接口录入的用户数据仅用于判断是否触发联动规则,其中的目标楼层并不会生效。

相关数据:

梯控系统iotId:A

人脸识别门禁iotId:D

人脸识别门禁所在楼层:1

用户ID:500eopb710fa6e2af4e85fcae3388cdb3dad2900

用户楼层房间号:10-01

使用接口:

同场景3

场景5:室内呼梯

场景描述:

用户在家里通过手机或语音助手主动呼叫电梯,并指定要到达1楼。此时,定义用户居住或办公所在的楼层为起始楼层,用户需要到达的楼层为目标楼层。

相关数据:

梯控系统iotId:A

用户所在楼层房间号:10-01

使用接口:

1、远程呼梯

{
  "iotId": "A",
  "startFloor": "10",
  "startRoomNo": "01",
  "targetFloor": "1"
}