Als ich das erste Mal einen JSONPath-Ausdruck schrieb, der zählte, hatte ich mich dreimal geirrt, bevor er funktionierte, und ich wusste nur, dass er falsch war, weil das API-Gateway, das ich konfigurierte, eine leere Richtlinie anstelle des gewünschten Feldes zurückgab Es gab keine Rückkopplungsschleife Ich würde den Ausdruck bearbeiten, neu einsetzen und warten. Sobald ich anfing, einen JSONPath-Tester in einem anderen Tab offen zu halten, dauerte dieselbe Arbeit zwei Minuten statt eines Nachmittags. In diesem Leitfaden geht es darum, wie ich den JSONPath-Tester Auf Toolz.dev, was die Syntax tatsächlich bewirkt, und die kleinen Fallen, die einen Ausdruck erzeugen, geben nichts zurück, wenn Sie sicher waren, dass er übereinstimmen sollte.
tl; dr: JSONPath ist eine Abfragesprache für JSON, so wie XPath für XML ist Ein JSONPath-Tester wertet einen Ausdruck wie
$.store.book[*].authorGegen ein Dokument und gibt jeden Matching-Wert plus seinen Pfad zurück Die JSONPath-Tester Tut dies vollständig in Ihrem Browser, mit Unterstützung für Platzhalter, rekursive Abfahrt, Slices, Vereinigungen und Filterausdrücke, so dass Sie eine Abfrage erstellen und mit echten Daten debuggen können, bevor Sie sie in Code einfügen.
Was ist JSONPath?
JSONPath ist eine kompakte Syntax zur Auswahl von Teilen eines JSON-Dokuments, Sie schreiben einen kurzen Pfad, der eine Route durch die Daten beschreibt, und die Auswertung gibt den Wert oder die Werte auf dieser Route zurück Die Idee stammt von Stefan Goessner's Vorschlag von 2007, die bewusst XPath gespiegelt hat, damit sich jeder, der XML abgefragt hatte, wie zu Hause fühlt Jahrelang gab es keine formale Spezifikation, nur diesen Artikel und eine Familie von Implementierungen, die größtenteils übereinstimmten, und Anfang 2024 veröffentlichte die IETF RFC 9535 Grammatik festzustecken.
Sie treffen JSONPath häufiger, als Sie vielleicht erwarten Es ist die Selektorsprache in API-Testtools wie Postman und Karate, in Kubernetes kubectl Ausgabeformatierung, in AWS CloudWatch und Step Functions, in Protokollprozessoren und in Dutzenden von Low-Code-Plattformen, auf denen ein Benutzer ein Feld aus einer Webhook-Nutzlast ziehen muss, ohne Code zu schreiben. Einmal zu lernen zahlt sich in all diesen aus.
Das mentale Modell ist einfach Ein JSON-Dokument ist ein Baum Objekte haben Äste benannt, Arrays haben nummerierte Äste, und die Blätter sind Ihre skalaren Werte Ein JSONPath-Ausdruck ist eine Reihe von Richtungen zum Gehen dieses Baumes, und das Ergebnis ist jedes Blatt oder jeder Teilbaum, auf dem Sie landen. Wo es mächtig wird, ist, dass ein einzelner Ausdruck auf viele Orte gleichzeitig landen kann.
Was macht eigentlich ein JSONPath-Tester?
Ein Tester nimmt zwei Eingaben, Ihren JSON und einen Ausdruck, und zeigt Ihnen jeden Knoten, den der Ausdruck auswählt Das klingt offensichtlich, aber der Wert ist im Feedback Wenn ein Ausdruck nichts zurückgibt, oder mehr zurückgibt, als Sie erwartet haben, verwandelt ein Tester ein Ratespiel in einen Zwei-Sekunden-Check, denn Sie können genau sehen, welche Knoten übereinstimmen und jeweils ein Zeichen anpassen.
Auf Toolz.dev ist der Fluss kurz Fügen Sie ein JSON-Dokument ein, oder laden Sie den Beispielbuchladen, den die meisten JSONPath-Tutorials verwenden, geben Sie einen Ausdruck ein und bewerten Sie Das Tool listet jeden übereinstimmenden Wert mit einer laufenden Zählung auf, und Sie können die Ausgabe zwischen drei Ansichten umschalten Werte gibt Ihnen nur die Ergebnisse als JSON-Array Pfade gibt Ihnen den normalisierten Ort jedes Spiels, was die schnellste Möglichkeit ist, den Ausdruck zu entdecken, den Sie tatsächlich benötigen Einträge gibt Ihnen beide zusammen, so dass Sie den Pfad und den Wert Seite an Seite sehen können.
Der Grund, gegen reale Daten zu testen, anstatt im Kopf darüber nachzudenken, ist, dass JSON aus der Wildnis chaotischer ist als die Beispiele Ein Feld ist mal ein Objekt und mal ein Array Auf der Hälfte der Datensätze fehlt ein Schlüssel, den man erwartet hat Eine Zahl kam als Zeichenfolge an, Ausführen des Ausdrucks gegen die eigentliche Nutzlastoberflächen diese Überraschungen sofort statt zur Bereitstellungszeit.
Wie wähle ich Elemente aus einem Array aus?
In Arrays finden die meisten JSONPath-Arbeiten statt und es gibt vier Möglichkeiten, sie zu beheben.
Ein einzelner Index wählt ein Element aus. $.store.book[0] Erstes Buch zurückgibt, und JSONPath zählt, wie die meisten Sprachen, ab Null Ein negativer Index zählt vom Ende an, also $.store.book[-1] Gibt das letzte Buch zurück, ohne dass Sie wissen müssen, wie viele es sind. Diese negative Form ist wirklich nützlich, wenn Sie das neueste Element in einem Protokoll oder den neuesten Eintrag in einem Feed wünschen.
Eine Platzhalter wählt jedes Element aus. $.store.book[*] Alle vier Bücher zurückgibt, und $.store.book[*].author Gibt den Autor von jedem zurück, was Ihnen ein sauberes Array von Autoren gibt Die Platzhalterung funktioniert auch auf Objekten, wo $.store.* Gibt jeden Wert des Speicherobjekts unabhängig vom Schlüssel zurück.
Eine Gewerkschaft wählt eine bestimmte Menge aus. $.store.book[0,2] Gibt das erste und dritte Buch zurück, und dieselbe Kommasyntax funktioniert mit Namen, also $['store']['bicycle'] Mit in Klammern zitierten Tasten können Sie Tasten ansprechen, die Leerzeichen oder Satzzeichen enthalten, die die Punktform nicht enthalten kann.
Ein Slice wählt einen Bereich aus und leiht sich Python's start:end:step Form. $.store.book[:2] Nimmt die ersten beiden, $.store.book[1:3] Mittelbereich nimmt, wobei der Endindex exklusiv ist, $.store.book[::2] Nimmt jedes zweite Element und $.store.book[::-1] Reversiert das Array Slices sind der am wenigsten bekannte Teil der Syntax und derjenige, der die meiste Eingabe speichert, sobald Sie ihn haben.
Was macht der doppelte Punkt?
Der doppelte Punkt ist rekursiver Abstieg und es ist die Funktion, die JSONPath eher wie eine Suche als wie einen Pfad erscheinen lässt. $..author Findet jedes author Schlüssel überall im Dokument, egal wie tief es verschachtelt ist, und $..* Gibt jeden Wert auf jeder Ebene zurück, wenn man die genaue Form eines Dokuments nicht kennt, oder wenn dasselbe Feld in mehreren Tiefen erscheint, findet rekursiver Abstieg alle in einem Ausdruck.
Betrachten Sie die Musterbuchhandlung. $..price Gibt fünf Werte zurück, die vier Buchpreise und den Fahrradpreis, denn er steigt in jedes Objekt herab und sammelt jedes price Es findet. Eine Ebene $.store.book[*].price Würde nur die vier Buchpreise zurückgeben, denn es geht eine feste Route Der Unterschied zwischen diesen beiden Ausdrücken ist der Unterschied zwischen der Preisanfrage an einem bekannten Ort und der Preisanfrage an einem beliebigen Ort.
Rekursiver Abstieg ist stark genug, um gefährlich zu sein, in dem Sinne, dass er mehr mithalten kann, als du gemeint hast Genau deshalb zählt hier ein Tester Laufen $..name Gegen eine unbekannte Nutzlast und Sie könnten feststellen, dass sie mit einem Benutzernamen, einem Produktnamen und einem Dateinamen übereinstimmt, von dem Sie keine Ahnung hatten, dass er einen Schlüssel gemeinsam genutzt hat. Wenn Sie die Pfade in der Ausgabe sehen, erfahren Sie, ob Sie den Ausdruck einschränken sollen, bevor Sie sich darauf verlassen.
Wie funktionieren Filterausdrücke?
Ein Filter behält nur die Elemente, für die eine Bedingung wahr ist, und wird geschrieben [?(...)] trotz @ Stehen für das aktuelle Element. $.store.book[?(@.price < 10)] Gibt die Bücher günstiger zurück als zehn. Im Filter können Sie ein Feld mit einem Literal mit den Operatoren vergleichen ==, !=, <, <=, >, und >=testet das bloße Vorhandensein eines Feldes und kombiniert die Bedingungen mit && und ||drohen
Ein paar konkrete Beispiele machen die Form deutlich:
$.store.book[?(@.category == "fiction")]Wählt die Belletristiktitel aus.$.store.book[?(@.price < 10 && @.category == "fiction")]Verengt sich zu billiger Fiktion.$.store.book[?(@.isbn)]Wählt nur die Bücher aus, die eine ISBN haben, und verwendet dabei eher Existenz als Vergleich.$.vals[?(@ > 2)]Filtert eine einfache Reihe von Zahlen, wobei@Bezieht sich allein auf das Element selbst.
Der häufigste Filterfehler ist eine Typfehlanpassung. In JSON, "12" und 12 Unterschiedliche Werte sind, also ein Filter, der ein numerisches Feld mit einer zitierten Zahl vergleicht, oder ein Zeichenfolgenfeld mit einer bloßen Zahl, stimmt lautlos mit nichts übereinWenn ein Filter Sie überrascht, ist als erstes zu prüfen, ob das Feld und das Literal vom gleichen Typ sind Testen des Ausdrucks anhand der realen Daten, wo Sie die tatsächlichen Werte sehen können, ist, wie Sie das in Sekunden fangen, anstatt nach einem fehlgeschlagenen Deploy.
JSONPath gegen JSON Pointer gegen einen JSON-Diff
Diese drei Tools berühren alle die JSON-Struktur, beantworten jedoch unterschiedliche Fragen und die Auswahl des falschen Tools verschwendet Zeit. So vergleichen sie sich:
| heraufkommen | Antworten | Streichhöl | am besten für |
|---|---|---|---|
| JSONPath | Welche Knoten erfüllen diese Abfrage? | Null, eins oder viele | Extrahieren von Feldern, Filtern von Arrays, Erkunden unbekannter Formen |
| JSON-Zeiger (RFC 6901) | Was befindet sich genau an diesem Ort? | Immer genau eine | Referenzieren eines einzelnen festen Feldes, wie im JSON-Schema $ref |
| JSON-Diff | Was hat sich zwischen zwei Dokumenten geändert? | Eine Reihe von Änderungen | Vergleich zweier Versionen derselben Daten |
JSON-Zeiger, definiert in RFC 6901, adressiert eine genaue Stelle mit einem durch Schrägstriche getrennten Pfad wie /store/book/0/title‘und es verwendet niemals Platzhalter oder Filter Greifen Sie danach, wenn Sie ein einzelnes Feld eindeutig benennen müssen Greifen Sie nach JSONPath, wenn ein einzelner Ausdruck eine Menge von Feldern auswählen soll Und wenn Ihre eigentliche Frage ist, was sich zwischen zwei Nutzlasten unterscheidet, anstatt was eine Abfrage auswählt, a json diff Das richtige Werkzeug ist zu wissen, welche der drei man überhaupt braucht, ist die halbe Miete.
Warum liefert mein Ausdruck keine Ergebnisse?
Ein leeres Ergebnis kommt fast immer aus einer von wenigen Ursachen, und ein Tester lässt Sie diese schnell ausschließen.
Das erste ist ein strukturelles Missverhältnis Du hast geschrieben $.data.items.name wenn items Array ist, so dass Sie brauchten $.data.items[*].name Mit einer Platzhalter Die Punktform geht in ein Objekt, und ein Array ist kein Objekt mit einem name Schlüssel, so dass der Pfad in Sackgassen gerät Das Umschalten der Ausgabeansicht auf Pfade und das Schrittsetzen des Ausdrucks ein Segment nach dem anderen zeigt Ihnen genau an, wo er nicht mehr übereinstimmt.
Der zweite ist ein Rechtschreib - oder Gehäuseschutzfehler JSON-Schlüssel sind Groß - und Kleinschreibung, also $.userId Nicht mit a übereinstimmen wird userID Feld, und ein nachlaufendes Leerzeichen oder ein Tippfehler in einem Tastennamen erzeugt das gleiche stille Nichts, Weil der Tester Ihnen das Dokument direkt neben dem Ausdruck zeigt, sind diese schnell zu erkennen.
Der dritte ist, wie oben behandelt, ein Filtertyp-Mismatch, bei dem ein numerischer Vergleich gegen einen String-Wert oder umgekehrt läuft Der vierte geht davon aus, dass auf jedem Element ein Schlüssel existiert, wenn er nur auf einigen existiert Rekursiver Abstieg und Existenzfilter sind die üblichen Abhilfemaßnahmen In jedem Fall kommt der Fix daher, dass beobachtet wird, welche Knoten der Ausdruck berührt, wofür ein Tester genau da ist.
Wenn Sie so über den Stapel bauen, wie ich es tue, und zwischen einer Laravel-API, einem React-Frontend und gelegentlichem Shell-Skript wechseln, erscheint JSONPath in allen dreien, und ein browserbasierter Tester, der Ihre Daten nie hochlädt, ist das Tool, das ich am nächsten halte Ich habe darüber geschrieben, wie solche Dienstprogramme in ein breiteres Kit im passen Webentwickler-Toolkit, und die Argumente dafür, diese Art von Arbeit auf der Kundenseite beizubehalten, liegen in der Datenschutz in Online-Tools Führung.
Wie passt das zu meinem restlichen JSON-Workflow?
Ein JSONPath-Tester ist selten das einzige Tool, das geöffnet ist. Wenn der JSON, den ich abfrage, minifiziert oder mit inkonsistenter Einrückung angekommen ist, führe ich ihn durch JSON-Formater Zuerst, damit ich die Struktur lesen kann, während ich den Ausdruck schreibe Der Formatierer und der Tester zusammen sind, wie ich von einer unlesbaren API-Antwort zu einer funktionierenden Abfrage gehe.
Wenn ich weiß, welche Felder mir wichtig sind, dann geht es oft im nächsten Schritt darum, sie umzugestalten, wenn ich die ausgewählten Werte in eine Tabellenkalkulation oder eine Umgebungsdatei einspeisen muss, wird die JSON Flattener Verwendet die verschachtelte Struktur in Punktnotationstasten, und ihre Pfad-Syntax ist nahe genug an JSONPath, dass die beiden sich gegenseitig verstärken Wenn ich einen Typ für die Daten in TypeScript baue, wird die json zu typeScript Konverter generiert die Schnittstelle, und wenn ich die Form validieren muss, anstatt sie nur zu lesen, wird die JSON-Schema-Generator Erzeugt ein Schema, dem ich Einschränkungen hinzufügen kann JSONPath ist der Explorationsschritt; Diese Tools sind das, was ich mit dem mache, was ich finde.
Der Datenschutzpunkt ist es wert, wiederholt zu werden, da JSONPath-Arbeit so oft gegen sensible Daten geschieht API-Antworten tragen Token, Benutzerdatensätze und interne IDs, und das Einfügen in ein serverseitiges Tool bedeutet, jemand anderem zu vertrauen's-Protokolle. Weil der Toolz.dev-Tester Token, Benutzerdatensätze und interne IDs vollständig in Ihrem Browser analysiert und auswertet, verlässt nichts davon Ihre Maschine und das Tool arbeitet weiterhin mit dem Netzwerk getrennt Das ist der Unterschied zwischen einem Tool, das Sie für eine Staging-Nutzlast verwenden können, und einem, das Sie für die Realität verwenden können.
Häufig gestellte Fragen
Wofür wird JSONPath angewendet?
JSONPath wird verwendet, um Teile eines JSON-Dokuments mit einem einzigen Ausdruck auszuwählen und zu extrahieren. Es ist die Abfragesprache in API-Testtools, Kubernetes-Ausgabeformatierung, Cloud-Diensten wie AWS Step Functions und vielen Low-Code-Plattformen, wo immer jemand ein Feld ziehen oder ein Array aus einer JSON-Nutzlast filtern muss, ohne prozeduralen Code zu schreiben.
Wie wähle ich jedes Element eines Arrays in JSONPath aus?
Verwenden Sie also die Wildcard $.items[*] Gibt jedes Element des Items-Arrays zurück und $.items[*].id Gibt jeweils die id zurück Sie können auch ein Element nach Index mit auswählen $.items[0]Das letzte Element mit dem negativen Index $.items[-1], ein Set mit einer Gewerkschaft wie $.items[0,2]oder ein Bereich mit einem Slice wie $.items[1:3]drohen
Was bedeutet der doppelte Punkt in JSONPath?
Der Doppelpunkt ist der rekursive Abstieg, der in jeder Tiefe sucht. $..author Findet jeden Autorenschlüssel irgendwo im Dokument, egal wie tief verschachtelt, und $..* Gibt jeden Wert auf jedem Level zurück Es ist der schnellste Weg, ein Feld aus einem Dokument herauszuziehen, dessen genaue Struktur man nicht im Voraus kennt.
Wie funktionieren Filterausdrücke in JSONPath?
Ein Filter [?(...)] Behält nur die Elemente bei, für die eine Bedingung wahr ist, mit @ Bezug auf das aktuelle Element Zum Beispiel $.book[?(@.price < 10)] Gibt Bücher billiger als zehn zurück, und Sie können Bedingungen mit kombinieren && und ||(wie z [?(@.price < 10 && @.category == "fiction")]. Sie können auch auf ein Feld testen's Existenz mit [?(@.isbn)]drohen
Warum gibt mein JSONPath-Ausdruck nichts zurück?
Die beiden häufigsten Ursachen sind eine strukturelle Nichtübereinstimmung und eine Typinkongruenz Überprüfen Sie, ob jeder Schlüssel existiert und mit dem genauen Gehäuse geschrieben wird, und dass Sie eine Platzhalterkarte verwendet haben, bei der die Daten ein Array und kein Objekt sind Denken Sie in Filtern daran, dass & quot;12" und 12 unterschiedliche Werte sind, also vergleichen Sie ein Zeichenfolgenfeld mit einem zitierten Wert und ein numerisches Feld mit einer bloßen Zahl.
Was ist der Unterschied zwischen JSONPath und JSON Pointer?
Ein JSON Pointer adressiert einen exakten Ort, wie /store/book/0/title, und gibt immer einen einzelnen Wert zurück JSONPath ist eine Abfragesprache, bei der ein einzelner Ausdruck durch Platzhalter, rekursiven Abstieg und Filter viele Knoten gleichzeitig abgleichen kann Verwenden Sie einen Zeiger, um auf ein festes Feld zu verweisen, und JSONPath, um einen Satz Felder auszuwählen oder eine Sammlung zu filtern.
Kann ich den Pfad jedes Spiels sehen, nicht nur den Wert?
Ja. Den Ausgabemodus auf Pfade umschalten, um den normalisierten Ort jeder Übereinstimmung zu erhalten, oder Einträge, um den Pfad und den Wert zusammen zu bekommen Das Sehen der realen Pfade ist der schnellste Weg, einen Ausdruck zu verfeinern, bis er genau die Knoten auswählt, die Sie beabsichtigt haben, was besonders beim rekursiven Abstieg hilfreich ist.
Wird mein JSON hochgeladen, wenn ich den Tester verwende?
Nein. Das Dokument wird geparst und der Ausdruck in Ihrem Browser mit JavaScript ausgewertet, es wird also nichts übertragen, protokolliert oder gespeichert Sie können es bestätigen, indem Sie den Netzwerk-Tab ansehen, während Sie eine Abfrage ausführen, oder indem Sie die Verbindung zum Internet trennen, da der Tester nach dem Laden der Seite weiterhin offline arbeitet.
Probieren Sie es mit Ihren eigenen Daten aus, mit dem kostenlosen JSONPath-Tester. Es wertet Wildcards, rekursive Abstieg, Slices, Vereinigungen und Filterausdrücke vollständig in Ihrem Browser aus, ohne dass etwas hochgeladen wurde.
