Specifiche per l’accesso ai servizi di esposizione dei dati

Introduzione ai servizi di esposizione dati

Il presente articolo descrive le specifiche di integrazione per la fruizione dei servizi di esposizione dei dati gestiti dalla piattaforma.

Protocolli

I servizi di esposizione dei dati sono servizi rest-http implementati secondo le specifiche del protocollo oData V2: le risorse sono identificate tramite uri, definite tramite un Data Model

Url di pubblicazione

La fruizione dei servizi avviene attraverso la seguente url in cui codiceServizio identifica la risorsa/entity a cui si vuole accedere

http://api.smartdatanet.it/api/<codiceServizio>/

Nella sezione di ricerca dello userportal (http://userportal.smartdatanet.it/userportal/#/discovery) sono disponibili le funzioni per il discovery dei servizi pubblicati con le relative url di accesso

Cenni sull’implementazione SDP del protocollo oData

Nell’attuale release, la copertura del protocollo non è totale ma vengono implementati: - $filter-operatori logici: tutti tranne il not (ovvero eq, ne, gt, ge, lt, le, and, or)

  • $filter-funzioni sulle stringhe:

    • bool substringof(string po, string p1)
    • bool endswith(string p0, string p1)
    • bool startswith(string p0, string p1)
  • $top e $skip con le seguenti limitazioni:

    • Valore massimo per il parametro top à 150
    • Valore massimo per il parametro skip à 1000
    • Quando i parametri top e skip vengono omessi, i serivzi li impostano di default un valore di skip a zero e restituiscono un errore se il numero di record da restituire supera il valore massimo del top.
  • $format

  • $orderby (nota su cosa avviene l’ordinamento)

  • $select

  • $inlinecount=allpages che viene sempre forzato applicativamente ad eccezione delle chiamate su entity specifica

Nelle release successive sono previste estensioni funzionali con l’implementazione di ulteriori features oData

Specificità dei dati

Ogni Entity prevede i seguenti attributi:

  • internaId –>id univoco dell’entity
  • datasetVersion –> versione del dataset di origine (ogni OdataService espone, potenzialmente, informazioni
  • idDataset –> identificativo del dataset di origine (ogni oDataService espone, potenzialmente, informazioni di più dataset)

Per i dati provenienti da sensori e smartObjects in generale, oltre agli attributi specifici delle misure :

  • idDataset–> identificativo del dataset di origine (ogni oDataService esponde, potenzialmente, informazioni di più dataset)
  • sensor –> identificativo dello smartObject univoco a livello di tenant
  • streamCode –> identificativo NON univoco dello stream dati originario
  • time –> timestamp della misura in formato isodate

Alcuni esempi

Come esempio si fa riferimento ai dati salvati dallo stream di un sensore di traffico di Corso Grosseto a Torino

http://userportal.smartdatanet.it/userportal/#/dashboard/stream/csp/cb5b73c3-55ed-5e6f-9f74-f42c5c2ad7f4/TrFl

Il codice del servizio per l’accesso alle API di esposizione dei dati è ds_TrFl_2, la root del del’oDataService è la seguente e riporta, secondo le specifiche odata, tutte gli Entiy Type previsti dal servizio

http://api.smartdatanet.it/api/ds_Trfl_2/

L’EntityDataModel del servizio:

http://api.smartdatanet.it/api/ds_Trfl_2/$metadata

Accesso ai dati senza filtri (il servizio forza applicativamente skip a 0 e segnala un eccezione per il numero dei documenti)

http://api.smartdatanet.it/api/ds_Trfl_2/Measures

Accesso ai dati senza filtri con parametro top (il servizio forza applicativamente skip a 0)

http://api.smartdatanet.it/api/ds_Trfl_2/Measures?$top=24

Accesso ai dati senza filtri con filtro sul time

http://api.smartdatanet.it/api/ds_Trfl_2/Measures?$filter=time ge datetimeoffset’2014-12-01T07:00:00+01:00” and time lt datetimeoffset’2014-12-01T07:15:00+01:00”

API per statistiche di base

Con la release 1.0.0 le api di accesso ai dati espone, per i dataset relativi a misure da smartobjects, un nuovo entityset (MeasuresStats) che può essere utilizzato per ottenere informazioni statistiche di base su aggregazioni di dati in base a parametri temporali.

Analogamente, a partire dalla versione 1.3.0, per i dataset di tipo social (feed social provenienti da ricerche su twitter) è stato introdotto un nuovo entityset (SocialFeedStat) che consente di effettuare statistiche in base, oltre che ai parametri temporali, ad alcuni attributi specifici dei feed twitter

Entity MeasureStat

L’entity per le statistiche sulle misure prevede le seguenti properties:

  • Property temporali relative all’aggregazione (year, month, dayofmonth,hour,minute,dayofweek)
  • Count: conteggio delle misure/campioni che concorrono all’aggregazione
  • <propertymeasure>_sts: una per ogni property oggetto della misura dell’entity Measure, contiene le info statistiche richieste per quell’attributo; se per esempio l’entity measure contiene le property c0 (int) e c1 (double), l’entity MeasureStat conterrà c0_sts (int) e c1_sts(double) che verranno valorizzati in base alle operazioni richieste

Entity SocialFeedStat

L’entity per le statistiche sui feed twitter prevede le seguenti properties:

  • Property temporali relative all’aggregazione (year, month, dayofmonth,hour,minute,dayofweek,retweetparentid,iduser)
  • Count: conteggio delle tweet che concorrono all’aggregazione
  • <propertysocial>_sts: una per ogni property oggetto del feed twitter dell’entity SocialFeed, contiene le info statistiche richieste per quell’attributo; se per esempio l’entity socalfeed contiene le property getText(string) e tweetid (int), l’entity SocialFeedStat conterrà getText_sts (String) e tweetid_sts(int) che verranno valorizzati in base alle operazioni richieste

URI e Parametri per l’accesso ai calcoli statistici:

le query options standard odata agiscono sull’entityset MeasureStats ovvero sul risultato delle operazioni di raggruppamento e calcolo statistico.

Per la definizione delle modalità di raggruppamento, le operazioni da eseguire ed eventuali filtri sull’entityset di origine (Measures), sono stati definiti dei parametri custom seguendo le specifiche del protocollo odata che prevede un punto di estensione tramite “custom query options”.

Custom query Options:

  • timeGroupBy (obbligatorio): indica il tipo di aggregazione sull’attributo time della misura:

    • esempio: timeGroupBy=year

    • valori ammessi:

      • year
      • month_year
      • dayofmonth_month_year
      • hour_dayofmonth_month_year
      • minute_hour_dayofmonth_month_year
      • month
      • dayofmonth_month
      • dayofweek_month
      • dayofweek
      • hour_dayofweek
      • hour
      • retweetparentid (solo per i dataset di tipo social)
      • iduser (solo per i dataset di tipo social)
    • timeGroupOperators (obbligatorio): indica il tipo di operazioni da effettuare sui campi di origine durante l’aggregazione, è espresso nel formato <operazione>,<nomeCampo1>;<operazione>,<nomecampo2> ecc; è permessa una sola operazione statistica per ogni campo di origine

      • esempio timeGroupOperators=avg,c0;sum,c1: media del campo c0 e somma del campo c1
      • valori delle operazioni:
      • avg
      • sum
      • first
      • last
      • max
      • min
    • timeGroupFilter: filter, espresso nelle stesse modalità del $filter odata, sul dataset di origine (Measures), il timeGroupFilter interviene prima dell’operazione di aggregazione. Se ad esempio si considera un api /api001/ con entity set measures con un campo c0 double accedendo la seeguente url /api001/measurestat/? timeGroupBy =year& timeGroupOperators=avg,c0& timeGroupFilter=time ge datetimeoffset’2013-01-01T00:00:00.000+02:00′ restituirà la media del valore c0 suddivisa per anni senza prendere in considerazione le misure precedenti al 2013; analogamente /api001/measurestat/? timeGroupBy =year& timeGroupOperators=avg,c0& timeGroupFilter=c0 gt 10 and c0 lt 20 restituirà la media dei valori di c0 suddivisa per anni ma tale media verrà effettuata prendendo in considerazione solo i valori di c0 maggiori di 10 e minori di 20

Query options standard odata

  • $filter: filtro odata che interviene sul risultato dell’aggregazione (sull’edm dell’entityset measuresstats) … sempre facendo riferimento all’esempio precedente: /api001/measurestat/? timeGroupBy =year& timeGroupOperators=avg,c0& timeGroupFilter=c0 gt 10 and c0 lt 20&$filter=c0_sts gt 13 and c0_sts lt 18 … comporta la media dei valori di c0 compresi tra 10 e 20 suddivisa per anno, ma il resultset conterrà soltanto i record con media (c0_sts) compresa tra 13 e 18
  • $orderby: odata: ordinamento sul resultset di output. Ad esempio /api001/measurestat/? timeGroupBy =year& timeGroupOperators=avg,c0&$orderby=c0_sts desc: media dei valori di c0 suddivisi per anno ordinati in maniera decrescente sulla media stessa
  • $top, $skip: odata, stesso funzionamento che per l’entity sets measure

Esempio – stream dati traffico

Lo stream, oltre agli attributi di default (streamCode, sensor, time e info sui dataset) si compone di un una property con nome “value” che indica il numero di autvetture che transitano in un minuto (un double)

http://api.smartdatanet.it/api/ds_Trfl_2/$metadata

si noti come l’entity MeasureStat contenga:

  • Property temporali relative all’aggregazione (year, month, dayofmonth,hour)
  • Count: conteggio delle misure che concorrono all’aggregazione
  • Value_sts: contine le info statistich richieste per la property value dell’entity measure corrispondente

ESEMPI di errori:

i parametri timeGroupOperators e timeGroupBy sono obbligatori pertanto un’invocazione all’api senza tali parametri genera un errore

http://api.smartdatanet.it/api/ds_Trfl_2/MeasuresStats/

http://api.smartdatanet.it/api/ds_Trfl_2/MeasuresStats?timeGroupBy=year

Raggruppamento per anno e media sul value

i parametri timeGroupOperators e timeGroupBy saranno impostati come segue

  • timeGroupBy=year
  • timeGroupOperators=avg,value

http://api.smartdatanet.it/api/ds_Trfl_2/MeasuresStats/?timeGroupBy=year&timeGroupOperators=avg,value

Nota: nel risultato, gli attributi month, dayofmonth, hour sono valorizzati a -1 in quanto non rischisti come campi di aggregazione in timeGroupBy

Raggruppamento per ora_giorno_mese_anno e media sul value

  • timeGroupBy=year
  • timeGroupOperators=avg,value
  • $top=150
  • $orderby=year,month,dayofmonth,hour

Note:

  • è stato inserito $top: per via del numero di record trovati il servizio restituisce errore se non si limita il numero di risultati per pagina; è possibile verificare la paginazione impostando uno skip di 150,300 e così via
  • il risultato è stato ordinato sugli attributi di output anno,mese,giorno,ora in maniera crescente

Filtro sulle misure di origine

Partendo dall’esempio precedente si filtrano le misure di partenza prima di effettuare il raggruppamento;

si noti come gli attributi utilizzati per il filtro infatti siano le properties dell’entity Measure e non MeasureStat.

Il filtro limita le operazioni di aggregazione e calcolo alle misure del 01/12/2014

  • timeGroupBy=year
  • timeGroupOperators=avg,value
  • $top=150
  • $orderby=year,month,dayofmonth,hour
  • timeGroupFilter=time ge datetimeoffset’2014-12-01T00:00:00+01:00′ and time lt datetimeoffset’2014-12-02T00:00:00+01:00′

http://api.smartdatanet.it/api/ds_Trfl_2/MeasuresStats?timeGroupBy=hour_dayofmonth_month_year&timeGroupOperators=avg,value&timeGroupFilter=time ge datetimeoffset’2014-12-01T00:00:00+01:00” and time lt datetimeoffset’2014-12-02T00:00:00+01:00”&$top=150&$orderby=year,month,dayofmonth,hour

NOTE il parametro top in questo caso è superfluo in quanto il numero di documenti elaborato è inferiore a 150

Secondo Filtro sulle misure di origine

Partendo dall’esempio precedente si filtrano ulteriormente le misure di partenza prima di effettuare il raggruppamento; anche in questo caso gli attributi utilizzati per il filtro infatti siano le properties dell’entity Measure e non MeasureStat.

Il filtro limita le operazioni di aggregazione e calcolo alle misure del 01/12/2014 come nel caso precedente, ma viene aggiunto un secondo filtro sul value per selezionare solo i valori >0

  • timeGroupBy=year
  • timeGroupOperators=avg,value
  • $top=150
  • $orderby=year,month,dayofmonth,hour
  • timeGroupFilter= value gt 0D and time ge datetimeoffset’2014-12-01T00:00:00+01:00′ and time lt datetimeoffset’2014-12-02T00:00:00+01:00′

http://api.smartdatanet.it/api/ds_Trfl_2/MeasuresStats?timeGroupBy=hour_dayofmonth_month_year&timeGroupOperators=avg,value&timeGroupFilter=value gt 0D and time ge datetimeoffset’2014-12-01T00:00:00+01:00” and time lt datetimeoffset’2014-12-02T00:00:00+01:00”&$top=150&$orderby=year,month,dayofmonth,hour

Note: il valore di value_sts che contiene le medie sale e I valori count scendono: perché non vengono considerate le misure con value <=0

Filtro sull’output

Partendo dall’esempio precedente si elimina il filtro sulle misure con value <=0 e viene aggiunto un filtro sui risultati in modo da recuperare solo i document con una media (value_sts) inferiore a 5! In questo caso si utilizza il filter standard di odata che agisce sull’entity measuresstat

  • timeGroupBy=year
  • timeGroupOperators=avg,value
  • $top=150
  • orderby=year,month,dayofmonth,hour
  • timeGroupFilter=time ge datetimeoffset’2014-12-01T00:00:00+01:00′ and time lt datetimeoffset’2014-12-02T00:00:00+01:00′
  • $filter=value_sts lt 5D

http://api.smartdatanet.it/api/ds_Trfl_2/MeasuresStats?timeGroupBy=hour_dayofmonth_month_year&timeGroupOperators=avg,value&timeGroupFilter=time ge datetimeoffset’2014-12-01T00:00:00+01:00” and time lt datetimeoffset’2014-12-02T00:00:00+01:00”&$top=150&$orderby=year,month,dayofmonth,hour&$filter=value_sts lt 5D

NOTE: il numero di documenti scende a 8: solo quelli con value_sts < 5

Ulteriore filtro sull’output

Partendo dall’esempio precedente il filter odata viene modificato aggiungendo count = 60 ovvero considerando i documenti che sono frutto dell’aggregazione di 60 misure

  • timeGroupBy=year
  • timeGroupOperators=avg,value
  • $top=150
  • $orderby=year,month,dayofmonth,hour
  • timeGroupFilter=time ge datetimeoffset’2014-12-01T00:00:00+01:00′ and time lt datetimeoffset’2014-12-02T00:00:00+01:00′
  • $filter=value_sts lt 5D and count eq 60D

http://api.smartdatanet.it/api/ds_Trfl_2/MeasuresStats?timeGroupBy=hour_dayofmonth_month_year&timeGroupOperators=avg,value&timeGroupFilter=time ge datetimeoffset’2014-12-01T00:00:00+01:00” and time lt datetimeoffset’2014-12-02T00:00:00+01:00”&$top=150&$orderby=year,month,dayofmonth,hour&$filter=value_sts lt 5D and count eq 60D

Ulteriori esempi di interrogazione

Accesso ai dati con filtro su intervallo temporale

http://api.smartdatanet.it/api/ds_Trfl_2/Measures?$filter=time ge datetimeoffset’2014-12-01T07:00:00+01:00” and time lt datetimeoffset’2014-12-01T07:15:00+01:00”

Accesso ai dati con filtro su intervallo temporale e ordinamento

http://api.smartdatanet.it/api/ds_Trfl_2/Measures?$filter=time ge datetimeoffset’2014-12-01T07:00:00+01:00” and time lt datetimeoffset’2014-12-01T07:15:00+01:00”&$orderby=value desc

Accesso ai dati con filtro su intervallo temporale, valore double e ordinamento

http://api.smartdatanet.it/api/ds_Trfl_2/Measures?$filter=time ge datetimeoffset’2014-12-01T07:00:00+01:00” and time lt datetimeoffset’2014-12-01T07:15:00+01:00” and value ge 4D&$orderby=value desc

Accesso ai dati – singola entity

http://api.smartdatanet.it/api/ds_Trfl_2/Measures(“547bf73084ae6f07ff31f961”)