De eerste keer dat ik een JSONPath-expressie schreef die er toe deed, had ik het drie keer verkeerd voordat het werkte, en ik wist alleen dat het verkeerd was omdat de API-gateway die ik aan het configureren was een leeg beleid teruggaf in plaats van het veld dat ik wilde Er was geen feedbackloop Ik zou de uitdrukking bewerken, opnieuw implementeren en wachten Als ik eenmaal begonnen was met het openhouden van een JSONPath-tester op een ander tabblad, duurde datzelfde werk twee minuten in plaats van een middag Deze gids gaat over hoe ik de JSONPath-tester op Toolz.dev, wat de syntaxis eigenlijk doet, en de kleine vallen die een uitdrukking maken, geven niets terug als je zeker wist dat het zou moeten overeenkomen.
tl;dr: JSONPath is een querytaal voor JSON, zoals XPath dat is voor XML. Een JSONPath-tester evalueert een expressie zoals
$.store.book[*].authortegen een document en geeft elke overeenkomende waarde plus zijn pad terug De JSONPath-tester doet dit volledig in uw browser, met ondersteuning voor jokertekens, recursieve afdaling, plakjes, unions en filterexpressies, zodat u een query kunt bouwen en debuggen met echte gegevens voordat u deze in code plakt.
Wat is JSONPath?
JSONPath is een compacte syntaxis voor het selecteren van delen van een JSON-document U schrijft een kort pad dat een route door de gegevens beschrijft, en het evalueren ervan geeft de waarde of waarden op die route terug Het idee komt van Stefan Goessner's voorstel uit 2007, die opzettelijk XPath weerspiegelde, zodat iedereen die XML had opgevraagd zich thuis zou voelen Jarenlang was er geen formele specificatie, alleen dat artikel en een familie van implementaties die het grotendeels eens waren, en begin 2024 publiceerde de IETF RFC-9535 om de grammatica vast te pinnen.
Je ontmoet JSONPath vaker dan je zou verwachten Het is de selectortaal in API-testtools zoals Postman en Karate, in Kubernetes kubectl uitvoeropmaak, in AWS CloudWatch en Step Functions, in logprocessors, en in tientallen low-code platforms waar een gebruiker één veld uit een webhook payload moet trekken zonder code te schrijven Het eenmaal leren betaalt terug over al die.
Het mentale model is eenvoudig Een JSON document is een boom Objecten hebben takken benoemd, arrays hebben genummerde takken, en de bladeren zijn je scalaire waarden Een JSONPath uitdrukking is een set van richtingen voor het lopen van die boom, en het resultaat is elk blad of subboom waar je op landt Waar het krachtig wordt is dat een enkele uitdrukking op vele plaatsen tegelijk kan landen.
Wat doet een JSONPath tester eigenlijk?
Een tester neemt twee ingangen, je JSON en een expressie, en laat je elk knooppunt zien dat de expressie selecteert Dat klinkt voor de hand liggend, maar de waarde zit in de feedback Wanneer een expressie niets teruggeeft, of meer teruggeeft dan je had verwacht, verandert een tester een raadspel in een controle van twee seconden, omdat je precies kunt zien welke knooppunten overeenkwamen en één teken tegelijk kunt aanpassen.
Op Toolz.dev is de stroom kort Een JSON-document plakken, of de voorbeeldboekwinkel laden die de meeste JSONPath-tutorials gebruiken, een expressie typen en evalueren De tool vermeldt elke overeenkomende waarde met een lopende telling, en je kunt de uitvoer schakelen tussen drie weergaven Waarden geven je alleen de resultaten als een JSON-array Paden geeft je de genormaliseerde locatie van elke overeenkomst, wat de snelste manier is om de expressie te ontdekken die je eigenlijk nodig hebt Inzendingen geven je beide samen, zodat je het pad en de waarde naast elkaar kunt zien.
De reden om te testen tegen echte data in plaats van er reden over te hebben in je hoofd is dat JSON uit het wild rommeliger is dan de voorbeelden Een veld is soms een object en soms een array Een sleutel die je verwachtte ontbreekt op de helft van de records Een nummer kwam als een string aan de uitdrukking tegen de werkelijke payload aan oppervlakten die verrassingen onmiddellijk in plaats van op de implementatie tijd.
Hoe selecteer ik items uit een array?
Arrays zijn waar het meeste JSONPath-werk plaatsvindt, en er zijn vier manieren om deze aan te pakken.
Een enkele index selecteert één element. $.store.book[0] geeft het eerste boek terug, en JSONPath telt, zoals de meeste talen, vanaf nul Een negatieve index telt vanaf het einde, dus $.store.book[-1] retourneert het laatste boek zonder dat u hoeft te weten hoeveel het er zijn. Dat negatieve formulier is echt handig als u het meest recente item in een logboek of het laatste item in een feed wilt.
Een jokerteken selecteert elk element. $.store.book[*] geeft alle vier de boeken terug, en $.store.book[*].author geeft de auteur van elk terug, waardoor u een schone reeks auteurs krijgt De wildcard werkt ook op objecten, waar $.store.* retourneert elke waarde van het winkelobject, ongeacht de sleutel.
Een vakbond selecteert een specifieke set. $.store.book[0,2] retourneert het eerste en derde boek, en dezelfde kommasyntaxis werkt met namen, dus $['store']['bicycle'] en met tussen haakjes geciteerde toetsen kunt u toetsen adresseren die spaties of interpunctie bevatten die de puntvorm niet kan.
Een plak selecteert een bereik en leent Python's start:end:step form. $.store.book[:2] neemt de eerste twee, $.store.book[1:3] neemt een middenbereik met de eindindex exclusief, $.store.book[::2] neemt elk tweede element, en $.store.book[::-1] draait de array om Plakjes zijn het minst bekende deel van de syntaxis en degene die het meeste typen opslaat zodra je het hebt.
Wat doet de dubbele stip?
De dubbele stip is recursieve afdaling en het is de functie die ervoor zorgt dat JSONPath eerder als een zoekopdracht dan als een pad aanvoelt. $..author vindt elke author sleutel overal in het document, ongeacht hoe diep het is genest, en $..* geeft elke waarde op elk niveau terug Wanneer je de exacte vorm van een document niet weet, of wanneer hetzelfde veld op meerdere diepten verschijnt, vindt recursieve afdaling ze allemaal in één uitdrukking.
Denk aan de voorbeeldboekhandel. $..price geeft vijf waarden terug, de vier boekenprijzen en de fietsprijs, omdat het in elk object afdaalt en elke waarde verzamelt price het vindt. Een vlakte $.store.book[*].price zou alleen de vier boekenprijzen teruggeven, want het loopt een vaste route Het verschil tussen die twee uitdrukkingen is het verschil tussen het vragen van prijzen op een bekende locatie en het vragen van prijzen overal.
Recursieve afdaling is krachtig genoeg om gevaarlijk te zijn, in de zin dat het meer kan evenaren dan je bedoelde, Dat is precies waarom een tester hier ertoe doet Ren $..name tegen een onbekende payload en je zou kunnen ontdekken dat het overeenkomt met een gebruikersnaam, een productnaam en een bestandsnaam waarvan je geen idee had dat het een sleutel deelde. Als je de paden in de uitvoer ziet, kun je zien of je de expressie moet verkleinen voordat je erop vertrouwt.
Hoe werken filteruitdrukkingen?
Een filter bewaart alleen de elementen waarvoor een voorwaarde waar is, en deze is geschreven [?(...)] van @ staan voor het huidige element. $.store.book[?(@.price < 10)] retourneert de boeken goedkoper dan tien Binnenin het filter kun je een veld vergelijken met een letterlijke met de operatoren ==, !=, <, <=, >, en >=, test op de loutere aanwezigheid van een veld en combineer omstandigheden met && en ||.
Een paar concrete voorbeelden maken de vorm duidelijk
$.store.book[?(@.category == "fiction")]selecteert de fictietitels.$.store.book[?(@.price < 10 && @.category == "fiction")]beperkt zich tot goedkope fictie.$.store.book[?(@.isbn)]selecteert alleen de boeken met een ISBN, waarbij gebruik wordt gemaakt van het bestaan in plaats van vergelijking.$.vals[?(@ > 2)]filtert een gewone reeks getallen, waarbij@op zichzelf verwijst naar het element zelf.
De meest voorkomende filterbug is een type-mismatch. In JSON, "12" en 12 zijn verschillende waarden, dus een filter dat een numeriek veld vergelijkt met een geciteerd getal, of een tekenreeksveld met een kaal getal, komt stilletjes met niets overeen Wanneer een filter je verrast, is het eerste dat je moet controleren of het veld en de letterlijke hetzelfde type zijn. Het testen van de uitdrukking aan de hand van de echte gegevens, waar je de werkelijke waarden kunt zien, is hoe je dat in seconden oppakt in plaats van na een mislukte implementatie.
JSONPath versus JSON Pointer versus een JSON-diff
Deze drie tools raken allemaal de JSON-structuur, maar ze beantwoorden verschillende vragen, en het kiezen van de verkeerde verspilt tijd. Hier is hoe ze zich verhouden:
| toegang | Antwoorden | wedstrijd | het beste voor |
|---|---|---|---|
| JSONPath | Welke knooppunten voldoen aan deze vraag? | Nul, één of veel | Velden extraheren, arrays filteren, onbekende vormen verkennen |
| JSON-aanwijzer (RFC 6901) | Wat is er precies op deze locatie? | Altijd precies een | Verwijzend naar een enkel vast veld, zoals in JSON Schema $ref |
| JSON diff | Wat veranderde er tussen twee documenten? | Een set wijzigingen | Twee versies van dezelfde gegevens vergelijken |
JSON-aanwijzer, gedefinieerd in RFC 6901, richt zich op één precieze plaats met een door schuine strepen gescheiden pad zoals /store/book/0/title, en het maakt nooit gebruik van jokertekens of filters Bereik ervoor wanneer u een enkel veld ondubbelzinnig moet benoemen Bereik voor JSONPath wanneer een enkele expressie een set velden zou moeten selecteren En wanneer uw echte vraag is wat er verschilt tussen twee payloads in plaats van wat een query selecteert, a JSON-differentiatie is het juiste gereedschap Weten welke van de drie je eigenlijk nodig hebt is de helft van het gevecht.
Waarom levert mijn uitdrukking geen resultaat op?
Een leeg resultaat komt bijna altijd voort uit een van de weinige oorzaken, en met een tester kun je ze snel uitsluiten.
De eerste is een structurele mismatch Je schreef $.data.items.name wanneer items is een array, dus je had nodig $.data.items[*].name met een jokerteken De puntvorm loopt in een object, en een array is geen object met een name toets, dus het pad loopt dood. 'De uitvoerweergave naar paden schakelen en de uitdrukking segment voor segment opvoeren, laat u precies zien waar deze niet meer overeenkomt.
De tweede is een spelling - of behuizingsfout JSON-sleutels zijn hoofdlettergevoelig, dus $.userId zal niet overeenkomen met a userID veld, en een volgspatie of een typefout in een sleutelnaam levert hetzelfde stille niets op Omdat de tester u het document direct naast de uitdrukking laat zien, zijn deze snel te herkennen.
De derde, zoals hierboven behandeld, is een mismatch van het filtertype, waarbij een numerieke vergelijking tegen een tekenreekswaarde of de omgekeerde loopt, de vierde gaat ervan uit dat er op elk element een sleutel bestaat terwijl deze op slechts enkele bestaat Recursieve afdalings- en bestaansfilters zijn de gebruikelijke remedies. In elk geval komt de oplossing voort uit het kijken welke knooppunten de uitdrukking raakt, en dat is precies waar een tester voor is.
Als je over de stapel bouwt zoals ik dat doe, bewegend tussen een Laravel API, een React front end, en af en toe een shell script, komt JSONPath in alle drie voor, en een browser-gebaseerde tester die nooit je data uploadt is de tool die ik het dichtst bij houd Ik schreef over hoe hulpprogramma's zoals deze in een bredere kit passen in de Webontwikkelaar Toolkit, en de argumenten voor het behouden van dit soort werk aan de klantzijde liggen in de Gegevensprivacy in online tools guide.
Hoe past dit bij de rest van mijn JSON workflow?
Een JSONPath-tester is zelden het enige gereedschap dat open is. Wanneer de JSON die ik bevraag, geniniificeerd of met inconsistente inkeping arriveerde, voer ik hem door de JSON-formatter eerst zodat ik de structuur kan lezen terwijl ik de uitdrukking schrijf, De formatter en de tester samen zijn hoe ik van een onleesbaar API-antwoord naar een werkquery ga.
Als ik eenmaal weet om welke velden ik geef, is de volgende stap vaak om ze opnieuw vorm te geven Als ik de geselecteerde waarden moet invoeren in een spreadsheet of een omgevingsbestand, wordt de JSON Flattener verandert de geneste structuur in dot-notation-toetsen, en de padsyntaxis ligt zo dicht bij JSONPath dat de twee elkaar versterken Als ik een type aan het bouwen ben voor de gegevens in TypeScript, zal de json naar typoscript converter genereert de interface, en als ik de vorm moet valideren in plaats van alleen maar te lezen, zal de JSON-schemagenerator produceert een schema waaraan ik beperkingen kan toevoegen JSONPath is de verkenningsstap; deze tools zijn wat ik doe met wat ik vind.
Het privacypunt is het herhalen waard omdat JSONPath zo vaak tegen gevoelige gegevens werkt API-reacties dragen tokens, gebruikersrecords en interne ID's, en als je ze in een tool aan de serverzijde plakt, betekent dit dat je iemand anders vertrouwt. ' logt Omdat de Toolz.dev-tester volledig in je browser parseert en evalueert, blijft niets daarvan uw machine over, en blijft de tool werken terwijl het netwerk is verbroken. Dat is het verschil tussen een tool die u kunt gebruiken op een ensceneringspayload en een tool die u op het echte werk kunt gebruiken.
Veelgestelde vragen
Waar wordt JSONPath voor gebruikt?
JSONPath wordt gebruikt om delen van een JSON-document met één enkele expressie te selecteren en uit te pakken Het is de querytaal in API-testtools, Kubernetes-uitvoeropmaak, cloudservices zoals AWS Step Functions en veel low-code platforms, waar iemand een veld moet uittrekken of een array uit een JSON-payload moet filteren zonder procedurele code te schrijven.
Hoe selecteer ik elk element van een array in JSONPath?
Gebruik de wildcard, dus $.items[*] retourneert elk element van de itemsarray en $.items[*].id retourneert de id van elk U kunt ook één element selecteren op index met $.items[0], het laatste element met de negatieve index $.items[-1], een set met een unie zoals $.items[0,2], of een bereik met een plak als $.items[1:3].
Wat betekent de dubbele stip in JSONPath?
De dubbele stip is een recursieve afdaling, die op elke diepte zoekt. $..author vindt elke auteurssleutel overal in het document, hoe diep genest ook, en $..* geeft elke waarde op elk niveau terug Het is de snelste manier om een veld uit een document te trekken waarvan je de exacte structuur niet van tevoren weet.
Hoe werken filteruitdrukkingen in JSONPath?
Een filter [?(...)] houdt alleen de elementen waarvoor een voorwaarde waar is, met @ verwijzend naar het huidige element Bijvoorbeeld $.book[?(@.price < 10)] retourneert boeken goedkoper dan tien, en u kunt voorwaarden combineren met && en ||, zoals [?(@.price < 10 && @.category == "fiction")]. U kunt ook testen op een veld's bestaan met [?(@.isbn)].
Waarom levert mijn JSONPath-uitdrukking niets op?
De twee meest voorkomende oorzaken zijn een structurele mismatch en een typemismatch Controleer of elke toets bestaat en gespeld is met de exacte behuizing, en dat u een joker hebt gebruikt waarbij de gegevens een array zijn in plaats van een object In filters onthoud dat "12" en 12 verschillende waarden zijn, dus vergelijk een tekenreeksveld met een opgegeven waarde en een numeriek veld met een kaal getal.
Wat is het verschil tussen JSONPath en JSON Pointer?
Een JSON Pointer richt zich op één exacte locatie, zoals /store/book/0/title, en retourneert altijd een enkele waarde JSONPath is een querytaal waarbij een enkele expressie vele knooppunten tegelijk kan matchen via jokertekens, recursieve afdaling en filters. Gebruik een pointer om naar één vast veld te verwijzen, en JSONPath om een reeks velden te selecteren of een verzameling te filteren.
Kan ik het pad van elke match zien, niet alleen de waarde?
Ja. schakel de uitvoermodus naar paden om de genormaliseerde locatie van elke overeenkomst te krijgen, of invoer om het pad en de waarde bij elkaar te krijgen. Het zien van de echte paden is de snelste manier om een expressie te verfijnen totdat deze precies de knooppunten selecteert die u bedoelde, wat vooral handig is bij recursieve afdaling.
Wordt mijn JSON geüpload als ik de tester gebruik?
Nee Het document wordt geparseerd en de expressie wordt geëvalueerd in uw browser met JavaScript, zodat niets wordt verzonden, gelogd of opgeslagen U kunt het bevestigen door het netwerk tabblad te bekijken terwijl u een query uitvoert, of door de verbinding met het internet te verbreken, omdat de tester offline blijft werken zodra de pagina is geladen.
Probeer het op uw eigen gegevens met de gratis JSONPath-tester. Het evalueert jokertekens, recursieve afdaling, plakjes, unies en filterexpressies volledig in uw browser, zonder dat er iets is geüpload.
