梯控聯動服務API
本文檔提供的接口用于人員通行時觸發梯控設備的自動呼梯。
使用說明
本文檔提供的接口需要使用應用服務平臺的項目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域為設備服務的輸出參數。
該接口適用于梯控相關的所有物模型服務。
人梯聯動事件數據模型定義
數據模型名稱：人梯聯動數據模型 （AutoElevatorCallRecord）
數據模型版本：1.0
名稱 | 標識符 | 類型 | 說明 |
記錄標示 | eventId | String | 記錄的唯一標識 |
上報時間 | eventTime | Date | 上報時間 |
用戶ID | identityID | String | 用戶IDENTITY_ID |
通行方式 | mediaType | String | 枚舉值：FACE、QRCODE、CARD |
通行ID | mediaID | String | 對應通行方式中人員具備的唯一ID，例如人臉ID、二維碼，或者卡號 |
門禁產品名 | entranceProductKey | String | 無 |
門禁設備名 | entranceDeviceName | String | 無 |
梯控產品名 | elevatorProductKey | String | 無 |
梯控設備名 | elevatorDeviceName | String | 無 |
出發樓層信息 | startFloor | String | 無 |
出發電梯門信息 | StartRoomNumber | String | 無 |
目的樓層信息 | targetList | String | 無 |
聯動結果返回碼 | callResultCode | int | 200表示成功 |
聯動結果信息 | callResultMsg | String | 聯動結果， "success" 或者 "failed + 錯誤詳情" |
設備擴展信息 | deviceExtInfo | String | 設備擴展信息，保留字段 |
用戶信息擴展信息 | userExtInfo | String | 用戶擴展信息，保留字段 |
事件擴展信息 | eventExtInfo | String | 事件擴展信息，保留字段； |
梯控物模型服務定義
云端呼梯
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 | 目標樓層房間號 |