二、房源對接 · 云丁Saas管理系統openAPI最佳實現v1.0

# 2.1 房源對接方式的選擇智能設備管理系統開發的第一件事就是需要確定與云丁saas系統房源對接的方式。這里先介紹**房源**的概念：云丁智能設備管理是基于房源為單位的，對應于現實生活中的房源模型。具體說來就是建立一個房源，并且在其中創建房間，然后將相應的智能網關，智能門鎖，智能采集器，智能電表和智能水表等添加到對應的房間。因此、智能設備管理也就是基于房源的管理。商戶自行開發的智能設備管理系統與云丁Saas系統進行房源對接的方式主要分為兩種： 1. 已有設備，再對接即：商戶在云丁Saas系統先建立房源房間，并且添加設備之后再將云丁系統上的房源以及房源內的設備等數據導入自己的系統，實現系統之間的對接。（已有設備，再對接） 2. 先對接，再裝設備（**推薦**）即：商戶先在自己的系統上建立房源房間，然后通過openAPI將自己的房源數據推送給云丁Saas系統；再根據工單模塊添加安裝工單，云丁交付團隊上門安裝設備。（先對接，再裝設備）重點推薦先對接，再裝設備的方式。因此本文檔也將通過先對接，再裝設備的方式實現房源對接。 # 2.2 房源房間對接代碼實現根據上面的介紹，我們選擇第二種先對接，再裝設備的方式進行對接。因此，系統先實現房源的對接。代碼結構如下： ``` SmartDeviceMgrSystem —apis —home.py —room.py —ticket.py —home_model.py —main.py ``` **注意**：由于本文檔的目的是讓開發者快速了解與云丁系統對接的操作流程，因此房源數據結構采用json格式，不涉及模型的建立與數據庫存儲的操作。 apis文件夾主要存放調用云丁系統接口的函數，這一章我們完成的功能主要會調用到房源，房間和工單的接口，因此新建三個文件home.py, room.py, ticket.py。以下是具體的代碼示例： home.py ``` import requests def add_home(access_token, country, city, zone, location, block, home_id, home_name): ''' 添加房源 params: access_token: 調用接口憑證 country：國家 city：城市 zone：區域 location: 具體地址 block: 小區 home_id: 房源id(全局唯一) home_name: 房源名稱 ''' url = 'https://saas-openapi.dding.net/v2/add_home' headers = { 'Content-type': 'Application/json', 'User-Agent': 'PostmanRuntime/7.13.0', } payload = { 'access_token': access_token, 'country': country, 'city': city, 'zone': zone, 'location': location, 'block': block, 'home_id': home_id, 'home_name': home_name } response = requests.request('POST', url, headers=headers, json=payload) if response.status_code == 200: return response.json() def get_home_info(access_token, home_id): ''' 獲取房源信息 params: access_token: 調用接口憑證 home_id: 房源id（全局唯一） ''' url = 'https://saas-openapi.dding.net/v2/get_home_info' headers = { 'Content-type': 'Application/json', 'User-Agent': 'PostmanRuntime/7.13.0', } payload = { 'access_token': access_token, 'home_id' : home_id } response = requests.request('POST', url, headers=headers, json=payload) if response.status_code == 200: return response.json() ``` room.py ``` import requests ''' 添加房間 ''' def add_rooms(access_token, home_id, rooms): ''' 添加房間 params： access_token: 調用接口憑證 home_id: 房源id rooms: list類型 [room1, room2, ... roomn] ''' url = 'https://saas-openapi.dding.net/v2/add_rooms' headers = { 'Content-type': 'Application/json', 'User-Agent': 'PostmanRuntime/7.13.0', } payload = { 'access_token': access_token, 'home_id': home_id, 'rooms': rooms } response = requests.request('POST', url, headers=headers, json=payload) if response.status_code == 200: return response.json() ~~~ ``` ticket.py ~~~ import requests ''' 添加工單 ''' def add_ticket(access_token, home_id, service_target, service_type, room_ids, subscribe): ''' 添加工單 params： access_token: 接口調用憑證 home_id: 房源id service_target: 工單服務對象 1：網關 2：門鎖 3：電表 service_type: 工單類型 1：安裝 2：售后維修 room_ids: list 需要預約或維修的房間 [room1, room2] subscribe: 下單人 dict 需包含：date, time, name, phone date: 預約時間戳 ms time: 100:全天 101：上午 102:下午 name: 下單人姓名 phone: 下單人聯系方式 ''' url = 'https://saas-openapi.dding.net/v2/add_ticket' headers = { 'Content-type': 'Application/json', 'User-Agent': 'PostmanRuntime/7.13.0', } payload = { 'access_token': access_token, 'home_id': home_id, 'service_target': service_target, 'service_type': service_type, 'room_ids': room_ids, 'subscribe': subscribe } response = requests.request('POST', url, headers=headers, json=payload) if response.status_code == 200: return response.json() ~~~ 然后在系統建立房源模型，注意：為了簡潔，此處模型并不涉及數據庫的操作。vim home_model.py ``` from apis.home import add_home, get_home_info from apis.room import add_rooms from apis.ticket import add_ticket class Home: def __init__(self, **kwargs): access_token = kwargs['access_token'] country = kwargs['country'] city = kwargs['city'] zone = kwargs['zone'] location = kwargs['location'] block = kwargs['block'] home_id = kwargs['home_id'] home_name = kwargs['home_name'] res = add_home(access_token, country, city, zone, location, block, home_id, home_name) if 'ErrNo' in res: if res['ErrNo'] == 0: print('home creating successfully!') else: print('home creating failed') def get_home_info(self, **kwargs): access_token = kwargs['access_token'] home_id = kwargs['home_id'] res = get_home_info(access_token, home_id) return res def add_room(self, **kwargs): access_token = kwargs['access_token'] home_id = kwargs['home_id'] rooms = kwargs['rooms'] res = add_rooms(access_token, home_id, rooms) return res def add_ticket(self, **kwargs): access_token = kwargs['access_token'] home_id = kwargs['home_id'] service_target = kwargs['service_target'] service_type = kwargs['service_type'] room_ids = kwargs['room_ids'] subscribe = kwargs['subscribe'] res = add_ticket(access_token, home_id, service_target, service_type, room_ids, subscribe) return res ``` 創建Home類，并實現添加房間(add_home)，獲取房源信息(get_home_info),添加工單(add_ticket)等方法。 ## 2.2.1 房源對接剛剛已經實現了apis的接口函數和home_model，接著便可以在系統創建房源，并且與云丁Saas系統進行對接。vim main.py ``` from home_model import Home def main(): #創建房源 home_data = { 'access_token' : '6afc3f360e04f806244af07c6c5eca1cee6065e83565e107fc4896b55ce8f735df5bd9a7d3c5e1e2f96f1fdd1c2ea52483ec2e10e5cc38517a17b1d4aff2ceff', 'country' : '中國', 'city' : '深圳', 'zone' : '南山區', 'location' : '深南大道118號', 'block' : '萬科一期', 'home_id' : 'testhomeid123', 'home_name' : '18棟1501' } home = Home(**home_data) if __name__ == '__main__': main() ``` ``` ``` 將需要創建的房源參數組裝成Json格式，初始化Home類，成功創建房源。返回結果： ``` home creating successfully! ``` 生產環境中需要將home模型存入數據庫中，這重在說明實現的方法，因此省略數據庫操作。 ## 2.2.2 房間對接接下來，在上述的房源中創建房間，并且與云丁Saas系統對接。vim main.py 其代碼示例： ``` room_data = { 'access_token' : '6afc3f360e04f806244af07c6c5eca1cee6065e83565e107fc4896b55ce8f735df5bd9a7d3c5e1e2f96f1fdd1c2ea52483ec2e10e5cc38517a17b1d4aff2ceff', 'home_id' : 'testhomeid123', 'rooms' : [ { 'room_id':'0001', 'room_name':'房間1' } ] } res = home.add_room(**room_data) print(res) ``` 房間成功創建，其返回結果為： ``` {'ReqID': '1SBR3NWtqmY', 'ErrNo': 0, 'ErrMsg': ''} ``` 到此，我們實現了房源房間的對接，并且將home_id，room_id等數據都保存下來。 # 2.3 工單模塊的實現在實現了房源房間對接后，便需要安裝設備了，因此需要實現工單功能。上面兩小節中，我們已經創建了房源，房間并且把房源房間的基本數據，如：home_id, room_id等都保存了下來，接著使用它們建立工單。vim main.py ``` ticket_data = { 'access_token' : '6afc3f360e04f806244af07c6c5eca1cee6065e83565e107fc4896b55ce8f735df5bd9a7d3c5e1e2f96f1fdd1c2ea52483ec2e10e5cc38517a17b1d4aff2ceff', 'home_id' : 'testhomeid123', 'service_target' : 2, #2.門鎖 'service_type' : 1, #1.新裝工單 'room_ids' : ['0001', 'testhomeid123'], 'subscribe' : { 'date' : 1567094400000, 'time' : 102, 'name' : 'zengjia', 'phone' : '18620190127' } } res = home.add_ticket(**ticket_data) print(res) ``` 工單的接口含義如下： ``` params： access_token: 接口調用憑證 home_id: 房源id service_target: 工單服務對象 1：網關 2：門鎖 3：電表 service_type: 工單類型 1：安裝 2：售后維修 room_ids: list 需要預約或維修的房間 [room1, room2] subscribe: 下單人 dict 需包含：date, time, name, phone date: 預約時間戳 ms time: 100:全天 101：上午 102:下午 name: 下單人姓名 phone: 下單人聯系方式 ``` 添加工單成功后，我們能從返回的結果的ticket_id字段中拿到工單編號 ``` {'ReqID': '1SBR3ZfKpV6', 'ErrNo': 0, 'ErrMsg': '', 'ticket_id': 'ISLK1908301908503'} ``` # 2.4 設備安裝完成的確定當添加完工單后，云丁交付團隊便會根據工單前往現場安裝綁定設備，那么我們如何得知設備已經綁定成功，可以進行管理了呢？主要是兩種方式：事件回調與主動輪詢。具體說明之前，先解釋下**事件**。當我們對只能設備進行操作時，由于網絡IO耗時，所以采取異步操作。當設備操作成功便會將該信息回調給系統，云丁將這種由設備產生的回調稱為**事件**，如：綁定事件。 **1**.事件回調，在第一章申請對接的時候便填寫過異步事件的回調地址，當有設備事件發生時，云丁系統便會將設備事件回調給商戶對接的系統。云丁系統將對商戶的回調url發起http請求。商戶系統收到http請求之后，解析事件并能夠知曉設備已經綁定成功。 **2**. 主動輪詢get_home_info下面的devices字段，如果不為空，則說明設備已經添加成功。（注意：這里只是為了演示，并不考慮系統的效率問題，實際生產環境請使用解析事件的方法。） vim main.py ``` while True: res = home.get_home_info(**search_data) if 'result'in res: if 'devices'in res: if len(res['result']['devices']) != 0: for device in res['result']['devices']: print(device) break print('設備添加完畢') ``` 當設備都綁定成功后，get_home_info返回的結果如下： ``` { "ReqID": "1SC5R5uFrIu", "ErrNo": 0, "ErrMsg": "", "result": { "home_id": "testhomeid123", "home_name": "18棟1501", "location": "深南大道118號", "description": "", "home_type": 2, "province": "廣東省", "city": "深圳市", "zone": "南山區", "block": "萬科一期", "rooms": [ { "room_id": "testhomeid123", "room_name": "公區", "description": "", "sp_state": 1, "install_state": 4 }, { "room_id": "0001", "room_name": "房間1", "description": "", "sp_state": 1, "install_state": 4 } ], "devices": [ { "type": "lock", "sn": "lkjl0019180300779045", "uuid": "8dd9127be919024ba6b2dadd35ea4ff6", "device_id": 534906033, "description": "lock01", "room_id": "testhomeid123", "onoff": 1, "is_out": true, "center_uuid": "ccec6095685126a25213657764f7eb2f", "model_name": "D2F", "model": "lk-19", "power": 94 }, { "type": "gateway", "sn": "cnjl0003180100385967", "uuid": "ccec6095685126a25213657764f7eb2f", "device_id": 2043770700, "description": "網關", "room_id": "testhomeid123", "onoff": 1, "is_out": true, "model_name": "G2", "model": "cn-03" }, { "type": "lock", "sn": "lkjl0026190002800173", "uuid": "157c4b2bfc87abe316378b42cde86141", "device_id": 1632908514, "description": "lock02", "room_id": "0001", "onoff": 1, "center_uuid": "ccec6095685126a25213657764f7eb2f", "model_name": "D3", "model": "lk-26", "power": 0 } ], "lease_type": 1 } } ``` devices字段已經有綁定的設備了。后面還需要安裝新設備也是采用相同的方法。 # 2.5 小結本章節按照先對接，再裝設備的方式，完成了智能設備管理系統的房源房間對接以及設備添加。