文档

人梯联动

更新时间:
一键部署

使用说明

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

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

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

接口列表

梯控设备数据管理

接口名称

接口路径

当前版本

新增设备数据

/elevator/entrance/device/add

1.0.2

更新设备数据

/elevator/entrance/device/update

1.0.2

删除设备数据

/elevator/entrance/device/delete

1.0.2

查询设备数据

/elevator/entrance/device/query

1.0.2

梯控用户数据管理

接口名称

接口路径

当前版本

保存用户数据

/elevator/entrance/user/save

1.0.2

删除用户数据

/elevator/entrance/user/delete

1.0.2

查询用户数据

/elevator/entrance/user/query

1.0.2

梯控操作接口

接口名称

接口路径

当前版本

远程呼梯

/elevator/control/elevator/call

1.0.1

调用设备服务(梯控泛化接口)

/cloud/thing/service/invoke

1.0.1

API: 新增设备数据

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

path

版本

/elevator/entrance/device/add

1.0.2

入参

名称

类型

是否必填

说明

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.2

入参

入参

类型

是否必填

说明

dataId

String

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

triggerFloor

String

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

triggerRoomNo

String

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

delaySeconds

Integer

延迟执行的秒数

出参

出参

类型

说明

code

Integer

响应码

message

String

响应消息

API: 删除设备数据

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

path

版本

/elevator/entrance/device/delete

1.0.2

入参

入参

类型

是否必填

说明

dataId

String

代表联动关系的数据项id

出参

字段

类型

备注

code

Integer

返回码

message

String

返回信息

API: 查询设备数据

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

path

版本

/elevator/entrance/device/query

1.0.2

入参

入参

类型

是否必填

说明

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.2

入参

入参

类型

是否必填

说明

dataId

String

代表联动关系的数据项id

identityId

String

用户统一身份id

expiryTime

String

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

userTargetList

List

用户的目标楼层列表:

在CALL_ONLY模式下可空,其他模式必填;在ACTIVATE_ONLY模式下,只支持1条记录;其他模式最多支持100条记录。

-targetFloor

String

目标楼层

-targetRoomNo

String

目标楼层房间号

出参

字段

类型

备注

code

Integer

返回码

message

String

返回信息

API: 删除用户数据

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

path

版本

/elevator/entrance/user/delete

1.0.2

入参

入参

类型

是否必填

说明

dataId

String

代表联动关系的数据项id

identityId

String

用户统一身份id

出参

字段

类型

备注

code

Integer

返回码

message

String

返回信息

API: 查询用户数据

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

path

版本

/elevator/entrance/user/query

1.0.2

入参

入参

类型

是否必填

说明

dataId

String

代表联动关系的数据项id

identityId

String

用户统一身份id

出参

出参

类型

说明

code

Integer

响应码

message

String

响应消息

data

JSONObject

响应数据

- dataId

String

代表联动关系的数据项id

- identityId

String

用户统一身份id

- 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

返回信息

API: 调用设备服务(梯控泛化接口)

接口定义

path

版本

是否需要登录

/cloud/thing/service/invoke

1.0.1

入参

字段

类型

是否必传

备注

iotId

String

门禁设备的iotId

identifier

String

设备服务标识符

args

JSNOObject

服务的输入参数

出参

返回结果使用通用结果类型,data域为设备服务的输出参数。

说明

该接口适用于梯控相关的所有物模型服务。

梯控物模型服务定义

  1. 云端呼梯

CloudCallElevator

功能类型:服务

调用方式:同步

输入参数:

参数名称

参数标识

数据类型

长度限制

电梯编号

ElevatorID

text

2048

起始楼层

StartFloor

text

2048

起始楼层房间号

StartRoomNumber

text

2048

目标楼层

TargetFloor

text

2048

目标楼层房间号

TargetRoomNumber

text

2048

目标方向

TargetDirection

enum(枚举型)1:上行;2:下行

-

输出参数:

参数名称

参数标识

数据类型

结果编码

code

int

结果说明

message

text

结果说明(下同):

结果编码(code)

结果说明(message)

0

成功

success

4

发送到设备失败

send to device fail

  1. 获取电梯状态

QueryElevatorStatus

功能类型:服务

调用方式:同步

输入参数:无

输出参数:

参数名称

参数标识

数据类型

电梯状态

ElevatorStatus

array(数组)

元素类型:STRUCT,元素定义详见下方

结果编码

code

int

结果说明

message

text

电梯状态(ElevatorStatus)数组元素定义

参数名称

参数标识

数据类型

电梯编号

ElevatorID

text

轿厢当前楼层

CurrentPosition

text

轿厢运行状态

CarStatus

ENUM

-1:未知;0:停止;1:运行

轿厢运行方向

CarDirection

ENUM

-1:未知;0:无方向;1:上行;2:下行

结果说明(下同):

结果编码(code)

结果说明(message)

0

成功

success

4

发送到设备失败

send to device fail

  1. 获取电梯信息

QueryElevatorInfo

功能类型:服务

调用方式:同步

输入参数:无

输出参数:

参数名称

参数标识

数据类型

电梯控制模式

ElevatorMode

text

当前定义列表:

"SINGLE":单控;"GROUP":群控;"ALL":双模(单控和群控)

电梯信息

ElevatorInfo

array

元素类型:STRUCT,元素定义详见下方

电梯楼层房间信息

FloorRoomInfo

array

元素类型:STRUCT,元素定义详见下方

结果编码

code

int

结果说明

message

text

电梯信息(ElevatorInfo)数组元素定义

参数名称

参数标识

数据类型

电梯编号

ElevatorID

text

电梯名称

ElevatorName

text

双开门

IsDualCardDoor

Bool

电梯楼层房间信息(FloorRoomInfo)数组元素定义

参数名称

参数标识

数据类型

电梯编号

ElevatorID

text

楼层

Floor

text

房间号

RoomNumber

text

结果说明(下同):

结果编码(code)

结果说明(message)

0

成功

success

4

发送到设备失败

send to device fail

  1. 设置人梯联动开关

SetElevatorRuleState

功能类型:服务

调用方式:同步

输入参数:

参数名称

参数标识

数据类型

使能状态

Availability

text

"disable":禁用; "enable":使能

输出参数:

参数名称

参数标识

数据类型

结果编码

code

int

结果说明

message

text

结果说明(下同):

结果编码(code)

结果说明(message)

0

成功

success

4

发送到设备失败

send to device fail

  1. 获取人梯联动开关

GetElevatorRuleState

功能类型:服务

调用方式:同步

输入参数:无

输出参数:

参数名称

参数标识

数据类型

使能状态

Availability

text

"disable":禁用; "enable":使能

结果编码

code

int

结果说明

message

text

结果说明(下同):

结果编码(code)

结果说明(message)

0

成功

success

4

发送到设备失败

send to device fail

使用场景示例

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

场景描述:

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

相关数据:

梯控系统iotId:A

轿厢编号:X

刷卡设备iotId:B

用户id:500eopb710fa6e2af4e85fcae3388cdb3dad2900

用户楼层房间号:10-01

使用接口:

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

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

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

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

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

场景描述:

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

相关数据:

梯控系统iotId:A

轿厢编号:X

刷二维码设备iotId:C

用户id:500eopb710fa6e2af4e85fcae3388cdb3dad2900

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

使用接口:

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

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

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

{
  "dataId": "xxx",
  "identityId": "500eopb710fa6e2af4e85fcae3388cdb3dad2900",
  "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",
  "identityId": "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"
}

历史版本

保存用户数据(1.0.1)

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

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

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

返回信息

删除用户数据(1.0.1)

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

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

返回信息

查询用户数据(1.0.1)

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

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

目标楼层房间号