Tipus d'aplicació de font de dades: Crea el teu connector de dades

Visió general

Una aplicació de tipus de font de dades et permet crear el teu propi connector de dades dins de la plataforma.

Si només vols enviar dades via API a una font de dades ja existent i/o sense cap interfície personalitzada, només has de seguir les instruccions de l'API d'inserció.

Contingut

• Abans de començar
• Què és una aplicació de tipus de font de dades?
• Com funciona (de principi a fi)
• Responsabilitats de l'API
• Regla arquitectònica crítica
• Pautes sobre càrrega útil i rendiment
• Problemes comuns
• Millors pràctiques de la UI
• Marca i distribució
• Inici ràpid

• Enllaços relacionats

   

Abans de començar

Has de:

• Haver creat una aplicació (consulta: API de desenvolupament: Crea i gestiona la teva aplicació)
• Tenir infraestructura backend (servidor API)
• Poder exposar punts finals HTTPS públics
• Consell PRO: demana a suport un esquelet d'aplicació que t'ajudarà a avançar més ràpidament

Què és una aplicació de tipus de font de dades?

Una aplicació de tipus de font de dades és una aplicació que:

• Defineix un tipus de font de dades
• Permet als usuaris crear fonts de dades a través de la teva UI
• Envia dades a aquestes fonts de dades

Com funciona (de principi a fi)

1. S'instal·la l'aplicació

• L'aplicació s'instal·la en un compte
• El teu backend rep un token permanent
• Utilitzes aquest token per cridar l'API v3

(per a més detalls consulta: API de desenvolupament: Crea i gestiona la teva aplicació)

2. El tipus de font de dades esdevé disponible

Després de la instal·lació:

1. Ves a Configuració
2. Obre Fonts de dades
3. Fes clic a Registra nova font de dades
4. El teu tipus de font de dades apareix a la llista sota la secció de fonts de dades externes

3. L'usuari crea una font de dades

Quan l'usuari selecciona el teu tipus de font de dades, la plataforma carrega la teva UI:

GET /datasources/new

4. La teva aplicació gestiona la configuració

La teva UI ha de:

• Sol·licitar configuració (credencials, IDs, etc.)
• Validar l'entrada
• Enviar dades al teu backend

5. El teu backend crea la font de dades

Has de cridar l'API v3:

POST https://api.dexcell.com/v3/datasources

Exemple:

curl --location 'https://api.dexcell.com/v3/datasources' \
  --header 'x-dexcell-token: <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "My Datasource",
    "key": "unique-key-123",
    "timezone": "Europe/Madrid",
    "type": "VIRTUAL",
    "status": "CONNECTED"
  }'

👉 Referència completa: https://developers.dexma.com/#75913267-89ad-422f-bce2-fbf606353196

6. Desa les dades de la font de dades localment

El teu backend ha de desar:

• id de la font de dades id
• clau de la font de dades key
• configuració de la font de dades
• mapeig al teu sistema extern

7. Recupera el token d'inserció

Després de crear la font de dades:

GET https://api.dexcell.com/v3/datasources/{id}/token

Això retorna el token necessari per enviar lectures.

👉 Referència completa: https://developers.dexma.com/#18c8716c-e3fe-4d09-82a9-ebd4c17096cb

8. Envia lectures (API d'inserció)

Aquest és el flux principal de dades.

POST https://insert.dexma.com/readings?source_key=<DATASOURCE_KEY>

Capçaleres:

x-dexcell-source-token: <DATASOURCE_TOKEN>
Content-Type: application/json

Exemple de petició

curl -X POST "https://insert.dexma.com/readings?source_key=<KEY>" \
  -H "x-dexcell-source-token: <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "did": "device-1",
      "sqn": 1,
      "ts": "2026-01-01T00:00:00+01:00",
      "values": [
        { "p": 402, "v": 1250.0 }
      ]
    }
  ]'

Com funciona la inserció

• per definir "p" consulta Introducció als paràmetres i llista d'id de paràmetres, operació i resolució
• Les peticions són asincròniques
• HTTP 200 OK vol dir acceptat, no completament processat
• Les dades apareixen més tard a la plataforma

👉 Referència completa: Ús de l'API d'inserció per introduir dades en un gateway

9. Edició d'una font de dades

Quan un usuari obre una font de dades:

GET /datasources/{id}

La teva aplicació ha de:

• Carregar la configuració actual
• Permetre edicions
• Enviar actualitzacions al backend

Crida al backend:

PUT https://api.dexcell.com/v3/datasources/{id}

10. Eliminació d'una font de dades

Quan s'elimina una font de dades:

DELETE /datasources/{id}

El teu backend ha de:

• Eliminar els mapeigs interns
• Opcionalment cridar l'API v3:

DELETE https://api.dexcell.com/v3/datasources/{id}

Retorna:

HTTP 2xx

Si retornen un error, s'anul·la l'eliminació.

Responsabilitats de l'API

Regla arquitectònica crítica

No cridis l'API v3 abans de cada inserció.

En lloc d'això:

• Desa l'estat de la font de dades localment
• Mantingues-lo actualitzat quan hi hagi canvis
• Utilitza directament l'API d'inserció

Per què és important

Si no ho segueixes:

• Pots arribar als límits de l'API
• El rendiment es degradarà
• La integració pot fallar a gran escala

Pautes sobre càrrega útil i rendiment

• Recomanat: ~1.000 lectures per petició
• Màxim: ~5.000 lectures
• Màxim de concurrència: ~8 peticions
• Utilitza l'enviament en lots quan sigui possible

Problemes comuns

Error d'inserció

• token de font de dades incorrecte
• clau de font de dades incorrecta
• combinació de paràmetres invàlida (paràmetre base + resolució + paràmetre)
• format de marca temporal incorrecte

Inserció correcta però sense dades

Les dades s'insereixen amb OK, però no es visualitzen a la font de dades

Les dades no es poden veure dins la font de dades ni a eliminar lectures ni a últimes lectures. Pot ser degut a:

• marca temporal invàlida per a la combinació de paràmetres: les dades d'interval de temps s'han d'inserir al principi del període i considerant la resolució triada.
• combinació de paràmetres invàlida (paràmetre base + resolució + paràmetre)
• dispositiu rebutjat

Les dades s'insereixen amb OK, però no es visualitzen a l'analítica

Les dades es poden veure dins la font de dades a eliminar lectures o últimes lectures, però no a l'analítica. Comprova que:

• el dispositiu i paràmetre estan acceptats
• el dispositiu està assignat a una ubicació
• estàs visualitzant les dades en el dispositiu, paràmetre, resolució, operació i període de temps correctes

Millors pràctiques de la UI

La teva UI ha de:

• Ser simple i guiada
• Explicar clarament les entrades requerides
• Validar aviat
• Evitar exposar complexitat tècnica

Marca i distribució

Pots:

• Afegir el teu logotip
• Controlar la UI
• Definir el flux de configuració

Opcions de visibilitat

• Privat → només per a la teva organització
• Públic → disponible per a tots els usuaris (requereix aprovació)

Inici ràpid

Crea el teu primer connector:

1. Crea l'aplicació
2. Instal·la l'aplicació
3. Ves a Fonts de dades → Registra nova font de dades
4. Selecciona el teu tipus de font de dades
5. Completa la UI de configuració
6. Crea la font de dades via API
7. Recupera el token
8. Envia una lectura
9. Verifica que apareixen les dades

Enllaços relacionats

• API v3 - portal de desenvolupadors
• API de desenvolupament: Crea i gestiona la teva aplicació
• Ús de l'API d'inserció per introduir dades en un gateway