Utilizzo delle funzioni JSON

FileMaker Pro offre diverse funzioni di testo che permettono all'app personalizzata di analizzare e modificare i dati JSON da altre origini, come i servizi Web che trasferiscono i dati in formato JSON attraverso un'API REST.

Per ulteriori informazioni sul formato dati JSON, consultare il sito json.org.

Recupero dei dati JSON da un servizio Web

Utilizzare l'istruzione di script Inserisci da URL per accedere a un servizio Web, specificare i parametri per le informazioni da recuperare, inviare e ricevere intestazioni HTTP e memorizzare i risultati in una variabile o in un campo.

Ad esempio, un panificio mette a disposizione dei propri clienti un elenco dei prodotti in formato JSON attraverso un'API REST. Quanto riportato di seguito restituisce l'elenco delle specialità del giorno come dati JSON nella variabile $$JSON:

Copia
Imposta variabile [$url; "https://panificio.example.com/rest/api/prodotti"]
Copia
Inserisci da URL [Con finestra di dialogo: Disattivata ; Destinazione: $$JSON; $url; Verifica certificati SSL; Opzioni cURL: "--data elenco=specialità"]

Per i dati restituiti in $$JSON, vedere Dati JSON di esempio.

FileMaker Pro offre anche diverse funzioni di utilità per gestire la codifica caratteri e la firma crittografica richiesta da alcune API REST:

Formattazione dei dati JSON

I dati JSON non richiedono spazi o terminazioni di riga tra gli elementi. Tuttavia, per facilitare la lettura dei dati durante il debug dei problemi, utilizzare la funzione JSONFormatElements che aggiunge tabulazioni e terminazioni di riga, come mostrato in Dati JSON di esempio.

Analisi dei dati JSON

Utilizzare le seguenti funzioni JSON per analizzare i dati JSON, ovvero per ottenere chiavi, valori o interi oggetti o matrici JSON da elaborare:

  • JSONGetElement – Esegue una query sui dati JSON per un elemento (un oggetto, una matrice o un valore)
  • JSONListKeys – Elenca i nomi degli oggetti (chiavi) o gli indici di matrice nei dati JSON
  • JSONListValues – Elenca i valori nei dati JSON

Il primo parametro di queste funzioni, json, specifica il campo Testo, la variabile o l'espressione di testo che contiene dati JSON validi su cui agire.

Il secondo parametro, chiaveOIndiceOPercorso, specifica la parte dei dati JSON su cui agire:

  • chiave – il nome di una chiave in un oggetto JSON
  • indice – l'indice di un elemento in una matrice JSON (il primo elemento ha indice 0)
  • percorso – una stringa gerarchica di nomi di chiavi, indici di matrice o entrambi

Per il parametro chiaveOIndiceOPercorso è supportata la seguente sintassi.

Parametro chiaveOIndiceOPercorso

Significato

"."

(Opzionale) Il livello principale, se è il primo carattere

".[n]"

Elementi all'indice n di una matrice al livello principale

".nome"

La chiave di un oggetto nome al livello principale

".nomeA.nomeB.nomeC"

Un oggetto nomeC, discendente di nomeB e nomeA

".[3][2][1]nomeA[0]"

Il primo elemento della matrice nell'oggetto nomeA, al terzo livello in una serie di matrici nidificate

Il seguente script di esempio crea un record per ogni prodotto in una matrice JSON. Supponendo che i Dati JSON di esempio siano memorizzati nella variabile $$JSON, lo script utilizza JSONListValues per ottenere i contenuti della matrice prodotto come elenco di valori e utilizza ConteggioValore per determinare il numero dei prodotti dell'elenco. Creando ogni volta un record per un prodotto attraverso il ciclo, lo script utilizza RicavaValore per ottenere l'oggetto JSON per un prodotto dell'elenco e imposta i campi sui valori ottenuti utilizzando JSONGetElement. Poiché le funzioni JSON analizzano l'intero oggetto JSON che è stato loro passato, può essere più efficiente utilizzare le funzioni JSON su oggetti JSON più piccoli all'interno di un ciclo che viene ripetuto più volte.

Copia
Imposta variabile [$ElencoProdotti; Valore: 
   ConteggioValore (JSONListValues ( $$JSON ; "panificio.prodotto" ) ) ]
Imposta variabile [$ConteggioProdotti; Valore: ConteggioValore ( $ElencoProdotti ) ]
Imposta variabile [$i; Valore: 1 ]
If [$ConteggioProdotti > 0]
   Loop
      Nuovo record/richiesta
      Imposta variabile [$Prodotto; Valore: RicavaValore ( $ElencoProdotti ; $i ) ]
      Imposta campo [Prodotti::ID; JSONGetElement ( $Prodotto ; "id" ) ]
      Imposta campo [Prodotti::Prezzo; JSONGetElement ( $Prodotto ; "prezzo" ) ]
      Imposta campo [Prodotti::Magazzino; JSONGetElement ( $Prodotto ; "magazzino" ) ]
      Salva record/richieste [Con finestra di dialogo: Disattivata]
      Imposta variabile [$i; Valore: $i +1] 
      Exit Loop If [$i > $ConteggioProdotti]
   End Loop
End If

Modifica e aggiunta di elementi dati JSON

Per modificare valori e aggiungere elementi nei dati JSON, utilizzare la funzione JSONSetElement. I parametri json e chiaveOIndiceOPercorso in questa funzione agiscono come descritto in Analisi dei dati JSON. Se chiaveOIndiceOPercorso specifica un elemento esistente, il valore di questo elemento viene modificato; se l'elemento non esiste, ne viene aggiunto uno nuovo.

JSONSetElement imposta l'elemento specificato sul parametro valore. È possibile specificare qualsiasi valore JSON valido, da una stringa o un numero semplici a un oggetto o una matrice complessi.

Il parametro tipo specifica il tipo di dati in valore in modo che il parser JSON segua regole rigide nella gestione di ciascun tipo di dati. Per i tipi di dati supportati, vedere la funzione JSONSetElement. Per inserire i dati in json, già formattato come elemento JSON valido, impostare tipo su JSONRaw.

L'esempio di seguito aggiunge le coppie chiave-valore per un nuovo prodotto a un oggetto JSON vuoto. Quindi il nuovo oggetto viene aggiunto alla fine della matrice prodotto nella variabile $$JSON (vedere Dati JSON di esempio).

Copia
Imposta variabile [$NuovoProdotto; Valore: 
   JSONSetElement ( "{}" ;
      ["id"; "FB4"; JSONString] ; 
      ["nome"; "Torta alla vaniglia"; JSONString] ; 
      ["prezzo"; 17.5; JSONNumber] ; 
      ["magazzino"; 12; JSONNumber] ; 
      ["categoria"; "Torte"; JSONString] ; 
      ["specialità"; true; JSONBoolean] 
   )]
Imposta variabile [$IndiceSucc; Valore: 
   ConteggioValore ( 
      JSONListKeys ( $$JSON ; "panificio.prodotto" ) 
   )] 
Imposta variabile [$$JSON; Valore: 
   JSONSetElement ( 
      $$JSON ; "panificio.prodotto[" & $IndiceSucc & "]" ; $NuovoProdotto ; 
      JSONObject 
   )]

Eliminazione di elementi dati JSON

Per eliminare un elemento, utilizzare la funzione JSONDeleteElement. I parametri json e chiaveOIndiceOPercorso in questa funzione agiscono come descritto in Analisi dei dati JSON. Il parametro chiaveOIndiceOPercorso deve specificare un elemento esistente in json.

L'esempio di seguito elimina l'elemento nella matrice prodotto la cui chiave "id" ha il valore "FB3" nella variabile $$JSON (vedere Dati JSON di esempio).

Copia
Imposta variabile [$ConteggioProdotti; Valore: 
   ConteggioValore ( 
      JSONListKeys ( $$JSON ; "panificio.prodotto" ) 
   )] 
Imposta variabile [$i; Valore: 0]
If [$ConteggioProdotti > 0]
   Loop
      Imposta variabile [$ID; Valore: 
         JSONGetElement ( $$JSON ; "panificio.prodotto[" & $i & "]id" )]
      If [$ID = "FB3"]
         Imposta variabile [$$JSON; Valore: 
            JSONDeleteElement ( $$JSON ; "panificio.prodotto[" & $i & "]" )]
         Esci dallo script [Risultato testo: 0]
      End If
      Imposta variabile [$i; Valore: $i +1]
      Exit Loop If [$i ≥ $ConteggioProdotti]
   End Loop
End If

Gestione degli errori nei dati JSON

Se si verifica un errore durante l'analisi del parametro json, le funzioni JSON restituiscono "?" seguito da un messaggio di errore del parser JSON.

Ad esempio, se in Dati JSON di esempio manca ":" dopo la chiave "panificio", questo calcolo

Copia
JSONGetElement ( $$JSON ; "panificio.prodotto[0]id" )

restituisce questo messaggio di errore:

Copia
? * Line 3, Column 2
  Missing ':' after object member name
* Line 13, Column 5
  Extra non-whitespace after JSON value.

Per determinare se i dati JSON sono validi prima di utilizzarli, utilizzare la funzione JSONFormatElements e controllare se il primo carattere è "?". Ad esempio:

Copia
Imposta variabile [$risultato; Valore: JSONFormatElements ( $$JSON ) ]
If [Sinistra ( $risultato ; 1 ) = "?" ]
   # $$JSON contiene dati JSON non validi.
End If

Dati JSON di esempio

I dati JSON di esempio di seguito contengono un oggetto "panificio" che ha una matrice di tre oggetti "prodotto", ognuno con diverse coppie chiave-valore.

Copia
{
    "panificio"
    {
        "prodotto"
        [
            {
                "id" : "FB1",
                "nome" : "Donuts",
                "prezzo" : 1.99,
                "magazzino" : 43,
                "categoria" : "Pani",
                "specialità" : true
            },
            {
                "id" : "FB2",
                "prezzo" : 22.5,
                "nome" : "Torta al cioccolato",
                "magazzino" : 23,
                "categoria" : "Torte"
                "specialità" : true
            },
            {
                "id" : "FB3",
                "prezzo" : 3.95,
                "nome" : "Baguette",
                "magazzino" : 34,
                "categoria" : "Pani"
                "specialità" : true
            }
        ]
    }
}

Note

  • Il parser JSON conserva l'ordine degli elementi in una matrice, ma non l'ordine degli elementi in un oggetto. Pertanto, le funzioni JSON possono restituire elementi in un oggetto in un ordine diverso da quello specificato.
  • Nei dati JSON, i valori numerici decimali devono utilizzare un punto "." come separatore decimale indipendentemente dal separatore specificato dalle formattazioni di sistema del computer in uso o dalle formattazioni utilizzate al momento della creazione del file FileMaker Pro.