Protocolli e formati supportati

Attualmente, YUCCA supporta i seguenti protocolli di Input/Output

In questo articolo vengono descritte solo le informazioni principali relative ai protocolli. Le indicazioni sulle architetture applicative sono solo a titolo esemplificativo: l’architettura da adottare e i protocolli da utilizzare dipendono dai requisiti dell’applicazione e la loro scelta è a carico dei gruppi di progetto delle stesse.

../../../_images/linee_guida3.png

I protocolli Near Realtime sono da utilizzarsi tipicamente in scenari IoT e consentono l’invio e la fruizione degli eventi in tempo “quasi reale”. Il protocollo MQTT è indicato negli scenari di integrazione tra applicazioni server mentre il protocollo Websocket è utile per la realizzazione di dashbord realtime tramite tecnologie client (es: javascript). Il formato utilizzato per questi protocolli è JSON.

Tipologie di dato

Le entità di tipo Stream e Dataset contengono componenti/colonne ognuno dei quali rappresenta una specifica tipologia di informazioni e deve essere di uno specifico tipo di dato. Per esempio una centralina meteo mobile potrebbe inviare le seguenti componenti:

  • Longitudine
  • Latitudine
  • Temperatura
  • Umidità

Le tipologie di dato disponibili sono:

Tabella 6 - Tipi di dato

Tipo Descrizione Esempio
Int Numero Intero 32 bit 1523
Long Numero Intero 64 bit 1234561245
Float Numero con virgola a singola precisione 32 bit 451.23
double Numero con virgola a singola precisione 64 bit 123312.4442
String Stringa “elemento disponibile”
boolean Valori ammessi “true” e “false” true
dateTime Istante di tempo che include informazioni di timezone 2015-03-10T11:30:00.123Z
longitude Come double ma che descrive una misura di longitudine WGS 84 45.03452
latitude Come double ma che descrive una misura di latitudine WGS 84 7.660726

Formati di rappresentazione

Per la serializzazione i protocolli descritti in figura supportano JSON, XML e CSV.

Protocollo di streaming MQTT(s) (input/output)

MQTT (Message Queuing Telemetry Transport) è un protocollo di messaggistica leggero, studiato per dispositivi limitati in termini di risorse (cpu, memoria) che operano su reti a bassa largheza di banda e ad alta latenza. Implementa il paradigma publish/subscribe. E’ uno standard OASIS. E’ utilizzabile sia in INPUT che in OUTPUT.

Quali tipi di dato gestisce

Attualmente gestisce i dati delle misure (dei sensori o delle applicazioni) forniti in formato JSON.

Per quali tipi di architettura applicativa è indicato

il protocollo MQTT è supportato dai principali linguaggi di programmazione ed è usabile in tutti i tipi di applicazioni:

  • componenti server side scritte nei linguaggi supportati;
  • componenti client side scritte nei linguaggi supportati, comprese le Rich Internet Application in Javascript;
  • applicazioni mobile sia native che in tecnologia web;
  • sensori.

Modalità di utilizzo

  • In INPUT, l’applicazione fornitrice invia i dati ad una coda dipendente dal proprio tenant e univoca per tutti gli stream. Per un esempio è possibile vedere il seguente tutorial.
  • In OUTPUT.

Autenticazione

  • In INPUT, l’autenticazione avviene utilizzando le credenziali tecniche fornite in fase di attivazione del tenant.
  • In OUTPUT, l’autenticazione avviene tramite il passaggio di un token OAuth2. Per i dati pubblici è pure possibile utilizzare l’autenticazione tramite le credenziali tecniche fornite in fase di creazione del tenant.

Trasmissione sicura dei dati

Il protocollo supporta la modalità sicura MQTTS. Tale modalità non è attualmente disponibile e verrà fornita in una prossima release della piattaforma.

Quali librerie utilizzare

Smart Data Platform non suggerisce l’utilizzo di nessuna libreria o framework MQTT ma lascia la scelta allo sviluppatore dell’applicazione. Gli esempi e i tutorial presenti sul developer portal sono stati implementati utilizzando la libreria Paho del progetto Eclipse.

Smart Data Platfom non fornisce nessun supporto sull’utilizzo delle librerie MQTT per il quale rimanda al produttore delle stesse.

Dove approfondire Per approfondimenti fare riferimento alle specifiche del protocollo.

Protocollo HTTP(s) per l’invio dei dati

Http(S) (HyperText Transfer Protocol ) è il protocollo di trasferimento dati utilizzato per le normali comunicazioni sul web utilizzando un paradigma client/server. Le specifiche del protocollo sono gestite dal Word Wide Web Consortium.

Quali tipi di dato gestisce

Attualmente gestisce i dati delle misure (dei sensori o delle applicazioni) forniti in formato JSON. Sono in fase di realizzazione dei servizi per l’invio massivo di dati (disponibili in una prossima release).

Per quali tipi di architettura applicativa è indicato

Per la sua natura, il protocollo HTTP è considerato universale in quanto esistono client per qualsiasi tecnologia. E’ il protocollo suggerito in tutti quei casi in cui MQTT non è supportato correttamente. In particolare è indicato per:

  • applicazioni web ricche;
  • applicazioni mobile;
  • sensori.

Modalità di utilizzo

Questa modalità è utilizzabile solo in INPUT. L’applicazione fornitrice invoca un servizio HTTP POST al quale invia un messaggio JSON contenente i dati della misura. L’URL del servizio dipende dal tenant. Per un esempio è possibile vedere il seguente tutorial.

Autenticazione

L’autenticazione avviene utilizzando le credenziali tecniche fornite in fase di attivazione del tenant inviate tramite Basic Authentication.

Trasmissione sicura dei dati Il protocollo supporta la modalità sicura HTTPS. Tale modalità non è obbligatoria ma è fortemente suggerito il suo utilizzo, soprattutto per evitare attacchi l’intercettazione delle credenziali in fase di autenticazione.

Quali librerie utilizzare

Smart Data Platform non suggerisce l’utilizzo di nessuna libreria o framework HTTP ma lascia la scelta allo sviluppatore dell’applicazione. Smart Data Platfom non fornisce nessun supporto sull’utilizzo delle librerie HTTP per il quale rimanda al produttore delle stesse.

Dove approfondire

Per approfondimenti fare riferimento alle specifiche del protocollo.

Protocollo di streaming STOMP (over web socket) per la fruizione dei dati

STOMP (Simple Text-Oriented Messaging Protocol) è un protocollo che definisce il formato dei messaggi che transitano fra client e server. Si appoggia, come layer di trasporto, al protocollo web socket che fornisce canali di comunicazione full-dublex attraverso una singola connessione TCP/IP. Di fatto consente al server di inviare notifiche al client senza la necessità di essere invocato (modalità push).

Quali tipi di dato gestisce

Attualmente gestisce i dati delle misure (dei sensori o delle applicazioni) forniti in formato JSON.

Per quali tipi di architettura applicativa è indicato

Essendo nato per il mondo web è particolarmente è indicato per:

  • applicazioni web ricche scritte in Javascript.
  • applicazioni mobile web e ibride scritte in javascript.

Esistendo implementazioni websocket anche per linguaggi serverside (es. java), non si esclude la possibilità di utilizzarlo anche server side.

Modalità di utilizzo

Questa modalità è utilizzabile solo in OUTPUT. L’applicazione fruitrice si sottoscrive ad una coda dipendente dallo stream di cui si vogliono leggere i dati. Per un esempio è possibile vedere il seguente tutorial.

Autenticazione

L’autenticazione avviene tramite il passaggio di un token OAuth2. Per i dati pubblici è pure possibile utilizzare l’autenticazione tramite le credenziali tecniche fornite in fase di creazione del tenant.

Trasmissione sicura dei dati

Attualmente non è supportata. In futuro sarà possibile utilizzare la cifratura via SSL.

Quali librerie utilizzare

Smart Data Platform non suggerisce l’utilizzo di nessuna libreria o framework STOMP ma lascia la scelta allo sviluppatore dell’applicazione. Negli esempi è stata utilizzata la libreria ufficiale rilasciata da chi ha redatto le specifiche del protocollo. Smart Data Platfom non fornisce nessun supporto sull’utilizzo delle librerie utilizzate per il quale rimanda al produttore delle stesse. Dove approfondire Per approfondimenti fare riferimento alle specifiche del protocollo.

REST oData Service per la fruizione dei dati

ODATA (Open Data) è un protocollo, rilasciato da Microsoft, che definisce le modalità di esposizione e richiamo di servizi REST. Si appoggia al protocollo HTTP del quale eredita le modalità di accesso e fruizione.

Quali tipi di dato gestisce

Attualmente gestisce i dati, delle applicazioni e dei sensori che sono stati memorizzati in modo permanente sulla piattaforma.

Per quali tipi di architettura applicativa è indicato

Essendo basato sul protocollo HTTP è utilizzbile con tutte le tipologie di architetture applicative.

Modalità di utilizzo

Questa modalità è utilizzabile solo in OUTPUT. L’applicazione invoca, via HTTP(S) i servizi. Per un tutorial sull’utilizzo di oData vedere questo link.

Autenticazione

L’autenticazione avviene tramite il passaggio di un token OAuth2. Per i dati pubblici è pure possibile utilizzare l’autenticazione tramite le credenziali tecniche fornite in fase di creazione del tenant.

Trasmissione sicura dei dati

Il protocollo supporta la modalità sicura HTTPS. Tale modalità non è obbligatoria ma è fortemente suggerito il suo utilizzo, soprattutto per evitare attacchi l’intercettazione delle credenziali in fase di autenticazione.

Quali librerie utilizzare

Smart Data Platform non suggerisce l’utilizzo di nessuna libreria o framework HTTP, REST o oData ma lascia la scelta allo sviluppatore dell’applicazione. Smart Data Platfom non fornisce nessun supporto sull’utilizzo delle librerie utilizzate per il quale rimanda al produttore delle stesse.

Dove approfondire Per approfondimenti fare riferimento alle specifiche

del protocollo.

Download dei file

Si tratta della funzionalità standard di download, via HTTP, utilizzata dai siti e dalle applicazioni web.

Quali tipi di dato gestisce

Attualmente gestisce i dati bulk caricati, sulla piattaforma, dalle applicazioni.

Per quali tipi di architettura applicativa è indicato

E’ un download di file. E’ utile per fare l’import massivo dei dati all’interno dei propri sistemi informativi.

Modalità di utilizzo

Si esegue il download del file dallo User Portal.

Autenticazione

L’autenticazione avviene facendo login sullo User Portal.

Trasmissione sicura dei dati

Il download dei file avviene tramite il protocollo HTTPS.

Quali librerie utilizzare

L’operazione è manuale.

Dove approfondire

Vedi questo tutorial.

Gestione degli Errori

In questa sezione vengono descritte le modalità di gestione degli errori della piattaforma a fronte di problemi sugli eventi ricevuti.

Eventi alfanumerici in realtime

Le politiche sotto descritte si applicano agli eventi ricevuti su tutti i canali (MQTT e HTTP).

Gli eventi che causano errori sulla piattaforma producono nuovi eventi nel seguente formato:

{

«error_name» : «NOME ERRORE»,

«error_code» : «CODICE ERRORE «,

«output» : «CODA DI USCITA»,

«message» : <MESSAGGIO ERRATO>

}

A fronte della ricezione di un evento errato la piattaforma:

  1. Se il protocollo è request/response (come HTTP) risponde con uno status errato (HTTP 500) e con il messaggio di cui sopra
  2. In ogni caso pubblica il messaggio errato nella topic dichiarata nel campo “output” (se tale campo è valorizzato)

Gli errori attualmente gestiti sono:

../../../_images/Errori.png