物聯網電梯數據交互平臺RESTful API接口設計與實現

張海洋 成新民 徐黃鎮

1.湖州師范學院信息工程學院；2.湖州師范學院信息工程學院；3.湖州市特種設備檢測研究院

針對目前物聯網電梯信息管理上存在的數據分散、缺乏合理統一的建設標準以及“信息孤島”的問題，提出采用RESTful API、OAuth2.0等技術[1]，設計開發電梯管理平臺的企業服務接口，實現平臺對第三方電梯數據供應方以及企業相關數據獲取、推送、管理。同時設計出API服務接口的模式，規定了統一的接口規范，解決不同開發環境的異構系統之間數據交互問題，實現了區域電梯管理政府主導的模式，健全了整個電梯管理體系。

隨著物聯網、大數據、云計算等信息技術的興起，國家也隨之提出了“智慧城市”的發展戰略[2]。電梯作為城市樓宇交通的一個重要組成部分，符合“智慧城市”戰略的建設要求，所以需要構建一個能夠獲取所有電梯相關數據的接口服務體系，實現對電梯從生產、安裝、運行、維保全過程的信息監督。目前，城市電梯數據分散在不同的電梯數據平臺，各電梯數據平臺信息系統建設時期不同，電梯數據規范不一致，無法實現電梯數據跨平臺交互共享。總體而言，國家在物聯網電梯領域標準化工作起步緩慢，電梯信息化建設缺乏相應的經驗,本文研究的基于RESTful API的物聯網電梯數據交互平臺，針對所需收集的電梯各類數據，開發相應的API接口，為城市電梯信息化建設提供了一種可行的解決方案。

1 數據服務接口設計

1.1 接口數據需求分析

物聯網電梯數據交互平臺與第三方電梯數據供應方對接的電梯數據主要分為兩類。具體的需求如下：

（1）在線管理電梯各項靜態數據。這些數據包括電梯設備基礎信息、相關單位基礎信息、檢驗報告信息、維保記錄信息、公眾投訴信息等，數據是由第三方電梯數據供應方以及相關電梯品牌商通過平臺提供的接口打包上傳至本平臺，此類數據經過清洗、轉換、集成操作，應用于平臺做數據查詢、統計分析和展示。

（2）及時反饋電梯物聯數據并進行分析預警。由于電梯的運行故障涉及到乘客的人身財產安全，所以在電梯運行過程中，需要獲取電梯實時運行狀態數據，這些數據包括電梯實時視頻鏈接、電梯當前樓層、運行速度、運行方向、開關門狀態、有無人狀態等，當電梯設備檢測到運行異常時，立即向API服務器發送異常狀態數據，平臺隨即進行實時預警，響應救援單位前往電梯故障地。該部分數據主要是由第三方電梯供應商主動通過數據接口上報至平臺，應用于平臺做大數據分析服務，并兼顧數據查詢、統計分析。

綜上所述，電梯數據交互平臺接口按其業務需求的實時性特點可分為實時接口和非實時接口兩類接口進行設計與實現。

1.2 接口應用關鍵技術

（1）RESTful API技術。RESTful是一種面向資源的API架構風格[3]，是目前許多公司企業使用的主流API架構風格，相比于其他風格的API構架，符合RESTful風格的API接口更加靈活，系統中每個需要被訪問、調用的數據信息被看作為一個資源，用特定的URL指向每種資源，URL和服務一一對應，同一個URL對資源的操作有GET(獲取資源)、POST(新建資源)、PUT(更新)、DELETE(刪除資源)。

（2）OAuth2.0授權機制。OAuth2.0授權機制是以原OAuth協議為基礎，升級了開發的簡易性，通過允許第三方應用來代表用戶獲取授權，允許用戶在不提供個人信息的情況下來訪問平臺資源，提高了系統的安全性[4]。API的范圍權限采用符合IETF RFC6749的OAuth2.0的授權機制，第三方開發者早在每次訪問數據類API之前，需要先API服務器申請動態令牌，在申請到有效令牌之后，開發者需要在指定時間內完成對API服務器數據類API的服務調用，超時令牌將被撤銷訪問。本接口基于OAuth2.0認證授權機制的訪問流程如圖1所示。

1.3 接口體系結構

物聯網電梯數據交互平臺構建的API接口層，對第三方電梯數據供應方制定統一的數據規范，保證接口數據交互格式的一致。此外，通過ETL工具Kettle對數據進行處理、轉換、遷移操作[5]，從而解決了目前電梯信息化管理面臨的電梯數據分散、不規范的問題。由此構建的物聯網電梯數據交互平臺接口層完成了電梯數據的準確獲取，并且實現了第三方電梯數據供應方與平臺間電梯數據的靈活交互。接口體系框架圖如圖2所示。

接口工作流程說明如下：通過Kettle數據ETL工具將第三方電梯數據供應方傳來的電梯各項數據按照實時性數據、非實時性數據類別進行抽取，匯總統一處理及存儲，利用RESTful API技術高內聚低耦合的特點[6]建立開放、通用的數據接口，實現電梯數據集成平臺接口服務，與第三方電梯數據供應方平滑對接。

1.4 接口設計與安全控制

1.4.1 接口設計過程

（1）數據交互流程如圖3所示；

（2）數據交互的流程包括：1）規定數據類API訪問的URL樣式；2）在HTTP請求頭中攜帶數據訪問令牌，同時為了保證請求的唯一性，設置一個參數Request-ID，這個Request-ID一般是GUID或UUID那樣的全局唯一碼；3）將參數根據參數字典排序，并賦以真實值后進行MD5字符串加密，形成Sign(簽名)；4）構建JSON數據包樣式，Post數據到服務器；5）在API服務器上對簽名字符串進行比對，無效的數據將返回訪問失敗；6）簽名串比對成功，服務器將響應結果組裝成JSON格式數據返回給客戶端，并返回200狀態碼表示訪問成功。

1.4.2 接口安全控制

（1）OAuth2.0認證授權。在OAuth2.0協議流的定義下，第三方獲取資源必須按照獲取認證、獲取訪問資源令牌、通過令牌獲取指定資源的順序。

（2）IP認證。對于測試應用API，無IP地址限定要求，而對于正式應用，需在開發者中心申請IP地址白名單并經審核，平臺只會接受提前認證的IP推送的數據，IP地址白名單以外的IP，無法訪問正式應用API。

（3）端口指定。物聯網電梯數據交互平臺與第三方企業平臺以及機構之間約定指定端口進行數據交互。

（4）簽名比對。從第三方電梯數據供應方發往API服務器的數據請求，都需要加入簽名，簽名為MD5加密字符串，簽名不符合的數據將視為垃圾數據而不予處理。

（5）規定數據交互的格式。平臺與第三方之間的數據交互，需按照指定的數據格式進行傳輸，對于不合規的數據格式，會被系統視作垃圾數據處理。

2 接口實現與示例

2.1 接口部署

接口部署網絡架構圖如圖4所示。第三方電梯數據供應方以及相關機構的電梯數據首先要經過ETL數據處理，從數據源中取出業務所需的數據，進行數據清洗，把不完整、錯誤、重復的數據源過濾掉，最終按照預先定義好的數據中心模型，將數據加載到數據中心，把數據轉換成信息。數據傳輸是基于HTTP協議對接API服務器，調用業務API接口，將第三方電梯數據供應方的電梯數據上傳至物聯網電梯數據交互平臺。

2.2 接口調用

2.2.1 創建應用

第三方電梯數據供應方、相關機構以及上級主管部門的開發者需要登錄平臺，即進入開發者應用中心，創建一個新應用，應用分為測試應用和正式應用兩類。開發者在測試應用中上傳的數據，系統只會保留72h，之后會被自動清除。而正式應用中上傳的數據，即為正式數據，一個開發者應用需要平臺管理員審核后，才可以開通。

2.2.2 應用公匙與私匙

當開發者創建了應用之后，開發者可以從“應用>基礎信息”中獲得應用公匙(AppKey)與私匙(AppSecret)，公匙與私匙均為256為DES加密字符串。應用公匙和私匙都是用于表示第三方開發者身份的可公開ID和私有密匙。

2.2.3 獲取動態令牌

動態令牌即Token，為操作數據核心加密動態標識，每次訪問數據之前，開發者都需要先向API服務器申請動態令牌，申請的格式為:

http://api.hztjzx.cn:9095/api_lift?action=token&appKey=YOUR_APP_KEY& appSecret=YOUR_APP_SECRET×tamp=YOUR_TIME STAMP&sign=YOUR_SIGNATURE。

其中相關參數的意義如表1所示。

表1 URL相關參數解釋Tab.1 URL related parameters

返回的JSON文本：

{

"ret_status":{

"ret_code":”200”,

"ret_msg":"訪問成功"

},

"ret_data":{

"app_token":"ADEDF45AFF9AFFG345AADFACF F89A23E4",

"token_valid_time":"7200"

}}

其中相關返回參數的意義如表2所示。

表2 返回JSON文本參數解釋Tab.2 Parameter description of the returned JSON text

2.2.4 調用業務API示例

以電梯實時預警API為例。該API需在電梯設備檢測到運行異常(GBT24476-2017《電梯、自動扶梯和自動人行道物聯網的技術規范》所列的故障)后，立即向API服務器發送異常狀態數據。如前所述，首先數據上傳方需要獲取到動態令牌，獲取了動態令牌之后就可以調用電梯實時預警API上傳數據了。

電梯實時預警API的URL樣式為:

http://api.hztjzx.cn:9005/api_lift?Action=lift_alarm

電梯實時預警API的JSON數據包樣式為：

{

"req_context”:{

"version": "2.0",

"timestamp":"YOUR_TIMESTAMP",

"signature":"YOUR_SIGNATURE"

},

"req_info":{

"unique_id":"204150",//唯一設備識別碼

"device_id":"3110102872020C0151",//設備代碼

"internal_id":"18181",//生產商內部生成的事件編號

"service_mode":"0",//當前服務狀態

"car_status":"0",//當liftType=1時，為轎廂運行狀態,當lift_type=2時，為扶梯運行狀態)

"car_direction":"0",//當liftType=1時， 為 轎 廂運行方向,當lift_type=2時，為扶梯運行方向)

"car_position":"1",//電梯當前樓層

"door_status":"1",//關門到位

"passenger_status":"1",//轎內是否有人

"total_running_time":"1000",//設備累計運行時間

"present_counter_value":"100",//設備當前運行次數

"message_code":"01",//信息代碼

"message_body":"",//信息說明

}

}

JSON數據包中的字段含義說明如表3所示。

表3 JSON數據包字段含義解釋Tab.3 Field meanings of JSON packets

系統返回的JSON文本為：

{

"ret_status":{

"ret_code":"200",

"ret_msg":"數據添加成功"

},

"ret_data":{

}

}

其中相關返回參數的意義如表4所示。

表4 返回JSON文本參數解釋Tab.4 Parameter description of the returned JSON text

3 結語

本文針對目前電梯類特種設備數據管理方面進行分析，制定了RESTful API設計的原則，實施構建了物聯網電梯數據交互平臺的數據服務接口系統，為城市電梯管理行業提供了規范的數據訪問格式以及實時連接的數據訪問服務。有利于實現第三方電梯數據供應平臺、數據分析平臺、上級單位之間的互聯互通，對于突發情況，各單位能夠協調共同處理，提升電梯管理服務水平，為廣大人民的生命、財產安全提供了有力保障，提高了政府的服務質量。