ENERGY MANAGEMENT INFORMATION SYSTEM. EMIS Web Service for Sensor Readings. Issue

Transcription

1 ENERGY MANAGEMENT INFORMATION SYSTEM EMIS Web Service for Sensor Readings Issue

2 CONTENTS 1 Overview Communication and Authentication Connecting to the REST Web Service Authentication Web Service Methods Echo Method Echo Request Echo Response Examples Batch Sending Method... Error! Bookmark not defined Batch Request Structure... Error! Bookmark not defined Batch Response Structure... Error! Bookmark not defined Batch-Contained Objects Structure... Error! Bookmark not defined. 3.3 Query Methods... Error! Bookmark not defined Meters Query... Error! Bookmark not defined Readings Query... Error! Bookmark not defined. 3.4 Service Response Codes

3 1 OVERVIEW Various sensors can be installed on the objects, to gather data such as temperature, humidity, pressure, information whether and how much windows are open etc. A sensor can be placed Readings gathered from various sensors can be delivered to the EMIS by a REST Web Service. Messages are in JSON format, sent by HTTP protocol to the URL of the web service method. The HTTP message header should contain a sender s username and a security MAC (Message Authentication Code) value, calculated as a hash of the sent data and the secret pre-shared key. The following data can be exchanged this way: 1. List of all sensor types in the system (reading only new ones should be created through EMIS) 2. List of all sensors (for the current data-supplier. Sensors can be created, retrieved and deleted.) 3. Readings (for a specified sensor. Can be created, retrieved and deleted.) 2

4 2 COMMUNICATION, AUTHENTICATION AND AUTHORIZATION 2.1 Connecting to the REST Web Service HTTP traffic between a client and the URI of the web service must be allowed. In further text SERVICE_URI specifies the base URI of the web service. The messages are in JSON format. In the forthcoming text, Base URI will be specified as SERVICE_URI/json. All the messages should be UTF-8 encoded. 2.2 Authentication The HTTP-Header section of each request must contain the following: Parameter X-Ekonerg-Login X-Ekonerg-MAC Description Data-Supplier username MAC (Message Authentication Code) of the HTTP-Body. Calculated as a SHA-256 digest of the message body combined with a secret pre-shared key, username and method URI (described below) The MAC must be calculated as follows: 1. Instantiate an SHA-256 digest object and initialize with the following bytes: (httpmethod + "\n" + methoduri + "\n" + username + "\n" + password).getbytes(utils.utf8) 2. Calculate digest of the HTTP body using UTF-8 encoding. 3. Encode the digest result as Base64 and set it as a HTTP-Header parameter named X-Ekonerg-MAC 3

5 3 WEB SERVICE METHODS 3.1 General Response Properties These are properties common to all response messages. These properties will be omitted from the forthcoming tables describing specific methods. status Number HTTP response code Standard HTTP response code statusdesc Text HTTP response Standard HTTP response description description ts Timestamp YYYY-MM- Response timestamp DD T HH:mm:ss.SSS serviceurl URL Echoed URL of the service method datasupplierid Text Data supplier ID datasupplierlogin Text Data supplier Login processedentries Number Total number of processed or returned entries successfulentries Number Number of successfully processed entries failedentries Number Number of failed entries err Text Only in case of an error Error code in text format (e.g. TechnicalException ) errdesc Text Only in case of an error Detailed error description errtechnical Boolean Only in case of an error true specifies an error on the server side, false specifies an error caused by invalid request parameters. 4

6 3.2 Echo Method The echo method is used for integration/authentication testing Echo Request Echo Request Properties POST value Text Any string The contents of this string will be returned by the service Echo Response Echo Response Properties status Number HTTP response code Standard HTTP response code statusdesc Text HTTP response Standard HTTP response description description ts Timestamp YYYY-MM- Response timestamp DD T HH:mm:ss.SSS value Text Any text The same value from the echo request serviceurl Text HTTP/S link URL of the service (copied from request) datasupplierid Text userid User ID datasupplierlogin Text userlogin User Login Examples Echo Example Successful0F1 POST X-Ekonerg-MAC: 0zsztndLpk9XxuQetmo9uGWTnNtFu7xHjiWPUQ26iFA= Content-Length: 27 "value" : "Hello, World!" "status": 200, "statusdesc": "OK", "ts": " T15:14:50.628", "serviceurl": " "datasupplierlogin": "test", "value": "blabla" Echo Example Failed Authentication POST 1 HTTP request headers are written in italic. 5

7 X-Ekonerg-MAC: abcd Content-Length: 27 "value" : "Hello, World!" "status": 401, "statusdesc": "Unauthorized", "ts": " T15:39:24.462", "serviceurl": " "datasupplierlogin": "test", "err": "AuthorizationException", "errdesc": "Invalid MAC" 6

8 3.3 Reading Sensor Types This method is used for reading all sensor types registered in the system. It requires no parameters Sensor Types Request Sensor Types Properties GET No parameters Sensor Types Response Sensor Types Response Properties processedentries Number Entries count Number of returned entries sensortypes sensortype[] List of sensor types Sensor Type Properties id Text ID Sensor Type ID name Text Sensor name description Text Sensor description uom Text Unit of measure readingtimetype Text IMMEDATE, INTERVAL Reading type regarding sampling time; IMMEDIATE specifies a momentary value. Besides a value, IMMEDIATE readings will have also a timestamp of the sampling time; INTERVAL is a value for a given interval. Besides a value, INTERVAL readings will have also a timestamp of the start and a timestamp of the end of the reading period Examples Sensor Types Successful0F GET X-Ekonerg-MAC: 0zsztndLpk9XxuQetmo9uGWTnNtFu7xHjiWPUQ26iFA= "status": 200, "statusdesc": "OK", "ts": " T11:22:01.915", "serviceurl": " "processedentries": 3, "datasupplierlogin": "test", "sensortypes": [ "id": "INTTEMP", 7

9 ],, "name": "Internal temperature", "description": "Temperature inside a building", "uom": " C", "readingtimetype": "IMMEDIATE" "id": "PRESSURE", "name": "Pressure", "uom": "bar", "readingtimetype": "IMMEDIATE" "id": "HUMIDITY", "name": "Humidity", "uom": "%", "readingtimetype": "IMMEDIATE" 8

10 3.4 Reading Sensors This method returns all sensors available for a logged-in data supplier Sensors Request Sensor Types Properties GET No parameters Sensors Response Sensor Types Response Properties processedentries Number Entries count Number of returned entries sensors sensor[] List of sensors *see Sensor Properties id Text ID Sensor ID sensortypeid Text Sensor type ID shortdescription Text Sensor description (e.g. Thermometer near the stove ) comment Text Additional comments (longer description, such as Soon to be replaced because of frequent outages ) serialnumber Text Sensor serial number (as specified on a device) datasupplierid Text DataSupplier ID Data supplier which created the sensor objectemiscode Text Object Emis Code ID EMIS code of an object where a sensor is attached permissionreadsensor Boolean Can a user read sensor object permissionwritesensor Boolean Can a user modify sensor object permissionreadsensorreading Boolean Can a user read sensor readings permissionwritesensorreading Boolean Can a user send sensor readings Examples Sensor Types Successful0F GET X-Ekonerg-MAC: 0zsztndLpk9XxuQetmo9uGWTnNtFu7xHjiWPUQ26iFA= "status": 200, "statusdesc": "OK", "ts": " T13:23:50.848", "serviceurl": " "processedentries": 3, "datasupplierid": null, "datasupplierlogin": null, 9

11 "sensors": [,, ] "id": , "sensortypeid": "HUMIDITY", "serialnumber": "asdgasd fkaldf lak;sjdfl;a dkfj ", "objectemiscode": "HR ", "permissionreadsensor": true, "permissionwritesensor": false, "permissionreadsensorreading": true, "permissionwritesensorreading": false "id": , "dsinternalid": "TEST-123", "sensortypeid": "HUMIDITY", "comment": "C3acddy", "shortdescription": "Pero", "serialnumber": "SN_TEST1", "datasupplierid": "TEST", "objectemiscode": "HR ", "permissionreadsensor": true, "permissionwritesensor": false, "permissionreadsensorreading": true, "permissionwritesensorreading": false "id": , "sensortypeid": "HUMIDITY", "serialnumber": "S1", "objectemiscode": "HR ", "permissionreadsensor": true, "permissionwritesensor": false, "permissionreadsensorreading": true, "permissionwritesensorreading": false 10

12 3.5 Creating Sensors This method creates sensors. In order to create a sensor on an object, a user must have a permission to create sensors enabled on the object Create Sensors Request Create Sensors Request Properties POST sensors sensor[] - See above for a sensor definition Create Sensors Response Create Sensors Response Properties processedentries Number Entries count Number of returned entries sensors sensor[] List of sensors *see Sensor Properties id Text ID Sensor ID assigned by EMIS sensortypeid Text Sensor type ID shortdescription Text Sensor description (e.g. Thermometer near the stove ) comment Text Additional comments (longer description, such as Soon to be replaced because of frequent outages ) serialnumber Text Sensor serial number (as specified on a device) datasupplierid Text DataSupplier ID Data supplier which created the sensor objectemiscode Text Object Emis Code ID EMIS code of an object where a sensor is attached permissionreadsensor Boolean Can a user read sensor object permissionwritesensor Boolean Can a user modify sensor object permissionreadsensorreading Boolean Can a user read sensor readings permissionwritesensorreading Boolean Can a user send sensor readings err Text Error code. If present, then adding a sensor has failed. In that case, errdesc contains more detailed description of the cause. errdesc Text If present, then adding a sensor has failed. In that case, errdesc contains more detailed description of the cause Examples Creating a Sensor Successful POST X-Ekonerg-MAC: 0zsztndLpk9XxuQetmo9uGWTnNtFu7xHjiWPUQ26iFA= 11

13 "sensors": [ "dsinternalid": "TEST-T1", "sensortypeid": "INTTEMP", "serialnumber": "SN_TEMP_1", "objectemiscode": "HR " ] "status": 200, "statusdesc": "OK", "ts": " T13:37:23.389", "serviceurl": " "processedentries": 1, "datasupplierlogin": "test", "successfulentries": 1, "failedentries": 0, "sensors": [ "id": , "dsinternalid": "TEST-T1", "permissionreadsensor": true, "permissionwritesensor": true, "permissionreadsensorreading": true, "permissionwritesensorreading": true ] Creating a Sensor one OK, and one failed (because of a duplicate ID) POST X-Ekonerg-MAC: 0zsztndLpk9XxuQetmo9uGWTnNtFu7xHjiWPUQ26iFA= "sensors": [ "dsinternalid": "TEST-T9", "sensortypeid": "INTTEMP", "serialnumber": "SN_TEMP_9", "objectemiscode": "HR ", "dsinternalid": "TEST-T9", "sensortypeid": "INTTEMP", "serialnumber": "SN_TEMP_10", "objectemiscode": "HR " ] "status": 207, "statusdesc": "Multi-Status", "ts": " T11:34:05.898", "serviceurl": " "processedentries": 2, "datasupplierlogin": "test", "successfulentries": 1, "failedentries": 1, "sensors": [ "id": , "dsinternalid": "TEST-T9", "dsinternalid": "TEST-T9", "sensortypeid": "INTTEMP", "serialnumber": "SN_TEMP_10", 12

14 ] "objectemiscode": "HR ", "permissionreadsensor": true, "permissionwritesensor": true, "permissionreadsensorreading": true, "permissionwritesensorreading": true, "err": "SQLIntegrityConstraintViolationException", "errdesc": "Internal datasupplierid must be unique", "ts": " T11:34:07.460" 13

15 3.6 Deleting a Sensor This method deletes a specified sensor. In order to delete a sensor on an object, a user must have a permission to create sensors enabled on the object, AND there must be no readings on the sensor. So, before deleting a sensor, all its readings must be deleted first Delete Sensor Request Delete Sensor Request Properties DELETE Delete Sensor Response Delete Sensor Response Properties processedentries Number Entries count Number of deleted entries Examples Deleting a Sensor Successful DELETE X-Ekonerg-MAC: 0zsztndLpk9XxuQetmo9uGWTnNtFu7xHjiWPUQ26iFA= "status": 200, "statusdesc": "OK", "ts": " T13:37:23.389", "serviceurl": " "processedentries": 1, "datasupplierlogin": "test", "successfulentries": 1, "failedentries": 0, "sensors": [ "id": , "dsinternalid": "TEST-T1", "permissionreadsensor": true, "permissionwritesensor": true, "permissionreadsensorreading": true, "permissionwritesensorreading": true ] 14

16 3.7 Sending Readings This method sends one or more readings for one or more different sensors. In order to send a reading, a user must have a permission to write readings on that sensor Send Readings Request Send Readings Request Properties POST readings reading[] - See above for a sensor definition Send Readings Response Send Readings Response Properties processedentries Number Entries count Number of returned entries readings reading[] Failed Readings Only when there was an error, returns only a list of failed readings. Reading Properties date Timestamp YYYY-MM- Reading timestamp. Mandatory. DD T HH:mm:ss dateto Timestamp YYYY-MM- Reading timestamp. Only for interval readings. DD T HH:mm:ss sensorid Number Sensor ID (EMIS ID) value Decimal Sensor value Examples Sending Readings Successful POST X-Ekonerg-MAC: 0zsztndLpk9XxuQetmo9uGWTnNtFu7xHjiWPUQ26iFA= "readings": [ "date": " T13:00:00", "sensorid": "179897", "value": "22.1", "date": " T13:10:00", "sensorid": "179897", "value": "22.4", "date": " T13:20:00", "sensorid": "179897", "value": "22.3" ] "status": 200, "statusdesc": "OK", 15

17 "ts": " T16:06:35.586", "serviceurl": " "processedentries": 3, "successfulentries": 3, "failedentries": 0, "datasupplierlogin": "test" Sending Readings two OK, and one failed (because of a duplicate time+sensor) POST X-Ekonerg-MAC: 0zsztndLpk9XxuQetmo9uGWTnNtFu7xHjiWPUQ26iFA= "readings": [ "date": " T13:20:00", "sensorid": "179897", "value": "22.3", "date": " T13:30:00", "sensorid": "179897", "value": "22.5", "date": " T13:40:00", "sensorid": "179897", "value": "22.5" ] "status": 207, "statusdesc": "Multi-Status", "ts": " T16:08:20.202", "serviceurl": " "processedentries": 3, "successfulentries": 2, "failedentries": 1, "datasupplierlogin": "test", "readings": [ "sensorid": , "date": " T13:20:00", "value": 22.3, "err": "SQLIntegrityConstraintViolationException", "errdesc": "Reading date on sensor must be unique", "ts": " T16:08:20.365" ] 16

18 3.8 Retrieving Readings This method fetches previous readings for one or more different sensors. In order to send a reading, a user must have a permission to write readings on that sensor Retrieve Readings Request Send Readings Request Properties GET month] sensorid Number Mandatory Sensor ID (EMIS ID) year Number Mandatory Year for the readings month Number Optional, 1-12 Optional month for the readings Retrieve Readings Response Retrieve Readings Response Properties processedentries Number Entries count Number of returned entries readings reading[] Returned reading entries. See above for description of reading Examples Sending Readings Successful GET X-Ekonerg-MAC: 0zsztndLpk9XxuQetmo9uGWTnNtFu7xHjiWPUQ26iFA= "status": 200, "statusdesc": "OK", "ts": " T14:01:15.985", "serviceurl": " "processedentries": 6, "datasupplierlogin": "test", "sensorreadings": [ "sensorid": , "date": " T12:00:00", "value": 22.1, "datasupplierid": "TEST", "sensorid": , "date": " T13:00:00", "value": 22.1, "datasupplierid": "TEST", "sensorid": , "date": " T13:10:00", "value": 22.4, "datasupplierid": "TEST", "sensorid": , "date": " T13:20:00", "value": 22.3, "datasupplierid": "TEST", "sensorid": , "date": " T13:30:00", 17

19 ], "value": 22.5, "datasupplierid": "TEST" "sensorid": , "date": " T13:40:00", "value": 22.5, "datasupplierid": "TEST" 18

20 3.9 Deleting Readings This method deletes readings of a specified sensor, in a given period Delete Readings Request Delete Sensor Request Properties DELETE sensorid Number - Sensor ID fromdate Date yyyy-mm-dd't'hh:mm:ss Start date (inclusive) todate Date yyyy-mm-dd't'hh:mm:ss To date (inclusive) Delete Sensor Response Delete Sensor Response Properties processedentries Number Entries count Number of deleted readings Examples Deleting Readings Successful DELETE X-Ekonerg-MAC: 0zsztndLpk9XxuQetmo9uGWTnNtFu7xHjiWPUQ26iFA= "status": 200, "statusdesc": "OK", "ts": " T16:23:14.909", "serviceurl": " "datasupplierlogin": "test", "processedentries": 4, "successfulentries": 4 19

21 3.10 Service Response Codes These are standard HTTP responses that the service may return in its status and statusdesc : Service Response Codes Code Text Description 200 OK Request was successfully processed 207 Multi-Status Some or all items could not have been processed due to some business reasons 400 Bad Request Malformed request 401 Unauthorized The MAC or username were invalid 500 Internal Server Error An error on the server side occurred In case of an error, the service returns a HTTP response code as specified above, and the body of the HTTP response contains a service response object, with the exception of errors returned by layers other than the service (e.g. firewalls or connection timeouts), where the response object cannot be returned. Error Response Example1F2 HTTP/ Unauthorized Server: nginx Date: Mon, 30 Sep :26:29 CEST Content-Type: text/html; charset=utf-8 Cache-Control: no-cache Pragma: no-cache "status":401,"statusdesc":"unauthorized","ts":" T15:26:29.926","err":"AuthorizationException","errDesc":"Invalid MAC", "serviceurl ":" datasupplierid="test" datasupplierlogin="test" XML Response HTTP/ Unauthorized Server: nginx Date: Mon, 30 Sep :26:29 CEST Content-Type: text/html; charset=utf-8 Cache-Control: no-cache Pragma: no-cache <response xmlns=" status="401" statusdesc="unauthorized" ts=" t15:29:23.664" err="authorizationexception" errdesc="invalid MAC" serviceurl=" " datasupplierid="test" datasupplierlogin="test"/> Change Log Initial version 2 HTTP response header is marked italic. 20