Nescloud API tiene la siguiente estructura de recursos y métodos:
- /auth/validate (POST)
- /networks (GET)
- /sensordata (GET)
- /get-expert-knowledge (POST)
A continuación, se describen los cuatro recursos:
/auth/validate
Este recurso tiene un único método POST que permite obtener a un usuario el token asociado a su cuenta.
Este token es imprescindible para el resto de llamadas a la API. El token determina si el usuario puede acceder a la información que se pide en la llamada. Si las credenciales suministradas son correctas, el parámetro login_status del response body será True. De lo contrario este parámetro será False.
URL: https://data.nescloud.net/auth/validate
El request body debe tener el siguiente formato:
{
"username": "user@mail.com",
"password": "foo"
}
Siendo username y password las credenciales de usuario de la plataforma Nescloud.
La llamada necesita de un request header: “x-api-key“. Este header debe contener una API Key válida. La API Key se debe solicitar a Nespra.
Si las credenciales son válidas, esta llamada devuelve el ID del usuario, su nombre y apellidos, las organizaciones a las que tiene acceso y sus IDs, el token para poder realizar el resto de llamadas a la API y cuando expira el token dado:
[
{
"login_status": true,
"user_id": 65,
"first_name": "app",
"last_name": "movil",
"organizations": [
{
"id": 2,
"name": "Nespra Demo"
}
],
"api_token": "L5S6FzpgslWuBhRsKQfRx4rTXKXwQst-XV6oOKvTVGs",
"expiration_time": 1596105471
}
]
/networks
Este recurso tiene un único método GET que permite obtener la información de los Nesgates, Nesmotes, alarmas y alertas de una organización.
URL: https://data.nescloud.net/networks
Este método requiere de un solo query parameter:
- organisation_id: Solo se cogerá la información de las redes de la organización especificada. Nótese que el token suministrado a la llamada debe pertenecer a un usuario de la organización, de lo contrario la llamada devolverá un error conforme no se puede acceder a los datos.
De cara a identificar y autorizar esta llamada, también son necesarios dos request headers:
- “x-api-key“ : Este header debe contener una API Key de AWS válida.
- “Authorization“ : En este header se ha de poner el “api_token” devuelto por el método /auth/validate
La respuesta a esta llamada tiene el formato:
[
{
"name": "Sevilla",
"id": 7,
"nesgates": [
{
"id": 5,
"device_status": 1,
"device_name": "Santiago",
"deveui": "nespra_demo",
"name_model": "NG-ENTERPRISE-LTE-868-EU-GB",
"public_ip": "",
"connectivity": "ETHERNET",
"tx_total": 0,
"timezone": "Europe/Madrid",
"gps_longitude": -0.3276027143,
"gps_latitude": 39.4622116089
}
],
"nesmotes": [
{
"device_status": 1,
"id": 6,
"device_name": "Ascensor 0003",
"deveui": "34-35-31-31-74-37-78-11",
"name_model": "NM-11-HW",
"parent_id": 5,
"gps_longitude": -0.3280189037,
"gps_latitude": 39.4621582031,
"parent_name": "Santiago",
"sensor_labels": [
"AI1",
"AI2",
"AI3",
"AI4"
],
"sensor_types": [
"Conductividad",
"Nivel",
"pH",
"Caudal"
],
"units": [
"uS/cm",
"m",
"pH",
"m3/h"
]
},
{
"device_status": 1,
"id": 7,
"device_name": "Ascensor 0004",
"deveui": "70-b3-d5-7b-a0-00-17-ab",
"name_model": "NM-WS11",
"parent_id": 5,
"gps_longitude": -0.3280189037,
"gps_latitude": 39.4621582031,
"parent_name": "Santiago",
"sensor_labels": [
"precipitation",
"wind_speed",
"temperature",
"pressure",
"humidity"
],
"sensor_types": [
"precipitation",
"wind speed",
"Temperature",
"Pressure",
"Humidity"
]
}
],
"sensors": 9,
"number_of_alerts": 1,
"number_of_alarms": 2,
"alerts": [],
"alarms": []
}
]
/sensordata
Este recurso tiene un único método GET que permite obtener la información de los sensores de un Nesmote.
Los parámetros de la query son:
- “deveui” es el DevEUI del Nesmote, y ha de pertenecer a la organización del usuario. Dependiendo del rol del usuario, también será necesario que el Nesmote pertenezca a una de las networks que el usuario puede ver. El formato de este dato se puede ver en la foto de arriba, no hace falta poner comillas.
- “t0” define el instante inicial de adquisición de datos. Debe ser dado como UNIX timestamp tal como se ve en la foto de arriba. No puede ser mayor que “t1”.
- “t1” define el instante final de adquisición de datos. Debe ser dado como UNIX timestamp tal como se ve en la foto de arriba. No puede ser menor que “t0”. El intervalo de tiempo entre “t0” y “t1” no puede ser mayor a 180 días.
- “sensor_labels“ define los sensores de los cuales queremos obtener la información. Debe darse con el formato que se puede observar en la foto de arriba, cada nombre de sensor ha de estar separado por una coma (e.g DO1, AI1).
- “hourly“ define si queremos buscar en la base de datos horaria o no. Este parámetro es opcional, si no se define, por defecto se pillan los datos de la base de datos normal. Para obtener datos de la base de datos horaria, “hourly” debe ser True.
- "ig_module" se especifica cuando se solicitan los datos de un dispositivo IG. Las opciones son "mip", "rtu", "ai" y "di".
- "ip_host" determina la ip al que se le solicita la información cuando se trata de pedir datos de modbus.
- "port" define el puerto al que se le solicita la información cuando se trata de pedir datos de modbus.
La llamada necesita de dos request headers:
- “x-api-key“. Este header debe contener una API Key de AWS válida
- “Authorization“ : En este header se ha de poner el “api_token” devuelto por el método /auth/validate
Si el usuario asociado al token tiene visibilidad del Nesmote porque está en su organización y su rol lo permite ver, entonces se devolverán los datos de los sensores, de lo contrario se notificará al usuario en la respuesta que ese token no permite ver los sensores del Nesmote dado.
La respuesta de esta llamada tiene el siguiente formato con “hourly a False, donde el TimeStamp está en formato UNIX en segundos:
[
{
"TimeStamp": 1601480532,
"AI2": 36.274,
"AI1": 11.004
},
{
"TimeStamp": 1601480592,
"AI2": 37.852,
"AI1": 10.993
}
]
En caso de que “hourly esté a True:
[
{
"yymmddhh": 20051908,
"AI2": 36.274,
"AI1": 11.004
},
{
"yymmddhh": 20051909,
"AI2": 37.852,
"AI1": 10.993
}
]
En este último caso “yymmddhh” hace referencia al año, mes, día y hora.
/get-expert-knowledge
En este caso la llamada necesita los mismos dos request headers que en el recurso anterior:
- “x-api-key“. Este header debe contener una API Key de AWS válida
- “Authorization“ : En este header se ha de poner el “api_token” devuelto por el método /auth/validate
El request body debe tener el siguiente formato:
{
"dict_with_info":{
"dev-eui-1":{
"sensor_data":{
"sensor-label-1":{
"x_array":["1682330002"],
"y_array":["448"]
}
}
},
"dev-eui-2":{
"sensor_data":{
"sensor-label-1":{
"x_array":["1682330002"],
"y_array":["57.86"]
}
}
}
}
}
La respuesta debe tener el siguiente formato:
{
"dev-eui-1_sensor-label-1": {
"status_color_array": [
"#008000"
],
"status_text_array": [
"EXCELENTE"
]
},
"dev-eui-2_sensor-label-1": {
"status_color_array": [
"#008000"
],
"status_text_array": [
"BUENO"
]
}
}
donde se devuelve para cada sensor, el color y el texto del conocimiento experto en unos arrays en el mismo orden en el que se hayan solicitado en el body durante el request.