Specifiche per l’utilizzo dei servizi online di scrittura per file binari

Nella versione attuale di Yucca Smart Data Platform sono disponibili i Web Services online per l’inserimento di file binari afferenti ad un DataSet.

Tali Web Services consentono l’inserimento diretto di file all’interno di dataset di tipo BULK con allegato.

I dataset Bulk con allegato sono un nuovo “tipo” di dataset che prevede la presenza di uno o più campi di tipo allegato.

I dataset Bulk sono popolabili come i dataset bulk con le api generiche considerando i campi allegati come di tipo stringa.

Il valore inserito per il campo allegato deve essere uguale al campo idBinary dichiarato durante l’upload (vedi paragrafo dopo)

Interfaccia dei servizio: upload

Il servizio di inserimento dati è stato realizzato come API REST su trasporto HTTP.

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

Le policy di limitazione sulla dimensione del file impediscono un upload superiore a 100MB (104857601 bytes).

Ogni singola chiamata al servizio consente l’invio di un singolo file, quindi se si vogliono allegare più file per lo stesso DataSet, bisogna effettuare chiamate diverse per ogni allegato.

La url rest in POST per l’upload del file è la seguente: http://api.smartdatanet.it/binary/input/<tenantCode> dove tenantCode è il codice tenant proprietario del dataset. Il body della richiesta di tipo multipart/form-data è composto da:

Nome Attributo Tipo Obbligatorio
upfile File Si
alias Text Si
datasetCode Text Si
datasetVersion Text Si
idBinary Text Si

L’attributo ‘upfile’ contiene il riferimento al binario che si vuole inviare al sistema, il campo alias è un campo di testo che identifica il binario, datasetCode e datasetVersion sono relativi al Dataset a cui va aggiunto l’allegato in questione, mentre il campo idBinary è il valore chiave dell’allegato così come è stato inserito sul dataset.

Interfaccia del servizio: download

E” possibile ottenere l’elenco degli allegati associati ad un dataset BULK (con allegato), interrogando la URL

http://api.smartdatanet.it/api/Binaries

dove:

apiCode è il codice API ODATA associato al dataset BULK (con allegato), che è possibile recuperare dallo Store

L’URL di download di un particolare allegato può essere ottenuto dalla response della precedente chiamata,aggiungendo il prefisso http://api.smartdatanet.it al valore dell’attributo urlDownloadBinary contenuto nella specifica sezione xml “<entry>” dell’allegato.

Ad esempio

http://api.smartdatanet.it” +”/api/Provaallegat_530/attachment/529/1/allegato2

Per individuare invece l’allegato associato ad una particolare record del dataset è possibile interrogare la URL

http://api.smartdatanet.it/api//DataEntities(“<internalId>”)/Binaries

dopo aver individuato lo specifico internalId associato al record del dataset, utilizzando una query OData:

Ad esempio:

http://api.smartdatanet.it/api/Provaallegat_530/DataEntities

Nel caso il dataset sia di tipo privato, per tutte le chiamate, occorrerà utilizzare le consuete modalità di autenticazione e cioè valorizzare http header “Authorization” con il valore “Bearer IlMioTokenOauth”, dove IlMioTokenOauth è il token Oauth2 ottenuto dallo Store.

Risposta e codici di errore

In caso di operazione eseguita con successo (il file è stato effettivamente scritto/letto su HDFS) la risposta sarà HTTP STATUS OK (http 200)

In caso di fallimento dell’operazione (nessun file scritto su HDFS) la risposta sarà uno stato errato (http 500, http 404 o http 413 a seconda della tipologia).

In caso di file superiore a 100MB verrà restituito un errore http 413 e il body del messaggio conterrà il dettaglio dell’errore nel formato json che segue:

{

«error_name» : «File too big»,

«error_code» : «E114»,

«output» : «NONE»,

«message» : “THE SIZE IS TOO BIG”

}

In caso di dati errati relativi ad un dataset o di dataset inesistente verrà restituito un errore http 500 e il body del messaggio conterrà il dettaglio dell’errore nel formato json che segue:

{

«error_name» : «Dataset unknow»,

«error_code» : «E111»,

«output» : «NONE»,

«message» : “YOU COULD NOT FIND THE SPECIFIC DATASET”

}

In caso di dataset errato (non di tipo bulk) verrà restituito un errore http 500 e il body del messaggio conterrà il dettaglio dell’errore nel formato json che segue:

{ «error_name» : «Dataset not attachment «, «error_code» : «E112», «output» : «NONE», «message» : “THIS DATASET DOES NOT ACCEPT ATTACHMENT” }

In caso di errore durante la scrittura su HDFS o nel caso in cui un file con lo stesso idBinary associato al tenantCode sia già stato utilizzato verrà restituito un errore http 500 e il body del messaggio conterrà il dettaglio dell’errore nel formato json che segue:

{

«error_name» : «Dataset attachment wrong»,

«error_code» : «E113»,

«output» : «NONE»,

«message» : “<a seconda dell’errore>”

}

Durante l’operazione di recupero e successivo download del file richiesto, ci possono essere quattro tipologie di errore, ovvero il file non viene letto da HDFS:

– quando l’utente ha inserito in idBinary non corretto, con un errore http di tipo 404:

{

«error_name» : «Binary not found «,

«error_code» : «E117»,

«output» : «NONE»,

«message» : “THIS BINARY DOES NOT EXIST”

}

– quando il Dataset di riferimento non è di tipo BULK e/o i dati relativi non sono corretti, e in questo caso il tipo di errore http viene restituito come 500:

{

«error_name» : «Dataset not attachment «,

«error_code» : «E112»,

«output» : «NONE»,

«message» : “THIS DATASET DOES NOT ACCEPT ATTACHMENT”

}

– quando il Dataset di riferimento non è stato trovato:

{

«error_name» : «Dataset not found «,

«error_code» : «E116»,

«output» : «NONE»,

«message» : “THIS DATASET DOES NOT EXIST”

}

– quando l’API CODE inseirto non è stato trovato:

{

«error_name» : «Dataset not found «,

«error_code» : «E115»,

«output» : «NONE»,

«message» : “THIS API DOES NOT EXIST”

}