Este artículo es un ejemplo paso a paso para utilizar la API de inserción para introducir datos en un concentrador usando Postman para las peticiones HTTP.
¿Qué es una API de inserción?
API viene del inglés Application Programming Interface (Interfaz de programación de aplicaciones). Es una interfaz de computación que permite interacciones entre múltiples programas informáticos intermediarios, como los sitios web o webapps interactuando entre sí.
Una API de inserción de datos es una API que permite que se le envíen datos, de modo que se procesa y es accesible en una aplicación web, como la plataforma EM.
La API de inserción permite a otros sistemas enviar datos a través de Internet a la plataforma usando el protocolo HTTP.
Puedes conocer las diferentes formas de enviar datos a la plataforma aquí.
Puedes encontrar más información sobre las API aquí.
Requisitos
Para poder insertar los datos, primero necesitas algunas cosas:
En el lado de la plataforma EMS
- Permisos de administrador o super-administrador.
De tu lado
- Necesitarás una aplicación que pueda gestionar las solicitudes HTTP. En este tutorial, usaremos Postman, que es de uso libre.
- Deberías tener un conocimiento básico de cómo funcionan las peticiones HTTP.
- Necesitarás preparar una petición HTTP POST, que aprenderás en este mismo artículo.
Requisitos de la red
En el caso de que tu red esté protegida, tienes de asegurarte de habilitar, o añadir a la "whitelist", el siguiente IP/URL y puerto.
- URL: insert.dexma.com
- IP: 104.155.73.171
- HTTP port: 80 / HTTPS port: 443
Otros requisitos
Hay que tener en cuenta que los mensajes insertados a la API deberían tener menos de 5.000 lecturas cada mensaje.
Además, aunque no haya ratelimits para insert.dexma.com, recomendamos los siguientes puntos para obtener un mejor rendimiento:
- limitar la concurrencia contra la API a no más de 8 ejecuciones paralelas
- no publicar cuerpos POST muy grandes (menos de 1000 lecturas por cuerpo)
Por último, tener en cuenta que los mensajes se introducen en colas, y se procesan de forma asíncrona, por lo que los datos no se verán inmediatamente cuando se publiquen grandes cantidades de datos.
¿Cómo funciona?
- Consigue la información de seguridad para tu gateway
- Construir la consulta
- Envia tu consulta con Postman
Consigue la información de seguridad para tu concentrador
Antes de configurar la consulta para enviar datos, necesitarás apuntar algunos datos de seguridad del concentrador al que quieres enviar los datos (echa un vistazo a este artículo para más información sobre concentradores).
Accede al concentrador al que quieres enviar datos en Configuración --> Concentradores. Si no tienes un concentrador en tu cuenta todavía, sigue los pasos de este artículo para crear un concentrador virtual.
La configuración del concentrador lista 2 campos que deben ser anotados, la Clave (Key) y el token del concentrador. Para este ejemplo se utilizarán:
- Clave (Key): mac-123456789
- Token del concentrador: token123456789
Toma nota de ambos ya que serán necesarios para construir la llamada. No compartas esta información con terceros.
Si el concentrador al que deseas enviar los datos no tiene su token listado, contacta con el soporte técnico, que podrá proveerte con el token correspondiente.
Con la clave (key) y el token del concentrador, ya puedes proceder a construir la petición HTTP.
Construir la consulta
Para enviar los datos con una consulta HTTP, se debe definir la URL, la cabezera y el cuerpo de la consulta.
Parámetros de la URL
La URL de la API de inserción es insert.dexma.com/readings. Los parámetros se añaden después de la URL para proporcionar la información de seguridad pertinente. URL Ejemplo:
https://insert.dexma.com/readings?source_key=mac-123456789&dexcell_source_token=token123456789
Host: insert.dexma.com
Path: /readings
Método: HTTPS POST
Parámetros de la URL:
- source_key: Parámetro obligatorio. Esta es la dirección MAC del concentrador o la clave única que identifica la fuente de datos a la que pertenecen los datos, que hemos anotado antes.
- dexcell_source_token: la forma de autenticación para cada concentrador. El token se utiliza como una capa de seguridad adicional y puede ser revocada por el proveedor de la plataforma si es necesario. No es obligatorio como parámetro de la URL, pero puede ser usado.
Cabecera de la consulta
Se debe definir una consulta con la información de seguridad para el concentrador. Este es obligatorio, y evita que nadie pueda enviar datos al concentrador si no tiene el token. Ejemplo de cabecera:
x-dexcell-source-token: token123456789
Tipo de contenido: application/json
x-dexcell-source-token: el token de autenticación del concentrador que fue anotado abajo antes.
Cuerpo del mensaje
El cuerpo del mensaje HTTP es un archivo JSON que debe contener la colección (array) del mensaje que quieres insertar.
[{
"did":"3a",
"sqn":1,
"ts":"2014-10-02T10:30:00+02:00"<,
"values":[
{
"p":401,
"v":3505
},
{
"p":402,
"v":5600012
},
{
"p":404,
"v":123504
}
]
},
{ ... },
{ ... }
]
La estructura del mensaje es la siguiente:
- "did" : String (texto) // máx. 25 caract.; ID local del dispositivo
- "sqn": Entero // Número del mensaje; → Usado internamente como control de las lecturas. Debería ser incremental empezando desde uno. Si no puedes envíarlo, ponlo en "1".
- "ts": String (texto) // Formato de fecha basado en el Estándar ISO 8601, los formatos disponibles de son:
- YYYY-MM-DDTHH:MM:SSZ→ 2021-07-28T22:00:00Z. Revisa esta sección si vas a usar tiempo Zulú
- YYY-MM-DDTHH:MM:SS+HH:MM → 2021-07-28T17:14:00+02:00
- YYY-MM-DDTHH:MM:SS-HH:MM → 2021-07-28T17:14:00-02:00
- Deberías añadir el desfase horario dependiendo de la zona horaria de tu ubicación.
- "valores": Colección // Contiene todas las lecturas con su id de parámetro y su valor respectivo. La estructura es la siguiente:
- "p": Entero // Parámetro ID del tipo de los datos contenidos; obtenido de Parámetros
- "v": Float // valor de la lectura
Envía la consulta con Postman
La URL de la consulta debe ser algo similar a esto:
http://insert.dexma.com/readings?source_key=mac-123456789
o esto:
https://insert.dexma.com/readings?source_key=mac-123456789&dexcell_source_token=token123456789
Donde "source_key" es la clave del concentrador que anotaste antes.
1. Dirígete a Postman (o al software equivalente que estés usando) para preparar la petición POST HTTP. La pantalla por defecto de Postman debería ser similar a esta:
2. Cambia el tipo de solicitud de GET a POST en el menú desplegable de la izquierda. En el cuadro de texto de la URL de la solicitud, introduce tu URL
http://insert.dexma.com/readings?source_key=mac-123456789
Asegúrate de cambiar mac-123456789 con la clave del concentrador. La pantalla debería verse así:
3. Haz clic en la pestaña Headers debajo de la barra de direcciones URL e introduce los siguientes encabezados:
- x-dexcell-source-token: token123456789
- Tipo de contenido: application/json
Asegúrate de cambiar token123456789 con tu token del concentrador. La pantalla debería verse así:
4. Haz clic en la pestaña "Body" debajo de la barra de URL e introduce el cuerpo de la solicitud. Tu pantalla debería tener este aspecto:
5. Una vez que haya terminado esta configuración, pulse el botón Send para enviar la petición HTTP e introducir datos en la plataforma. Si la configuración fue correcta, deberías obtener una respuesta de 200 OK:
Si tu consulta no tiene éxito, repasa los pasos de configuración y asegúrate de que tu clave y tu token son correctas.
Ejemplos
- Ejemplo 1: Envío de datos acumulados
- Ejemplo 2: Envío de datos discretos
- Ejemplo 3: Envío de datos instantáneos
Ejemplo 1: Envío de datos acumulados
Este ejemplo muestra cómo insertar datos acumulados de energía activa en el dispositivo "3" del concentrador "123456789". De acuerdo con la lista de parámetros, los datos deben ser introducidos en el parámetro 402.
- Sólo URL:
https://insert.dexma.com/readings?source_key=mac-123456789&dexcell_source_token=123456789
- URL y encabezado:
https://insert.dexma.com/readings?source_key=mac-123456789
x-dexcell-source-token:123456789
Cuerpo del mensaje:
[{
"did":"3",
"sqn":1,
"ts":"2014-10-02T10:30:00+00:00"<,
"values":[
{
"p":402,
"v":1250.0
}
]
},
{
"did":"3",
"sqn":2,
"ts":"2014-10-02T10:45:00+00:00"<,
"values":[
{
"p":402,
"v":1280
}
]
},
{
"did":"3",
"sqn":3,
"ts":"2014-10-02T11:00:00+00:00"<,
"values":[
{
"p":402,
"v":1298.3
}
]
}
]
Nota importante: Para los datos acumulados, la plataforma utiliza la convención de asignar el consumo entre dos marcas de tiempo A y B a A. Por ejemplo, una lectura con una marca de tiempo A de 2020-05-28T15:00:00 y un valor de 1000 kWh, seguida de una lectura con una marca de tiempo B de 2020-05-28T15:15:00 y un valor de 1100 kWh, resultará en un consumo de 100 kWh asignado a la marca de tiempo de A (2020-05-28T15:00:00) en la interfaz. Esto también significa que la plataforma no calculará el consumo de un intervalo hasta que reciba la lectura al final del mismo.
Ejemplo 2: Envío de datos discretos
Este ejemplo muestra cómo insertar datos de energía activa cada media hora en el dispositivo "5" del concentrador "123456789". De acuerdo con la lista de parámetros, los datos deben ser introducidos en el parámetro 40261.
- Sólo URL:
https://insert.dexma.com/readings?source_key=mac-123456789&dexcell_source_token=123456789
- URL y encabezado:
https://insert.dexma.com/readings?source_key=mac-123456789
x-dexcell-source-token:123456789
Cuerpo del mensaje:
[{
"did":"5",
"sqn":1,
"ts":"2014-10-02T10:30:00+00:00"<,
"values":[
{
"p":40261,
"v":30.0
}
]
},
{
"did":"5",
"sqn":2,
"ts":"2014-10-02T10:45:00+00:00"<,
"values":[
{
"p":40261,
"v":18.3
}
]
}
]
Notas importantes:
- Para los datos de intervalo discreto, la plataforma utiliza la convención de trazar la energía consumida durante el intervalo en la primera marca de tiempo. Por ejemplo, si de 20:00h a 20:30h la energía consumida es de 52 kWh, los datos deben ser introducidos en la marca de tiempo de las 20:00h.
- Para los datos de intervalo, se debe enviar la marca de tiempo del inicio del intervalo de acuerdo con la frecuencia de los datos. Por ejemplo, si se envía un consumo diario, se debe especificar siempre la primera hora del día, según la notación que esté utilizando. Por ejemplo, una lectura diaria correspondiente al consumo diario de energía activa (parámetro 40221) del día 28 de julio de 2021 en una zona horaria con desfase de +02:00 debe especificarse de cualquiera de las siguientes formas:
- 2021-07-28T22:00:00Z
- 2021-07-28T00:00:00+02:00
- Si se envía un mensaje con una marca de tiempo que no corresponde al inicio del intervalo, (por ejemplo 2021-07-28T22:15:00Z, o 2021-07-28T00:15:00+02:00) la API responderá con un mensaje OK (200) pero la lectura será descartada por el sistema de inserción.
Ejemplo 3: Envío de datos instantáneos
Este ejemplo muestra cómo insertar datos instantáneos como la temperatura (301) o la potencia (401) al dispositivo "7" del portal "123456789".
- Sólo URL:
https://insert.dexma.com/readings?source_key=mac-123456789&dexcell_source_token=123456789
- URL y encabezado:
https://insert.dexma.com/readings?source_key=mac-123456789
x-dexcell-source-token:123456789
Cuerpo del mensaje:
[{
"did":"7",
"sqn":1,
"ts":"2014-10-02T10:30:00+00:00"<,
"values":[
{
"p":301,
"v":25.2
},
{
"p":401,
"v":2540
}
]
},
{
"did":"7",
"sqn":2,
"ts":"2014-10-02T10:45:00+00:00"<,
"values":[
{
"p":301,
"v":25.8
},
{
"p":401,
"v":1890
}
]
}
]
Para cualquier otra duda o consulta, por favor contacta con tu soporte técnico.
Usar tiempo Zulú
Si vas a usar mensajes con hora zulú, ten en cuenta que debes añadir el desfase de la zona horaria de la pasarela en la que estás insertando los datos. Por ejemplo, una pasarela situada en la zona "Europa/Madrid" tendrá un desfase de +02:00 en verano, y la hora zulú correspondiente para una lectura a medianoche es la siguiente 2021-07-28T22:00:00Z. Si no se tiene en cuenta esto, y se envía una lectura a las 00:00:00Z, como 2021-07-28T00:00:00Z, la API procesará la petición y devolverá un mensaje OK (200) pero el sistema de inserción descartará la lectura.