API de inserción

Seguir

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.

Contenido:

¿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:

  • Obtener el token del concentrador en el que quieres importar los datos. Si no tienes ningun concentrador configurado en el EMS necesitarás configurar uno. Para ello, necesitarás need administrator rights.

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.
  • Debería haber preparado una petición HTTP POST

¿Cómo funciona?

Requerimentos 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: is3.dexcell.com
  • IP: 104.155.73.171
  • HTTP port: 80 / HTTPS port: 443

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.

Accede al concentrador al que quieres enviar datos en el menú de configuración (Configuración --> Concentradores). Si no tienes un concentrador en tu cuenta todavía, sigue los pasos de este artículo para crear uno.

La configuración del concentrador lista 2 campos que deben ser anotados, la Clave (Key) y el token del concentrador. (Están en borroso en la siguiente captura de pantalla por razones de seguridad). Por esto ejemplo utilizaremos lo siguiente:

  • Clave (Key): mac-123456789
  • Token del concentrador: token123456789

Toma nota de ambos ya que serán necesario para construir la llamada. No compartas esta información con terceros.

dexma-api-insert-example-01.png

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, podemos proceder a construir la petición HTTP.

Para más información sobre los concentradores, comprueba este artículo.

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 is3.dexcell.com/readings. Los parámetros se añaden después de la URL para proporcionar la información de seguridad pertinente.

URL Ejemplo:

https://is3.dexcell.com/readings?source_key=mac-123456789&dexcell_source_token=token123456789


Host: is3.dexcell.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 que el 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 // max 25 chars; 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 // Formato de fecha basado en el Estándar ISO 8601, los formatos disponibles de son:
    • YYY-MM-DDTHH:MM:SSZ → 2014-11-28T17:14:00Z
    • YYY-MM-DDTHH:MM:SS+HH:MM  2014-11-28T17:14:00+02:00
    • YYY-MM-DDTHH:MM:SS-HH:MM 2014-11-28T17:14:00-02:00
    • Deberías añadir el desfase horario dependiendo de la zona horaria de tu ubicación.
  • "valores": Colección/Arreglo // Contiene todas las lecturas con su id de parámetro y su valor respectivo, la estructura es lo siguiente:
    • "p": Entero // Parámetro ID del tipo de los datos contenidos; véase DEXMA Parámetros
    • "v": Float // valor de la lectura

 

Envia la consulta con Postman

La URL de la consulta debe ser algo similar a esto:

http://is3.dexcell.com/readings?source_key=mac-123456789

o esto:

https://is3.dexcell.com/readings?source_key=mac-123456789&dexcell_source_token=token123456789

Donde "source_key" es la clave del concentrador que anotaste antes.

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:

dexma-api-insert-example-02.png

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://is3.dexcell.com/readings?source_key=mac-123456789

Asegúrate de cambiar mac-123456789 con la clave del concentrador. La pantalla debería verse así:

dexma-api-insert-example-04.png

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í:

dexma-api-insert-example-03.png

Haz clic en la pestaña "Body" debajo de la barra de URL e introduce el cuerpo de su solicitud. Tu pantalla debería tener este aspecto:

dexma-api-insert-example-05.png

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:

dexma-api-insert-example-06.png

Si su consulta no tiene éxito, repasa los pasos de configuración y asegúratede que que tu clave y tu token son correctas.

 

Ejemplos

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://is3.dexcell.com/readings?source_key=mac-123456789&dexcell_source_token=123456789


URL y encabezado:

https://is3.dexcell.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://is3.dexcell.com/readings?source_key=mac-123456789&dexcell_source_token=123456789


URL y encabezado:

https://is3.dexcell.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
        }
        ]
  }
]

 

Nota importante: Para los datos de intervalo discreto, la plataforma utiliza la convención de trazar el la energía consumida durante el intervalo en la primera marca de tiempo. Por ejemplo, de 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.

 

Ejemplo 3: Envío de datos instantáneos

Este ejemplo muestra cómo insertar datos instantáneos como la temperatura (301) o la energía (401) al dispositivo "7" del portal "123456789".

Sólo URL:

https://is3.dexcell.com/readings?source_key=mac-123456789&dexcell_source_token=123456789


URL y encabezado:

https://is3.dexcell.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 contacte con su soporte técnico.

 

¿Te pareció útil este artículo?