Iottly API Integration

La piattaforma Iottly espone due canali di integrazione complementari per gli sviluppatori:

• HTTP API — interroga i dati del progetto, ispeziona i device, invia comandi e recupera la cronologia dei messaggi in modo programmatico.
• Webhooks — iscrive il tuo backend allo stream di messaggi in tempo reale provenienti dai device connessi.

Autenticazione

Tutte le chiamate API sono autenticate con un bearer token nell’header Authentication:

curl -H "Authentication: bearer <LA_TUA_API_KEY>" \
  https://api.cloud.iottly.com/v1.0/project/<PROJECT_ID>/inspect

Le chiamate non autenticate restituiscono uno status HTTP 401.

IMPORTANTE: I token API danno accesso ai tuoi dati. Non condividerli né inserirli nel codice sorgente.

Ottenere una API key

Dalla dashboard del tuo progetto, clicca il pulsante OPEN in alto a destra per aprire il pannello delle impostazioni, poi naviga su Manage API keys.

In questo pannello puoi visualizzare le chiavi esistenti, crearne di nuove ed eliminare quelle non più utilizzate.

Per aggiungere una chiave, inserisci una descrizione significativa (es. “Dashboard analytics”, “Reporting service”, “Mario Rossi”) e clicca Create new API key.

Suggerimento: Nomi descrittivi facilitano il controllo e la revoca delle chiavi in futuro.

Verifica la connettività

Once you have a key, test the connection with the ping endpoint:

curl -H "Authentication: bearer <LA_TUA_API_KEY>" \
  https://api.cloud.iottly.com/v1.0/project/ping

Risposta attesa:

{"status": "pong"}

Prossimi passi

Per ulteriore assistenza contatta iottly-support@tomorrowdata.io.

File di configurazione

[agent]
# Token univoco del device (impostato da `iottly-agent provision`)
token = eyJhbGciOiJSUzI1NiJ9...

# Livello di log: debug | info | warn | error (default: info)
log_level = info

# Percorso del file di log locale (default: /var/log/iottly/agent.log)
log_file = /var/log/iottly/agent.log

[connection]
# Endpoint della piattaforma Iottly (non modificare a meno di self-hosting)
endpoint = wss://agent.cloud.iottly.com/ws

# Intervallo di riconnessione in secondi (default: 5)
reconnect_interval = 5

# Intervallo massimo di riconnessione dopo back-off esponenziale (default: 120)
reconnect_max = 120

# Intervallo heartbeat in secondi (default: 30)
heartbeat_interval = 30

[telemetry]
# Abilita il publisher di telemetria integrato (default: true)
enabled = true

# Dimensione buffer per i frame di telemetria prima del flush (default: 100)
buffer_size = 100

# Intervallo di flush in millisecondi (default: 1000)
flush_interval_ms = 1000

[security]
# Percorso al bundle CA per verificare il certificato TLS della piattaforma
# Lasciare vuoto per usare lo store di sistema
ca_bundle =

# Versione TLS minima: tls1.2 | tls1.3 (default: tls1.2)
min_tls_version = tls1.2

Override tramite variabili d’ambiente

Ogni chiave di configurazione può essere sovrascritta a runtime usando il pattern IOTTLY_<SEZIONE>_<CHIAVE> (maiuscolo, underscore):

Esempio:

IOTTLY_AGENT_LOG_LEVEL=debug \
IOTTLY_TELEMETRY_FLUSH_INTERVAL_MS=500 \
  /opt/iottly/bin/iottly-agent start

Supporto proxy

Se il device è dietro un proxy HTTP, imposta le variabili d’ambiente proxy standard prima di avviare l’agent:

export HTTPS_PROXY=http://proxy.interno:3128
export NO_PROXY=169.254.0.0/16,10.0.0.0/8
systemctl start iottly-agent

Applicare le modifiche alla configurazione

L’agent monitora il file di configurazione per rilevare le modifiche. La maggior parte delle chiavi ha effetto dopo un reload graceful:

# Ricarica senza interrompere la connessione attiva
systemctl reload iottly-agent

# Riavvio completo (interrompe brevemente la connessione)
systemctl restart iottly-agent

Nota: Le modifiche a token o endpoint richiedono sempre un riavvio completo.