拿到access_token之后，我們便可以進行自己的系統開發了。本章節將以一個實際的例子快速實現房源房間添加，工單添加，設備安裝以及設備綁定。 # 2.1 系統開發過程 云丁智能設備管理是基于**房源**為單位的，對應于現實生活中的房源模型。具體說來就是在一個房源中創建房間，然后將相應的智能網關，智能門鎖，智能采集器，智能電表和智能水表等添加到對應的房間。 而房源模型的建立，房間的建立以及智能設備添加，到智能設備的管理都遵循著固定的順序。主要是**添加房源** —> **添加房間 **—> **添加新裝工單** —> **云丁交付上門安裝與綁定設備** —> **房間設備添加成功** —> **智能設備管理**。 本章節將按照該步驟快速創建一個包含公區和一個房間的房源，并且在公區和房間分別添加一把門鎖和一個電表。 # 2.2 項目的建立 創建項目，代碼的結構如下：  **注意**：由于本文檔的目的是讓開發者快速了解與云丁系統對接的操作流程，因此房源數據結構采用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() ~~~ # 2.3 房源房間的建立 新建房源模型, 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)等方法。 接下來創建房源， 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! ``` # 2.4 創建房間 我們在剛剛創建的房源home上，使用add_home方法添加房間，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': ''} ``` # 2.5 添加工單 接著我們使用add_ticket方法添加工單，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.6 事件回調與主動輪詢 當添加完工單后，云丁交付團隊便會根據工單前往現場安裝綁定設備，那么我們得知設備已經綁定成功，可以進行管理了呢？主要是兩種方式：事件回調與主動輪詢。 具體說明之前，先解釋下**事件**。當我們對只能設備進行操作時，由于網絡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字段已經有綁定的設備了。后面還需要安裝新設備也是采用相同的方法。