四、電表管理 · 云丁Saas管理系統openAPI快速開始

云丁Saas系統openAPI提供了豐富的電表管理接口，本章介紹常用的接口，并且使用它們實現常見的電表管理功能。如：電表詳情頁面展示，計算電筆當前剩余電量，電表異常記錄頁面展示等。 # 4.1 電表管理接口實現本節將實現電表管理的基礎功能，如：設置付費模式（set\_room\_pay\_type），獲取電表詳情（get\_elemeter\_info），獲取電表用電記錄（含公攤）（elemeter\_fetch\_power\_history\_with\_pool），獲取電表操作記錄（search_device_op_log）, 獲取電表異常記錄(device_fetch_exceptions)。具體實現：在apis文件夾下新建elemeter.py, vim elemeter.py. ``` import requests def set_room_pay_type(access_token, uuid, pay_type): ''' 設置房間付費模式 :param access_token: 調用接口憑證 :param uuid: 電表設備uuid, 唯一 :param pay_type: 付費類型 1：預付費 2：后付費 ''' url = 'https://saas-openapi.dding.net/v2/set_room_pay_type' headers = { 'Content-type': 'Application/json', 'User-Agent': 'PostmanRuntime/7.13.0', } payload = { 'access_token': access_token, 'uuid': uuid, 'pay_type': pay_type } response = requests.request('POST', url, headers=headers, json=payload) return response.json() def get_elemeter_info(access_token, home_id, uuid): ''' 獲取電表詳情 :param access_token: 調用接口憑證 :param home_id: 電表所在房源id :param uuid: 電表設備的uuid ''' url = 'https://saas-openapi.dding.net/v2/get_elemeter_info' headers = { 'Content-type': 'Application/json', 'User-Agent': 'PostmanRuntime/7.13.0', } query_string = { 'access_token': access_token, 'home_id': home_id, 'uuid': uuid } response = requests.request('GET', url, headers=headers, params=query_string) return response.json() def elemeter_fetch_power_history_with_pool(access_token, home_id, uuid): ''' 獲取電表用電記錄（含公攤） :param access_token: 調用接口憑證 :param home_id: 電表所在房源id :param uuid: 電表設備的uuid ''' url = 'https://saas-openapi.dding.net/v2/elemeter_fetch_power_history_with_pool' headers = { 'Content-type': 'Application/json', 'User-Agent': 'PostmanRuntime/7.13.0', } query_string = { 'access_token': access_token, 'home_id': home_id, 'uuid': uuid } response = requests.request('GET', url, headers=headers, params=query_string) return response.json() def search_elemeter_op_log(access_token, uuid): ''' 查詢電表操作記錄 :param access_token: :param uuid: :return: ''' url = 'https://saas-openapi.dding.net/v2/search_device_op_log' headers = { 'Content-type': 'Application/json', 'User-Agent': 'PostmanRuntime/7.13.0', } query_string = { 'access_token': access_token, 'uuid': uuid } response = requests.request('GET', url, headers=headers, params=query_string) return response.json() def elemeter_fetch_exceptions(access_token, uuid): ''' 電表異常記錄獲取 :param access_token: 接口調用憑證 :param uuid: 電表設備uuid ''' url = 'https://saas-openapi.dding.net/v2/device_fetch_exceptions' headers = { 'Content-type': 'Application/json', 'User-Agent': 'PostmanRuntime/7.13.0', } query_string = { 'access_token': access_token, 'uuid': uuid } response = requests.request('GET', url, headers=headers, params=query_string) return response.json() ``` 實現接口函數后，新建elemeter_model.py, 實現Elemeter類的定義以及相關實例方法。vim elemeter_model.py ``` from apis.elemeter import set_room_pay_type, get_elemeter_info, elemeter_fetch_exceptions, \ elemeter_fetch_power_history_with_pool, search_elemeter_op_log class Elemeter: def __init__(self, access_token, uuid): self.access_token = access_token self.uuid = uuid def set_room_pay_type(self, pay_type): res = set_room_pay_type(self.access_token, self.uuid, pay_type) return res def get_elemeter_info(self, home_id): res = get_elemeter_info(self.access_token, home_id, self.uuid) return res def elemeter_fetch_power_history_with_pool(self, home_id): res = elemeter_fetch_power_history_with_pool(self.access_token, home_id, self.uuid) return res def search_elemeter_op_log(self): res = search_elemeter_op_log(self.access_token, self.uuid) return res def elemeter_fetch_exceptions(self): res = elemeter_fetch_exceptions(self.access_token, self.uuid) return res ``` # 4.2 電表詳情頁面展示這一節實現電表詳情頁面展示，vim main.py ``` from elemeter_model import Elemeter def main(): access_token = 'xxxxxxxxxxx' #請填寫商戶賬號的access_token uuid = 'f0a0c5abd9769ebe2efae3e27a5fbea7' home_id = 'cadc71cb-6dec-4155-8ddb-4e99ae8f9f5a' elemeter = Elemeter(access_token, uuid) res = elemeter.get_elemeter_info(home_id) print(res) if __name__ == '__main__': main() ``` 先實例化電表，然后使用get_elemeter_info實例化方法，獲取該電表的詳情。返回結果如下：包括電表版本信息，信號值等等基本信息。可以將其展示給前端。 ``` { "ReqID": "1SSFPZJWbyf", "ErrNo": 0, "ErrMsg": "成功", "sn": "190215103584", "uuid": "f0a0c5abd9769ebe2efae3e27a5fbea7", "versions": { "elemeter_potocol_version": "07", "elemeter_potocol_type": "01" }, "name": "北川電表", "power": -1, "status": 1, "model": "DDSU1225", "model_name": "A1P", "onoff_line": 1, "onoff_time": 1567395901032, "time": 1563628490452, "bind_time": 1563628490641, "overdraft": 0, "overdraft_time": 1567408957336, "capacity": 14.52, "capacity_time": 1567408957336, "consume_amount": 314.34, "consume_amount_time": 1567407600000, "power_total": 0, "power_total_time": 1567408957336, "enable_state": 1, "enable_state_time": 1564632109395, "charge_stage": 3, "overdraft_stage": 3, "capacity_stage": 3, "trans_status": 1, "trans_status_time": 1566478811023, "switch_stage": 3, "switch_stage_time": 1567408957336, "control_switch": 1, "syn_stage_time": 1567408957336, "syn_stage": 3, "reset_stage_time": 1564648064289, "reset_stage": 3, "elecollector_uuid": "bc516a8cb656de8a33aa2c6b4bc8ce70" } ``` # 4.3 計算電表當前剩余電量電費的計量涉及幾個概念需要先了解：電表的付費模式分為**預付費**和**后付費**。不同的付費模式所需要調用的接口也是不同的，需要根據自己公司的業務確定付費模式。 **預付費**：即先付費后用電，主要涉及剩余電量計算等。 **后付費**：先用電后結算，由于不涉及費控，其主要涉及電表用電量的獲取等。 **公攤**：即將公共區間的用電量分攤給各房間用電量。本節的示例采用預付費的方式。當房間付費模式為預付費，并且開啟開啟公攤后，此時可通過elemeter\_fetch\_power\_history\_with\_pool接口獲取用電記錄。并且剩余電量的計算公式為： left = total\_amount - consume\_amount + charge\_pooling\_amount - pooling\_amount。 total_amont : 房間充值電量 consume_amount:房間用電量 charge_pooling_amount:公攤充值電量 pooling_amount:公攤用電量具體的代碼示例：vim main.py ``` from elemeter_model import Elemeter def main(): access_token = 'xxxxxxxxxxxxxxxx' #請填寫商戶自己的access_token uuid = 'f0a0c5abd9769ebe2efae3e27a5fbea7' home_id = 'cadc71cb-6dec-4155-8ddb-4e99ae8f9f5a' elemeter = Elemeter(access_token, uuid) # res = elemeter.get_elemeter_info(home_id) res = elemeter.elemeter_fetch_power_history_with_pool(home_id) print(res) if __name__ == '__main__': main() ``` 返回結果如下：history字段中含有該電表的用電量歷史記錄，可以根據該數據進行房間用電量展示以及剩余電量的計算。 ``` { "ReqID": "1SSIpPIQpOB", "ErrNo": 0, "ErrMsg": "", "history": [ { "home_id": "5d2949817c83c22451d14263", "room_id": "5d2949f7039d2a2452555664", "consume_amount": 314.34, "pooling_amount": 0, "total_amount": 0, "charge_pooling_amount": 0, "time": 1567407600000, "date": "2019-09-02", "uuid": "f0a0c5abd9769ebe2efae3e27a5fbea7" }, { "home_id": "5d2949817c83c22451d14263", "room_id": "5d2949f7039d2a2452555664", "consume_amount": 314.34, "pooling_amount": 0, "total_amount": 0, "charge_pooling_amount": 0, "time": 1567404000000, "date": "2019-09-02", "uuid": "f0a0c5abd9769ebe2efae3e27a5fbea7" }, { "home_id": "5d2949817c83c22451d14263", "room_id": "5d2949f7039d2a2452555664", "consume_amount": 314.34, "pooling_amount": 0, "total_amount": 0, "charge_pooling_amount": 0, "time": 1567400400000, "date": "2019-09-02", "uuid": "f0a0c5abd9769ebe2efae3e27a5fbea7" }, { "home_id": "5d2949817c83c22451d14263", "room_id": "5d2949f7039d2a2452555664", "consume_amount": 314.33, "pooling_amount": 0, "total_amount": 0, "charge_pooling_amount": 0, "time": 1567396800000, "date": "2019-09-02", "uuid": "f0a0c5abd9769ebe2efae3e27a5fbea7" }, { "home_id": "5d2949817c83c22451d14263", "room_id": "5d2949f7039d2a2452555664", "consume_amount": 314.33, "pooling_amount": 0, "total_amount": 0, "charge_pooling_amount": 0, "time": 1567393200000, "date": "2019-09-02", "uuid": "f0a0c5abd9769ebe2efae3e27a5fbea7" }, { "home_id": "5d2949817c83c22451d14263", "room_id": "5d2949f7039d2a2452555664", "consume_amount": 314.33, "pooling_amount": 0, "total_amount": 0, "charge_pooling_amount": 0, "time": 1567389600000, "date": "2019-09-02", "uuid": "f0a0c5abd9769ebe2efae3e27a5fbea7" }, { "home_id": "5d2949817c83c22451d14263", "room_id": "5d2949f7039d2a2452555664", "consume_amount": 314.32, "pooling_amount": 0, "total_amount": 0, "charge_pooling_amount": 0, "time": 1567386000000, "date": "2019-09-02", "uuid": "f0a0c5abd9769ebe2efae3e27a5fbea7" }, { "home_id": "5d2949817c83c22451d14263", "room_id": "5d2949f7039d2a2452555664", "consume_amount": 314.32, "pooling_amount": 0, "total_amount": 0, "charge_pooling_amount": 0, "time": 1567382400000, "date": "2019-09-02", "uuid": "f0a0c5abd9769ebe2efae3e27a5fbea7" }, { "home_id": "5d2949817c83c22451d14263", "room_id": "5d2949f7039d2a2452555664", "consume_amount": 314.32, "pooling_amount": 0, "total_amount": 0, "charge_pooling_amount": 0, "time": 1567378800000, "date": "2019-09-02", "uuid": "f0a0c5abd9769ebe2efae3e27a5fbea7" }, { "home_id": "5d2949817c83c22451d14263", "room_id": "5d2949f7039d2a2452555664", "consume_amount": 314.31, "pooling_amount": 0, "total_amount": 0, "charge_pooling_amount": 0, "time": 1567375200000, "date": "2019-09-02", "uuid": "f0a0c5abd9769ebe2efae3e27a5fbea7" }, { "home_id": "5d2949817c83c22451d14263", "room_id": "5d2949f7039d2a2452555664", "consume_amount": 314.31, "pooling_amount": 0, "total_amount": 0, "charge_pooling_amount": 0, "time": 1567371600000, "date": "2019-09-02", "uuid": "f0a0c5abd9769ebe2efae3e27a5fbea7" }, { "home_id": "5d2949817c83c22451d14263", "room_id": "5d2949f7039d2a2452555664", "consume_amount": 314.31, "pooling_amount": 0, "total_amount": 0, "charge_pooling_amount": 0, "time": 1567368000000, "date": "2019-09-02", "uuid": "f0a0c5abd9769ebe2efae3e27a5fbea7" }, { "home_id": "5d2949817c83c22451d14263", "room_id": "5d2949f7039d2a2452555664", "consume_amount": 314.3, "pooling_amount": 0, "total_amount": 0, "charge_pooling_amount": 0, "time": 1567364400000, "date": "2019-09-02", "uuid": "f0a0c5abd9769ebe2efae3e27a5fbea7" }, { "home_id": "5d2949817c83c22451d14263", "room_id": "5d2949f7039d2a2452555664", "consume_amount": 314.3, "pooling_amount": 0, "total_amount": 0, "charge_pooling_amount": 0, "time": 1567360800000, "date": "2019-09-02", "uuid": "f0a0c5abd9769ebe2efae3e27a5fbea7" }, { "home_id": "5d2949817c83c22451d14263", "room_id": "5d2949f7039d2a2452555664", "consume_amount": 314.3, "pooling_amount": 0, "total_amount": 0, "charge_pooling_amount": 0, "time": 1567357200000, "date": "2019-09-02", "uuid": "f0a0c5abd9769ebe2efae3e27a5fbea7" }, { "home_id": "5d2949817c83c22451d14263", "room_id": "5d2949f7039d2a2452555664", "consume_amount": 314.29, "pooling_amount": 0, "total_amount": 0, "charge_pooling_amount": 0, "time": 1567353600000, "date": "2019-09-02", "uuid": "f0a0c5abd9769ebe2efae3e27a5fbea7" } ] } ``` # 4.4 異常記錄頁面展示本節演示獲取用戶異常記錄，vim main.py ``` from elemeter_model import Elemeter def main(): access_token = 'xxxxxxxxxxxxxxxxxxx' #請填寫商戶自己的access_token uuid = 'f0a0c5abd9769ebe2efae3e27a5fbea7' home_id = 'cadc71cb-6dec-4155-8ddb-4e99ae8f9f5a' elemeter = Elemeter(access_token, uuid) # res = elemeter.get_elemeter_info(home_id) # res = elemeter.elemeter_fetch_power_history_with_pool(home_id) res = elemeter.elemeter_fetch_exceptions() print(res) if __name__ == '__main__': main() ``` 返回的結果如下：device_exceptions字段中含有該電表的異常記錄，可以將其發送給前端進行異常記錄頁面展示。 ``` ~~~ { "ReqID": "1SSQr1vNHoI", "ErrNo": 0, "ErrMsg": "", "device_exceptions": [ { "client_id": 100041, "device_type": "elemeter", "home_id": "cadc71cb-6dec-4155-8ddb-4e99ae8f9f5a", "time": 1567128030000, "type": 1007, "uuid": "f0a0c5abd9769ebe2efae3e27a5fbea7" }, { "client_id": 100041, "device_type": "elemeter", "home_id": "cadc71cb-6dec-4155-8ddb-4e99ae8f9f5a", "time": 1567042655000, "type": 1006, "uuid": "f0a0c5abd9769ebe2efae3e27a5fbea7" }, { "client_id": 100041, "device_type": "elemeter", "home_id": "cadc71cb-6dec-4155-8ddb-4e99ae8f9f5a", "time": 1566634238000, "type": 1007, "uuid": "f0a0c5abd9769ebe2efae3e27a5fbea7" }, { "client_id": 100041, "device_type": "elemeter", "home_id": "cadc71cb-6dec-4155-8ddb-4e99ae8f9f5a", "time": 1566633785000, "type": 1006, "uuid": "f0a0c5abd9769ebe2efae3e27a5fbea7" }, { "client_id": 100041, "device_type": "elemeter", "home_id": "cadc71cb-6dec-4155-8ddb-4e99ae8f9f5a", "time": 1566470154000, "type": 1007, "uuid": "f0a0c5abd9769ebe2efae3e27a5fbea7" }, { "client_id": 100041, "device_type": "elemeter", "home_id": "cadc71cb-6dec-4155-8ddb-4e99ae8f9f5a", "time": 1566469791000, "type": 1006, "uuid": "f0a0c5abd9769ebe2efae3e27a5fbea7" }, { "client_id": 100041, "device_type": "elemeter", "home_id": "cadc71cb-6dec-4155-8ddb-4e99ae8f9f5a", "time": 1566465006000, "type": 1007, "uuid": "f0a0c5abd9769ebe2efae3e27a5fbea7" }, { "client_id": 100041, "device_type": "elemeter", "home_id": "cadc71cb-6dec-4155-8ddb-4e99ae8f9f5a", "time": 1566464914000, "type": 1006, "uuid": "f0a0c5abd9769ebe2efae3e27a5fbea7" }, { "client_id": 100041, "device_type": "elemeter", "home_id": "cadc71cb-6dec-4155-8ddb-4e99ae8f9f5a", "time": 1566311201000, "type": 1007, "uuid": "f0a0c5abd9769ebe2efae3e27a5fbea7" }, { "client_id": 100041, "device_type": "elemeter", "home_id": "cadc71cb-6dec-4155-8ddb-4e99ae8f9f5a", "time": 1566309285000, "type": 1006, "uuid": "f0a0c5abd9769ebe2efae3e27a5fbea7" }, { "client_id": 100041, "device_type": "elemeter", "home_id": "cadc71cb-6dec-4155-8ddb-4e99ae8f9f5a", "time": 1564632109000, "type": 2014, "uuid": "f0a0c5abd9769ebe2efae3e27a5fbea7" }, { "client_id": 100041, "device_type": "elemeter", "home_id": "cadc71cb-6dec-4155-8ddb-4e99ae8f9f5a", "time": 1564560012000, "type": 2003, "uuid": "f0a0c5abd9769ebe2efae3e27a5fbea7" }, { "client_id": 100041, "device_type": "elemeter", "home_id": "cadc71cb-6dec-4155-8ddb-4e99ae8f9f5a", "time": 1564557239000, "type": 1007, "uuid": "f0a0c5abd9769ebe2efae3e27a5fbea7" }, { "client_id": 100041, "device_type": "elemeter", "home_id": "cadc71cb-6dec-4155-8ddb-4e99ae8f9f5a", "time": 1563629395000, "type": 1006, "uuid": "f0a0c5abd9769ebe2efae3e27a5fbea7" } ] } ``` # 4.5 小結本章通過幾個簡單的例子說明了常見的電表管理功能的實現。云丁Saas系統openAPI關于電表管理提供了豐富的接口，其使用方法也大同小異。開發者可根據需求自行對其進行組合。