API di sviluppo: crea e gestisci la tua app

Scopo

Questa guida spiega come registrare una Market App, installarla in un account, completare l'autenticazione e iniziare a utilizzare l'API v3. Non è intenzionalmente una documentazione completa dell'API — utilizza il portale sviluppatori per una documentazione esaustiva degli endpoint.

Requisiti

Hai bisogno di:

• Un utente della piattaforma con permessi di superadmin per registrare l'app.
• Un server backend con un URL pubblico HTTPS e la capacità di gestire richieste HTTP.
• Conoscenze base di REST, header HTTP e JSON.

Avvio rapido per l'autenticazione

Se non devi sviluppare alcuna UI che interagisca con la piattaforma, e ti serve solo un token per ottenere dati dall'API, puoi saltare le sezioni Configurazione dell'app e Handshake e modello di autenticazione, e semplicemente installare la Access Token App.

Questo token ha permessi di sola lettura. Se necessiti di permessi aggiuntivi - segui le istruzioni per la configurazione dell'app e handshake.

Configurazione dell'app

Registra la tua app (Gestione organizzazione → Market Apps)

• Dal menu utente in alto a destra, apri Gestione organizzazione.
• Vai su Market Apps e clicca Nuova Market App.
• Compila:
  • Info generali (nome, descrizione, icona, visibilità privata/pubblica).
  • URL: URL di installazione (obbligatorio), URL opzionale di pulizia/disinstallazione; viste UI incorporate/reports/sorgenti dati opzionali.
  • Permessi: concedi le aree di risorse in lettura/scrittura di cui la tua app avrà bisogno (permessi mancanti possono bloccare l'accesso).
• Salva l'app e annota App ID e App Secret (necessari per lo scambio di token durante l'installazione). 

Nota: le app private possono essere installate negli account della tua organizzazione senza ulteriori azioni, mentre le app pubbliche (visibili ai clienti della piattaforma) richiedono approvazione. Contatta il supporto per l'approvazione, una volta che l'app è pronta e se desideri renderla pubblica.

Installa la tua app in un account (Apps Market)

• Nell'account di destinazione, apri l'Apps Market e installa la tua app.

Handshake e modello di autenticazione

Quando un utente installa la tua app:

• La piattaforma chiama il tuo Install URL con dep_id e temp_token
• Il tuo backend scambia il temp_token con un token permanente usato nell'API v3 (x-dexcell-token).
• La tua app restituisce HTTP 200 OK per completare l'installazione.

Esempio: usa il token permanente nelle chiamate API v3

curl --request GET \
  --url "https://api.dexma.com/v3/locations" \
  --header "x-dexcell-token: <PERMANENT_TOKEN>"

Limiti di velocità

I limiti predefiniti sono di 10.000 richieste/giorno e 1.000 richieste/ora, che possono essere consultati negli header di ogni richiesta.

Questi limiti possono essere aumentati su richiesta inviando una email al supporto. L'email dovrebbe includere quali limiti sono richiesti e una giustificazione del motivo per cui tale capacità è necessaria

UI incorporata (opzionale)

È possibile esporre l'interfaccia utente in diverse sezioni della piattaforma, inclusi Dashboard, sezione Analisi, Report e Sorgenti dati.

La sessione della piattaforma espone informazioni che puoi usare per costruire queste interfacce, che includono:

• account
• current_location
• location_tags
• locations_below
• utente (incluso ruolo utente e locale)
• dominio personalizzato

Best practice (sicurezza + operatività)

• Mantieni i token lato server; non esporre x-dexcell-token nel codice front-end.
• Progetta per reinstallazione/disinstallazione: ogni installazione genera un nuovo token, e la disinstallazione lo invalida.
• Cache e raggruppa le letture API v3 per evitare l'esaurimento della quota. 

Esempi di chiamate

Con l'app registrata e installata con successo in uno dei tuoi account, dovresti aver ricevuto l'x-dexcell-token e averlo memorizzato nella tua app. Con quel token, puoi effettuare query ai diversi endpoint dell'API. Tutte le query disponibili sono descritte nel portale sviluppatori della piattaforma: developers.dexma.com.

Ottieni la lista di tutte le mie località

• url: https://api.dexcell.com/v3/locations
• header: x-dexcell-token

Ottieni le informazioni specifiche di una località

• url: https://api.dexcell.com/v3/locations/XXX
• header: x-dexcell-token 

Ottieni letture

• url:  http://api.dexcell.com/v3/readings?device_id=XXXXX&operation=DELTA&parameter_key=EACTIVE&resolution=D&from=2015-05-08T00:00:00&to=2015-05-09T23:59:59​
• parametri:
  • device_id: ottenuto da /devices. Non è lo stesso della chiave del dispositivo.
  • parameter key: controlla la lista dei parametri e l'introduzione ai parametri
  • operation: 
    • per letture istantanee: RAW
    • per letture intervallate:
      • DELTA per parametri di natura accumulata (energia, volume, massa, ...)
      • AVG, MAX, MIN per parametri di natura istantanea (potenza, temperatura, umidità, ...)
  • resolution:
    • se operation = RAW, allora resolution deve essere = B
    • se operation != RAW, allora resolution può essere una delle seguenti: FM, TM, QH, HH, H, D, M
  • from / to: YYYY-MM-DDThh:mm:ss (in ora locale)
• header: x-dexcell-token 

Link correlati

• App tipo sorgente dati: costruisci il tuo connettore dati
• Utilizzo dell'API di inserimento per introdurre dati in un gateway
• Access Token App
• APIv3 - Portale sviluppatori