物聯(lián)網(wǎng)電梯數(shù)據(jù)交互平臺RESTful API接口設(shè)計(jì)與實(shí)現(xiàn)

張海洋 成新民 徐黃鎮(zhèn)

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

針對目前物聯(lián)網(wǎng)電梯信息管理上存在的數(shù)據(jù)分散、缺乏合理統(tǒng)一的建設(shè)標(biāo)準(zhǔn)以及“信息孤島”的問題，提出采用RESTful API、OAuth2.0等技術(shù)[1]，設(shè)計(jì)開發(fā)電梯管理平臺的企業(yè)服務(wù)接口，實(shí)現(xiàn)平臺對第三方電梯數(shù)據(jù)供應(yīng)方以及企業(yè)相關(guān)數(shù)據(jù)獲取、推送、管理。同時(shí)設(shè)計(jì)出API服務(wù)接口的模式，規(guī)定了統(tǒng)一的接口規(guī)范，解決不同開發(fā)環(huán)境的異構(gòu)系統(tǒng)之間數(shù)據(jù)交互問題，實(shí)現(xiàn)了區(qū)域電梯管理政府主導(dǎo)的模式，健全了整個(gè)電梯管理體系。

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

1 數(shù)據(jù)服務(wù)接口設(shè)計(jì)

1.1 接口數(shù)據(jù)需求分析

物聯(lián)網(wǎng)電梯數(shù)據(jù)交互平臺與第三方電梯數(shù)據(jù)供應(yīng)方對接的電梯數(shù)據(jù)主要分為兩類。具體的需求如下：

（1）在線管理電梯各項(xiàng)靜態(tài)數(shù)據(jù)。這些數(shù)據(jù)包括電梯設(shè)備基礎(chǔ)信息、相關(guān)單位基礎(chǔ)信息、檢驗(yàn)報(bào)告信息、維保記錄信息、公眾投訴信息等，數(shù)據(jù)是由第三方電梯數(shù)據(jù)供應(yīng)方以及相關(guān)電梯品牌商通過平臺提供的接口打包上傳至本平臺，此類數(shù)據(jù)經(jīng)過清洗、轉(zhuǎn)換、集成操作，應(yīng)用于平臺做數(shù)據(jù)查詢、統(tǒng)計(jì)分析和展示。

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

綜上所述，電梯數(shù)據(jù)交互平臺接口按其業(yè)務(wù)需求的實(shí)時(shí)性特點(diǎn)可分為實(shí)時(shí)接口和非實(shí)時(shí)接口兩類接口進(jìn)行設(shè)計(jì)與實(shí)現(xiàn)。

1.2 接口應(yīng)用關(guān)鍵技術(shù)

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

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

1.3 接口體系結(jié)構(gòu)

物聯(lián)網(wǎng)電梯數(shù)據(jù)交互平臺構(gòu)建的API接口層，對第三方電梯數(shù)據(jù)供應(yīng)方制定統(tǒng)一的數(shù)據(jù)規(guī)范，保證接口數(shù)據(jù)交互格式的一致。此外，通過ETL工具Kettle對數(shù)據(jù)進(jìn)行處理、轉(zhuǎn)換、遷移操作[5]，從而解決了目前電梯信息化管理面臨的電梯數(shù)據(jù)分散、不規(guī)范的問題。由此構(gòu)建的物聯(lián)網(wǎng)電梯數(shù)據(jù)交互平臺接口層完成了電梯數(shù)據(jù)的準(zhǔn)確獲取，并且實(shí)現(xiàn)了第三方電梯數(shù)據(jù)供應(yīng)方與平臺間電梯數(shù)據(jù)的靈活交互。接口體系框架圖如圖2所示。

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

1.4 接口設(shè)計(jì)與安全控制

1.4.1 接口設(shè)計(jì)過程

（1）數(shù)據(jù)交互流程如圖3所示；

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

1.4.2 接口安全控制

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

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

（3）端口指定。物聯(lián)網(wǎng)電梯數(shù)據(jù)交互平臺與第三方企業(yè)平臺以及機(jī)構(gòu)之間約定指定端口進(jìn)行數(shù)據(jù)交互。

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

（5）規(guī)定數(shù)據(jù)交互的格式。平臺與第三方之間的數(shù)據(jù)交互，需按照指定的數(shù)據(jù)格式進(jìn)行傳輸，對于不合規(guī)的數(shù)據(jù)格式，會被系統(tǒng)視作垃圾數(shù)據(jù)處理。

2 接口實(shí)現(xiàn)與示例

2.1 接口部署

接口部署網(wǎng)絡(luò)架構(gòu)圖如圖4所示。第三方電梯數(shù)據(jù)供應(yīng)方以及相關(guān)機(jī)構(gòu)的電梯數(shù)據(jù)首先要經(jīng)過ETL數(shù)據(jù)處理，從數(shù)據(jù)源中取出業(yè)務(wù)所需的數(shù)據(jù)，進(jìn)行數(shù)據(jù)清洗，把不完整、錯(cuò)誤、重復(fù)的數(shù)據(jù)源過濾掉，最終按照預(yù)先定義好的數(shù)據(jù)中心模型，將數(shù)據(jù)加載到數(shù)據(jù)中心，把數(shù)據(jù)轉(zhuǎn)換成信息。數(shù)據(jù)傳輸是基于HTTP協(xié)議對接API服務(wù)器，調(diào)用業(yè)務(wù)API接口，將第三方電梯數(shù)據(jù)供應(yīng)方的電梯數(shù)據(jù)上傳至物聯(lián)網(wǎng)電梯數(shù)據(jù)交互平臺。

2.2 接口調(diào)用

2.2.1 創(chuàng)建應(yīng)用

第三方電梯數(shù)據(jù)供應(yīng)方、相關(guān)機(jī)構(gòu)以及上級主管部門的開發(fā)者需要登錄平臺，即進(jìn)入開發(fā)者應(yīng)用中心，創(chuàng)建一個(gè)新應(yīng)用，應(yīng)用分為測試應(yīng)用和正式應(yīng)用兩類。開發(fā)者在測試應(yīng)用中上傳的數(shù)據(jù)，系統(tǒng)只會保留72h，之后會被自動清除。而正式應(yīng)用中上傳的數(shù)據(jù)，即為正式數(shù)據(jù)，一個(gè)開發(fā)者應(yīng)用需要平臺管理員審核后，才可以開通。

2.2.2 應(yīng)用公匙與私匙

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

2.2.3 獲取動態(tài)令牌

動態(tài)令牌即Token，為操作數(shù)據(jù)核心加密動態(tài)標(biāo)識，每次訪問數(shù)據(jù)之前，開發(fā)者都需要先向API服務(wù)器申請動態(tài)令牌，申請的格式為:

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

其中相關(guān)參數(shù)的意義如表1所示。

表1 URL相關(guān)參數(shù)解釋Tab.1 URL related parameters

返回的JSON文本：

{

"ret_status":{

"ret_code":”200”,

"ret_msg":"訪問成功"

},

"ret_data":{

"app_token":"ADEDF45AFF9AFFG345AADFACF F89A23E4",

"token_valid_time":"7200"

}}

其中相關(guān)返回參數(shù)的意義如表2所示。

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

2.2.4 調(diào)用業(yè)務(wù)API示例

以電梯實(shí)時(shí)預(yù)警API為例。該API需在電梯設(shè)備檢測到運(yùn)行異常(GBT24476-2017《電梯、自動扶梯和自動人行道物聯(lián)網(wǎng)的技術(shù)規(guī)范》所列的故障)后，立即向API服務(wù)器發(fā)送異常狀態(tài)數(shù)據(jù)。如前所述，首先數(shù)據(jù)上傳方需要獲取到動態(tài)令牌，獲取了動態(tài)令牌之后就可以調(diào)用電梯實(shí)時(shí)預(yù)警API上傳數(shù)據(jù)了。

電梯實(shí)時(shí)預(yù)警API的URL樣式為:

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

電梯實(shí)時(shí)預(yù)警API的JSON數(shù)據(jù)包樣式為：

{

"req_context”:{

"version": "2.0",

"timestamp":"YOUR_TIMESTAMP",

"signature":"YOUR_SIGNATURE"

},

"req_info":{

"unique_id":"204150",//唯一設(shè)備識別碼

"device_id":"3110102872020C0151",//設(shè)備代碼

"internal_id":"18181",//生產(chǎn)商內(nèi)部生成的事件編號

"service_mode":"0",//當(dāng)前服務(wù)狀態(tài)

"car_status":"0",//當(dāng)liftType=1時(shí)，為轎廂運(yùn)行狀態(tài),當(dāng)lift_type=2時(shí)，為扶梯運(yùn)行狀態(tài))

"car_direction":"0",//當(dāng)liftType=1時(shí)， 為 轎 廂運(yùn)行方向,當(dāng)lift_type=2時(shí)，為扶梯運(yùn)行方向)

"car_position":"1",//電梯當(dāng)前樓層

"door_status":"1",//關(guān)門到位

"passenger_status":"1",//轎內(nèi)是否有人

"total_running_time":"1000",//設(shè)備累計(jì)運(yùn)行時(shí)間

"present_counter_value":"100",//設(shè)備當(dāng)前運(yùn)行次數(shù)

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

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

}

}

JSON數(shù)據(jù)包中的字段含義說明如表3所示。

表3 JSON數(shù)據(jù)包字段含義解釋Tab.3 Field meanings of JSON packets

系統(tǒng)返回的JSON文本為：

{

"ret_status":{

"ret_code":"200",

"ret_msg":"數(shù)據(jù)添加成功"

},

"ret_data":{

}

}

其中相關(guān)返回參數(shù)的意義如表4所示。

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

3 結(jié)語

本文針對目前電梯類特種設(shè)備數(shù)據(jù)管理方面進(jìn)行分析，制定了RESTful API設(shè)計(jì)的原則，實(shí)施構(gòu)建了物聯(lián)網(wǎng)電梯數(shù)據(jù)交互平臺的數(shù)據(jù)服務(wù)接口系統(tǒng)，為城市電梯管理行業(yè)提供了規(guī)范的數(shù)據(jù)訪問格式以及實(shí)時(shí)連接的數(shù)據(jù)訪問服務(wù)。有利于實(shí)現(xiàn)第三方電梯數(shù)據(jù)供應(yīng)平臺、數(shù)據(jù)分析平臺、上級單位之間的互聯(lián)互通，對于突發(fā)情況，各單位能夠協(xié)調(diào)共同處理，提升電梯管理服務(wù)水平，為廣大人民的生命、財(cái)產(chǎn)安全提供了有力保障，提高了政府的服務(wù)質(zhì)量。