Specifiche per l’utilizzo dei servizi online in scrittura su dataset generico

Nella versione attuale di Yucca Smart Data Platform sono disponibili i Web Services online per l’inserimento dati afferenti ad un generico dataset gestito dalla piattaforma

Tali Web Services consentono l’inserimento diretto di dati all’interno di un qualunque tipo di dateset (sia proveniente da stream per il quale è previsto il salvataggio che proveniente da caricamento bulk)

Per l’inserimento di dati su streamDataset, esiste anche un servizio specifico che copre lo stesso perimetro funzionale fornendo un’interfaccia più simile a quella per l’invio delle misure in near-realtime.

Interfaccia dei servizi I servizi di inserimento dati verranno realizzati come API REST su trasporto HTTP/HTTPS. Il formato di rappresentazione del modello dati sarà esclusivamente JSON

L’autenticazione applicativa avverrà con le stesse modalità di quelle applicate per l’invio di eventi in realtime: BasicAuth con username e password definite per tenant

Sono in fase di definizione le policy di limitazione sulla dimensione del recordset di input, nella fase iniziale verrà impostato un limite massimo di 1.500 misure complessive (contenenti anche più componenti) per singola chiamata ai servizi.

Ogni singola chiamata al servizio consente l’invio di più dataset, ma tutte i record afferenti ad uno stesso dataset devono essere raggruppate in un unico oggetto.

La url rest sarà: http://api.smartdatanet.it/dataset/input/<tenantCode> dove tenantCode è il codice tenant proprietario del dataset

Conterrà un array di oggetti dataset, ciascun oggetto dell’arrary descritto dal seguente modello dati

Modello dati:

Nome Attributo Tipo Obbligatorio Note
datasetCode Stringa  
datasetVersion Int No Se datasetVersion viene omesso, validazione dell’input e inserimento avvengono sulla versione current del dataset
values Array di oggetti  

L’array di oggetti “values” contiene i valori del record definiti tramite l’interfaccia userportal, ad esempio per un dataset che definisce 3 attributi campo1 (int), campo2(string), campo3(string)

Nome Attributo Tipo Obbligatorio
campo1 int No
campo2 String No
campo3 String No

NOTA: nel caso di dataset contenente misure associate ad uno stream delle parte realtime, i valori del record dovranno contenere, oltre ai campi definiti su userportal, l’attributo “time” di tipo dateTime

Di seguito si riporta il body json per linserimento di dati relativi ai dataset xxxx (bulk dataset con attributi campo1 (int), campo2(string), campo3(string) ) e yyyy (stream dataset con attributi temp(double), wind (int) )

[{

«datasetCode» : «xxxxx», «datasetVersion» : 1, «values» : [{

«campo1» : 17, «campo2» : «50», «campo3» : «pippo»
}, {
………… ………… ………… …………
}, {
«campo1» : 11,
«campo2» : «2222»,
«campo3» : «12»
}
]
}, {

«datasetCode» : «yyyy», «datasetVersion» : 1, «values» : [{

«time» : «2014-05-13T17:08:58+0200», «temp» : «17.4», «wind» : «50»
}, {
………… ………… ………… …………
}, {
«time» : «2014-05-13T17:08:58+0200», «temp» : «17.4», «wind» : «50»

}, ] } ]

Si noti come i valori per il dataset collegato alle misure di uno stream realtime conengano l’attributo time.

Risposta di output

L’oggetto restituito è insertApiResponse contenente un oggetto di tipo return con i seguenti attributi

Nome Attributo Tipo Obbligatorio Note
dataBLockreport Array di oggetti 8
globalRequest String 8
insertException String Se uguale a null indica che l’operazione è andata a buon fine (al netto del successo dei singoli blocchi)Se valorizzato indica il fallimento dell’operazione (vedi errore e codici).

Oggetti datablock report

Nome Attributo Tipo Obbligatorio Note
datasetVersion long versione del dataset
numRowInserted Int  
numRowToInsFromJson Int Numero di documenti presenti nel blocco di input e inserite
requestId String Identificativo dell’elaborazione del blocco di dati
sensor String No Sensore, in caso di dataset bulk non valorizzato
status String Risultato dell’operazione: end_ins indica l’avvenuto inserimento di tutti i documenti del blocco
stream String No Stream o aplication: valorizzato solo in caso di streamDataset
timestamp Long Timestamp in millisecondi di inizio operazioni di inserimento

{

«insertApiResponse» : {
«return» : {

«dataBLockreport» : [{

«datasetVersion» : 1,

«idDataset» : 14,

«numRowInserted» : -1,

«numRowToInsFromJson» : 4,

«requestId» : «14_1_1429793704672»,

«sensor» : «550e8400-e29b-41d4-a716-446655440000»,

«status» : «end_ins»,

«stream» : «provatime»,

«timestamp» : 1429793704672

}, {

«datasetVersion» : 1,

«idDataset» : 102,

«numRowInserted» : -1,

«numRowToInsFromJson» : 3,

«requestId» : «102_1_1429793731973»,

«sensor» : null,

«status» : «end_ins»,

«stream» : null,

«timestamp» : 1429793731973

}

],

«globalRequestId» : «smartlab_1429793704672»,

«insertException» : null

}

}

}