JSON Lines o array JSON: prepara i record per un’API senza perdere dati

JSON Lines e array JSON non sono lo stesso formato

JSON è un formato testuale per rappresentare dati strutturati. Claris documenta l’esportazione di record in un file di testo JSON Lines (JSONL). In JSON Lines, ogni riga contiene un valore JSON; negli esempi di record sono comuni gli oggetti, ma una riga può contenere anche un altro tipo di valore JSON. Un array JSON, invece, raggruppa una sequenza di valori tra parentesi quadre. Un file in un formato non è automaticamente nella struttura richiesta da un’API.

Per esempio, due righe JSON Lines contenenti oggetti possono essere: «{"id":1,"nome":"Ana"}» e «{"id":2,"nome":"Luis"}». Gli stessi oggetti, presentati come array, sono: «[{"id":1,"nome":"Ana"},{"id":2,"nome":"Luis"}]». È un esempio illustrativo: non indica quali campi o quale formato accetti un endpoint specifico.

• JSON Lines contiene un valore JSON per riga; gli oggetti sono comuni negli esempi di record, ma non sono l’unico tipo possibile.
• Un array JSON racchiude una sequenza di valori tra parentesi quadre.

Verifica la struttura richiesta dall’endpoint

Prima di preparare i dati, consulta la documentazione dell’endpoint specifico e, se disponibile, la relativa specifica OpenAPI. Cerca un esempio della richiesta e verifica quale forma debba avere il contenuto inviato: per esempio, un array alla radice, un oggetto che contiene i record o un singolo oggetto. È il contratto di quell’operazione, non il nome dell’endpoint, a indicare il formato atteso.

Controlla anche quali campi e tipi di valore sono previsti negli esempi o nella documentazione. Se una regola non è chiara, chiedi un chiarimento al team responsabile prima di preparare l’intero lotto. Cambiare la struttura esterna non risolve eventuali differenze rispetto ai requisiti dei campi.

• Individua l’endpoint e l’esempio di richiesta relativi all’operazione effettiva.
• Annota la struttura richiesta e i requisiti documentati per campi e valori.
• Chiarisci i dubbi prima di preparare tutti i dati.

Prova la trasformazione su un campione

Come consiglio generale, lavora prima su una copia di poche righe rappresentative. Se ciascuna riga contiene un valore JSON valido e l’endpoint richiede un array, l’idea illustrativa è leggere ogni riga come un valore, raccogliere i valori e produrre un array JSON. Per esempio, le due righe con Ana e Luis diventano l’array mostrato sopra. Non limitarti ad aggiungere parentesi e virgole al testo: verifica i valori come dati JSON e usa uno strumento adatto. Questo esempio non è una procedura garantita per ogni file o endpoint.

Controlla il campione di partenza e il risultato: verifica che il numero di valori corrisponda, che campi e tipi siano quelli attesi e che stringhe con caratteri speciali, come virgolette o barre inverse, risultino corrette. Se una riga non può essere interpretata come JSON o non ha la struttura prevista, fermati e chiarisci come gestirla invece di ignorarla o correggerla senza una regola. Conserva l’originale mentre valuti il risultato.

• Conserva una copia del file originale e inizia con poche righe rappresentative.
• Verifica che ogni riga del campione sia interpretabile come il valore JSON previsto.
• Confronta il numero di valori, i campi, i tipi e i caratteri speciali con l’originale e con i requisiti dell’API.
• Consulta la documentazione dello strumento per verificare i formati supportati e il comportamento previsto.

Esamina i casi che non corrispondono agli esempi

Il contenuto di un file può non corrispondere all’esempio usato per descrivere la trasformazione. Come controllo generale, verifica che le righe contengano i valori attesi e che non vi siano righe vuote, JSON non valido o valori di tipo diverso da quello previsto dal processo. Non assumere che questi casi vadano ignorati o trasformati nello stesso modo: le informazioni disponibili non definiscono una regola universale per gestirli.

Non eliminare o modificare record solo perché sembrano inattesi. Se trovi una differenza, stabilisci con il team responsabile come gestirla e annota la decisione. Controlla anche i campi richiesti e i relativi tipi rispetto al contratto, senza dedurre requisiti che non sono documentati.

• Confronta le righe con la struttura descritta dal contratto e verifica la validità dei valori JSON.
• Chiedi come gestire righe vuote, righe non valide o tipi inattesi invece di modificarli senza una regola.
• Documenta le decisioni che incidono sui record.

Controlla il risultato prima dell’invio

Come controllo generale, confronta il campione di origine con quello trasformato e verifica che il risultato abbia la forma richiesta. Controlla il conteggio dei valori e, quando ci si aspetta di conservare i record, confronta i campi e i valori corrispondenti. Presta attenzione a caratteri speciali e tipi di dato: non presumere che eventuali differenze siano innocue.

Dopo aver controllato il campione, esamina il risultato completo prima dell’invio. Verifica che sia JSON valido, che la struttura esterna corrisponda al contratto e che non vi siano righe o record persi o aggiunti rispetto a quanto intendi inviare. Se la documentazione specifica controlli ulteriori, seguili; un esempio dall’aspetto corretto non basta da solo a confermare che il risultato sia adatto all’endpoint.

• Confronta il campione trasformato con l’originale, inclusi conteggio, campi, tipi e valori.
• Verifica che il risultato completo sia JSON valido e abbia la forma indicata dalla documentazione dell’API.
• Esamina l’intero risultato prima dell’invio e chiarisci ogni differenza.

Decidi se mantenere JSON Lines

Convertire non è sempre necessario. Se il sistema ricevente documenta il supporto per JSON Lines, puoi valutare se mantenere il formato originale sia adatto al processo. Non dedurre il supporto a JSON Lines dal fatto che un sistema accetti dati JSON: verifica il formato indicato per l’operazione specifica.

Se il contratto richiede un array, prepara il risultato in quella forma e verifica che corrisponda agli esempi e alle indicazioni disponibili. Se non è chiaro come inviare i dati, chiedi un chiarimento o prova con un campione controllato prima di procedere con il resto.

• Mantieni JSON Lines solo se il sistema ricevente ne documenta il supporto.
• Usa un array quando è la struttura indicata dal contratto.
• Chiarisci i dubbi sul processo prima di inviare tutti i dati.

Lista di controllo e strumenti

Prima di completare la preparazione, identifica il formato di origine, consulta il contratto dell’API e conserva una copia intatta. Prova con un campione; controlla la validità dei valori, i campi, i tipi, il conteggio e i caratteri speciali. Poi verifica il risultato completo. Se individui casi da gestire in modo diverso, chiarisci le regole con la documentazione o con il team responsabile.

Apification offre l’integrazione di Cloud e dei servizi tramite REST API, OpenAPI, webhook, iframe e JavaScript, oltre a una procedura guidata per elaborare file e dati. Le informazioni disponibili non confermano una conversione specifica da JSON Lines a un array JSON: verifica i formati supportati prima di affidarti a una funzione particolare.

• Contratto dell’API consultato e file originale conservato.
• Campione controllato per validità, struttura, campi, tipi, conteggio e caratteri speciali.
• Casi inattesi chiariti prima dell’invio.
• Risultato completo confrontato e verificato prima dell’invio.
• Formati supportati dallo strumento verificati nella relativa documentazione.

Domande frequenti