如何使用人梯联动及其接口_物联网应用服务（文档停止维护）-阿里云帮助中心

使用说明

本文档提供的接口用于触发梯控设备呼梯，为设备联动或呼梯行为提供所需的数据。
本文档提供的接口需要使用应用服务平台的项目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域为设备服务的输出参数。

说明

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

梯控物模型服务定义

云端呼梯

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

获取电梯状态

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

获取电梯信息

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

设置人梯联动开关

SetElevatorRuleState

功能类型：服务

调用方式：同步

输入参数：

参数名称

参数标识

数据类型

使能状态

Availability

text

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

输出参数：

参数名称	参数标识	数据类型
结果编码	code	int
结果说明	message	text

结果说明（下同）：

结果编码（code）	结果说明（message）
0	成功	success
4	发送到设备失败	send to device fail

获取人梯联动开关

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	目标楼层房间号