Arbeiten mit den JSON-Funktionen

FileMaker Pro bietet mehrere Textfunktionen, mit denen Ihre eigene App JSON-Daten aus anderen Quellen analysieren und ändern kann, z. B. aus Webdiensten, die Daten in JSON-Format über ein REST API übertragen.

Weitere Informationen über das JSON-Datenformat finden Sie unter json.org.

Abrufen von JSON-Daten aus einem Webdienst

Verwenden Sie den Scriptschritt „Aus URL einfügen“, um auf einen Webdienst zuzugreifen, Parameter für die abzurufenden Informationen anzugeben, HTTP-Header zu senden und zu empfangen sowie die Ergebnisse in einer Variablen oder einem Feld zu speichern.

Beispiel: Eine Bäckerei stellt den Kunden ihre Produktliste in JSON-Format über eine REST API zur Verfügung. Folgendes gibt die Liste der heutigen Angebote als JSON-Daten in der Variablen $$JSON zurück:

Copy
Variable setzen [ $url ; "https://bäckerei.beispiel.de/rest/api/produkte" ]
Copy
Aus URL einfügen [ Mit Dialog: Aus; Ziel: $$JSON ; $url ; SSL-Zertifikate verifizieren ; cURL-Optionen: "--data list=Angebote" ]

Die in $$JSON zurückgegebenen Daten finden Sie unter Beispiel für JSON-Daten.

FileMaker Pro bietet auch mehrere Hilfsfunktionen für den Umgang mit der Zeichenkodierung sowie kryptografische Signierung, die einige REST APIs verlangen:

Formatieren von JSON-Daten

JSON-Daten benötigen keine Leerzeichen oder Zeilenenden zwischen Elementen. Damit Sie die Daten jedoch beim Beheben von Problemen besser lesen können, verwenden Sie die Funktion „JSONFormatElements“, die Tabulator- und Zeilenendezeichen hinzufügt, wie unter Beispiel für JSON-Daten gezeigt.

Parsen von JSON-Daten

Verwenden Sie die folgenden JSON-Funktionen, um JSON-Daten zu parsen, d. h. Schlüssel, Werte oder ganze JSON-Objekte oder -Arrays zu erhalten, die Sie weiter verarbeiten können:

  • JSONGetElement – Fragt JSON-Daten auf ein Element (Objekt, Array oder Wert) ab
  • JSONListKeys – Listet Objektnamen (Schlüssel) oder Array-Indizes in JSON-Daten auf
  • JSONListValues – Listet die Werte in JSON-Daten auf

Der erste Parameter dieser Funktionen, json, gibt das Textfeld, die Variable oder den Textausdruck mit den gültigen JSON-Daten für die Bearbeitung an.

Der zweite Parameter, SchlüsselOderIndexOderPfad, gibt den zu bearbeitenden Teil der JSON-Daten an:

  • Schlüssel – Name eines Schlüssels in einem JSON-Objekt
  • Index – Index eines Elements in einem JSON-Array (das erste Element hat den Index 0)
  • Pfad – hierarchische Zeichenfolge aus Schlüsselnamen bzw. Array-Indizes

Die folgende Syntax wird für den Parameter SchlüsselOderIndexOderPfad unterstützt.

Parameter SchlüsselOderIndexOderPfad

Erläuterung

"."

(Optional) Die Root-Ebene, wenn es das erste Zeichen ist

".[n]"

Elemente bei Index n eines Arrays auf der Root-Ebene

".name"

Der Schlüssel eines Objekts mit dem Namen name auf der Root-Ebene

".nameA.nameB.nameC"

Ein Objekt mit dem Namen nameC, das ein Abkömmling von nameB und nameA ist

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

Das erste Element des Arrays im Objekt nameA, das sich auf der dritten Ebene einer Gruppe von verschachtelten Arrays befindet

Das folgende Beispiel ermittelt die Anzahl der Produkte in den Beispiel für JSON-Daten (gespeichert in der Variablen $$JSON) mithilfe von JSONListKeys, erstellt einen Datensatz für jedes Produkt und stellt Felder in jedem Datensatz auf die Werte ein, die mithilfe von JSONGetElement für jedes Produkt abgerufen werden.

Copy
Variable setzen [ $ProduktAnzahl; Wert: 
   ElementeAnzahl ( 
      JSONListKeys ( $$JSON ; "Bäckerei.Produkt" ) 
   ) ] 
Variable setzen [ $i; Wert: 0 ]
Wenn [ $ProduktAnzahl > 0 ]
   Schleife (Anfang)
      Neuer Datensatz/Abfrage
      Feldwert setzen [ Produkte::ID ; 
         JSONGetElement ( $$JSON ; "Bäckerei.Produkt[" & $i & "]ID" ) ] 
      Feldwert setzen [ Produkte::Preis ; 
         JSONGetElement ( $$JSON ; "Bäckerei.Produkt[" & $i & "]Preis" ) ] 
      Feldwert setzen [ Produkte::Bestand ; 
         JSONGetElement ( $$JSON ; "Bäckerei.Produkt[" & $i & "]Bestand" ) ]
      Schreibe Änderung Datens./Abfrage [Mit Dialog: Aus]
      Variable setzen [ $i; Wert:  $i + 1 ] 
      Verlasse Schleife wenn [ $i ≥ $ProduktAnzahl ]
   Schleife (Ende)
Ende (wenn)

Ändern und Hinzufügen von JSON-Datenelementen

Verwenden Sie die Funktion „JSONSetElement“, um in JSON-Daten Werte zu ändern und Elemente hinzuzufügen. Die Parameter json und SchlüsselOderIndexOderPfad funktionieren hier so, wie unter Parsen von JSON-Daten beschrieben. Wenn SchlüsselOderIndexOderPfad ein bestehendes Element angibt, wird der Wert dieses Elements geändert. Wenn das Element nicht existiert, wird es hinzugefügt.

JSONSetElement stellt das angegebene Element auf den Parameter Wert ein. Sie können einen beliebigen gültigen JSON-Wert angeben, von einer einfachen Zeichenfolge oder Zahl bis zu einem komplexen Objekt oder Array.

Der Parameter Typ gibt den Datentyp in Wert an, damit der JSON-Parser beim Umgang mit jedem Datentyp strikte Regeln befolgt. Informationen über die unterstützten Datentypen finden Sie unter Funktion „JSONSetElement“. Um bereits als gültiges JSON-Element formatierte Daten in json einzufügen, stellen Sie Typ auf JSONRaw ein.

Das folgende Beispiel fügt einem leeren JSON-Objekt die Schlüssel-Wert-Paare für ein neues Produkt hinzu. Das neue Objekt wird dann an das Ende des Produktarrays in der Variablen $$JSON hinzugefügt (siehe Beispiel für JSON-Daten).

Copy
Variable setzen [ $NeuesProdukt; Wert: 
   JSONSetElement ( "{}" ;
      [ "ID" ; "FB4" ; JSONString ] ; 
      [ "Name" ; "Vanillekuchen" ; JSONString ] ; 
      [ "Preis" ; 17.5 ; JSONNumber ] ; 
      [ "Bestand" ; 12 ; JSONNumber ] ; 
      [ "Kategorie" ; "Kuchen" ; JSONString ] ; 
      [ "Angebot" ; true ; JSONBoolean ] 
   ) ]
Variable setzen [ $NächsterIndex; Wert: 
   ElementeAnzahl ( 
      JSONListKeys ( $$JSON ; "Bäckerei.Produkt" ) 
   ) ] 
Variable setzen [ $$JSON ; Wert: 
   JSONSetElement ( 
      $$JSON ; "Bäckerei.Produkt[" & $NächsterIndex & "]" ; $NeuesProdukt ; 
      JSONObject 
   ) ]

Löschen von JSON-Datenelementen

Verwenden Sie die Funktion „JSONDeleteElement“, um ein Element zu löschen. Die Parameter json und SchlüsselOderIndexOderPfad funktionieren hier so, wie unter Parsen von JSON-Daten beschrieben. Der Parameter SchlüsselOderIndexOderPfad muss ein bestehendes Element in json angeben.

Das folgende Beispiel löscht das Element im Produktarray, dessen „ID“-Schlüssel in der $$JSON-Variablen den Wert FB3 hat (siehe Beispiel für JSON-Daten).

Copy
Variable setzen [ $ProduktAnzahl; Wert: 
   ElementeAnzahl ( 
      JSONListKeys ( $$JSON ; "Bäckerei.Produkt" ) 
   ) ] 
Variable setzen [ $i; Wert: 0 ]
Wenn [ $ProduktAnzahl > 0 ]
   Schleife (Anfang)
      Variable setzen [ $ID; Wert: 
         JSONGetElement ( $$JSON ; "Bäckerei.Produkt[" & $i & "]ID" ) ]
      Wenn [ $ID = "FB3" ]
         Variable setzen [ $$JSON ; Wert: 
            JSONDeleteElement ( $$JSON ; "Bäckerei.Produkt[" & $i & "]" ) ]
         Aktuelles Script verlassen [ Textergebnis: 0 ]
      Ende (wenn)
      Variable setzen [ $i; Wert:  $i + 1 ]
      Verlasse Schleife wenn [ $i ≥ $ProduktAnzahl ]
   Schleife (Ende)
Ende (wenn)

Behandlung von Fehlern in JSON-Daten

Wenn beim Parsen des Parameters json ein Fehler auftritt, liefert die Funktion JSON ein „?“ gefolgt von einer Fehlermeldung aus dem JSON-Parser.

Wenn beispielsweise der „:“ nach dem Schlüssel „Bäckerei“ in Beispiel für JSON-Daten fehlt, gibt diese Formel

Copy
JSONGetElement ( $$JSON ; "Bäckerei.Produkt[0]id" )

diese Fehlermeldung zurück:

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

Anhand der Funktion „JSONFormatElements“ können Sie feststellen, ob JSON-Daten gültig sind, und testen, ob das erste Zeichen ein „?“ ist. Beispiel:

Copy
Variable setzen [ $Ergebnis ; Wert: JSONFormatElements ( $$JSON ) ]
Wenn [ Links ( $Ergebnis ; 1 ) = "?" ]
   # $$JSON enthält ungültige JSON-Daten.
Ende (wenn)

Beispiel für JSON-Daten

Im folgenden Beispiel enthalten JSON-Daten ein „Bäckerei“-Objekt mit einem Array von drei „Produkt“-Objekten, jedes mit mehreren Schlüssel-Wert-Paaren.

Copy
{
    "Bäckerei" : 
    {
        "Produkt" : 
        [
            {
                "ID" : "FB1",
                "Name" "Donuts",
                "Preis": 1.99,
                "Bestand" : 43,
                "Kategorie" : "Brot",
                "Angebot" : true
            },
            {
                "ID" : "FB2",
                "Preis": 22.5,
                "Name" "Schokoladenkuchen",
                "Bestand" : 23,
                "Kategorie" : "Kuchen", 
                "Angebot" : true
            },
            {
                "ID" : "FB3",
                "Preis": 3.95,
                "Name" "Baguette",
                "Bestand" : 34,
                "Kategorie" : "Brot", 
                "Angebot" : true
            }
        ]
    }
}

Hinweise

  • Der JSON-Parser bewahrt die Reihenfolge der Elemente in einem Array, aber nicht die Reihenfolge der Elemente in einem Objekt. Daher können die JSON-Funktionen Elemente in einem Objekt in einer anderen als der angegebenen Reihenfolge zurückgeben.
  • In JSON-Daten müssen gebrochene Zahlenwerte einen Punkt „.“ als Dezimaltrennzeichen verwenden, unabhängig davon, welches Trennzeichen durch die Systemformate Ihres Computers oder die beim Erstellen der FileMaker Pro-Datei verwendeten Formate angegeben wird.