A primeira vez que escrevi uma expressão JSONPath que importava, errei três vezes antes de funcionar, e só sabia que estava errado porque o gateway de API que EU estava configurando retornava uma política vazia em vez do campo que EU queria Não havia nenhum loop de feedback Eu editaria a expressão, reimplantaria e esperaria Uma vez que EU comecei a manter um testador JSONPath aberto em outra aba, esse mesmo trabalho levou dois minutos em vez de uma tarde Este guia é sobre como EU uso o Testador JSONPath no Toolz.dev, o que a sintaxe realmente faz e as pequenas armadilhas que fazem uma expressão não retornam nada quando você tinha certeza de que deveria corresponder.
tl;dr: JSONPath é uma linguagem de consulta para JSON, da mesma forma que XPath é para XML. Um testador JSONPath avalia uma expressão como
$.store.book[*].authorcontra um documento e retorna cada valor correspondente mais seu caminho. O Testador JSONPath faz isso inteiramente em seu navegador, com suporte para curingas, descida recursiva, fatias, uniões e expressões de filtro, para que você possa criar e depurar uma consulta com dados reais antes de colá-la em código.
O que é o JSONPath?
JSONPath é uma sintaxe compacta para selecionar partes de um documento JSON Você escreve um caminho curto que descreve uma rota através dos dados, e avaliá-lo retorna o valor ou valores nessa rota A ideia vem de Stefan Goessner' proposta de 2007, que deliberadamente espelhava o XPath para que qualquer um que tivesse consultado o XML se sentisse em casa Durante anos não houve especificação formal, apenas aquele artigo e uma família de implementações que concordaram principalmente, e no início de 2024 a IETF publicou RFC 9535 para fixar a gramática.
Você encontra o JSONPath com mais frequência do que você poderia esperar É a linguagem seletora em ferramentas de teste de API como Postman e Karate, no Kubernetes kubectl formatação de saída, no AWS CloudWatch e Step Functions, em processadores de log e em dezenas de plataformas de baixo código onde um usuário precisa retirar um campo de uma carga útil do webhook sem escrever código Aprendendo que uma vez compensa em todos aqueles.
O modelo mental é simples Um documento JSON é uma árvore Os objetos têm ramos nomeados, matrizes têm ramos numerados, e as folhas são seus valores escalares Uma expressão JSONPath é um conjunto de direções para andar essa árvore, e o resultado é cada folha ou subárvore em que você pousa Onde fica poderoso é que uma única expressão pode pousar em muitos lugares de uma só vez.
O que um testador JSONPath realmente faz?
Um testador pega duas entradas, seu JSON e uma expressão, e mostra a cada nó que a expressão seleciona Isso soa óbvio, mas o valor está no feedback Quando uma expressão não retorna nada, ou retorna mais do que você esperava, um testador transforma um jogo de adivinhação em uma verificação de dois segundos, porque você pode ver exatamente quais nós correspondiam e ajustar um caractere de cada vez.
No Toolz.dev o fluxo é curto Cole um documento JSON, ou carregue a livraria de amostra que a maioria dos tutoriais JSONPath usam, digite uma expressão e avalie A ferramenta lista cada valor correspondente com uma contagem em execução, e você pode alternar a saída entre três visualizações Os valores fornecem apenas os resultados como uma matriz JSON Os caminhos fornecem a localização normalizada de cada partida, que é a maneira mais rápida de descobrir a expressão que você realmente precisa As entradas fornecem os dois juntos, para que você possa ver o caminho e o valor lado a lado.
A razão para testar contra dados reais em vez de raciocinar sobre isso em sua cabeça é que JSON do wild é mais confuso do que os exemplos Um campo às vezes é um objeto e às vezes uma matriz Uma chave que você esperava está faltando na metade dos registros Um número chegou como uma string Executando a expressão contra a carga real superfícies essas surpresas imediatamente em vez de no tempo de implantação.
Como faço para selecionar itens de uma matriz?
As matrizes são onde a maioria dos trabalhos do JSONPath acontece e existem quatro maneiras de abordá-las.
Um único índice seleciona um elemento. $.store.book[0] retorna o primeiro livro, e JSONPath, como a maioria das linguagens, conta a partir de zero Um índice negativo conta a partir do final, então $.store.book[-1] retorna o último livro sem que você precise saber quantos existem Esse formulário negativo é genuinamente útil quando você deseja o item mais recente em um log ou a entrada mais recente em um feed.
Um curinga seleciona cada elemento. $.store.book[*] retorna todos os quatro livros e $.store.book[*].author retorna o autor de cada um, dando-lhe uma gama limpa de autores O curinga também funciona em objetos, onde $.store.* retorna cada valor do objeto de armazenamento, independentemente da chave.
Uma união seleciona um conjunto específico. $.store.book[0,2] retorna o primeiro e o terceiro livros, e a mesma sintaxe de vírgula funciona com nomes, então $['store']['bicycle'] e as teclas entre colchetes permitem endereçar teclas que contêm espaços ou pontuação que a forma de ponto não consegue.
Uma fatia seleciona um intervalo, emprestando Python' s start:end:step formulário. $.store.book[:2] leva os dois primeiros, $.store.book[1:3] ocupa um intervalo intermediário com o índice final exclusivo, $.store.book[::2] pega cada segundo elemento e $.store.book[::-1] inverte a matriz As fatias são a parte menos conhecida da sintaxe e a que salva mais digitação depois de tê-la.
O que faz o ponto duplo?
O ponto duplo é uma descida recursiva e é o recurso que faz o JSONPath parecer uma pesquisa e não um caminho. $..author encontra cada author digite em qualquer lugar do documento, não importa quão profundamente ele esteja aninhado, e $..* retorna todos os valores em todos os níveis Quando você não sabe a forma exata de um documento, ou quando o mesmo campo aparece em várias profundidades, a descida recursiva encontra todos eles em uma expressão.
Considere a livraria de amostra. $..price retorna cinco valores, os quatro preços dos livros e o preço da bicicleta, porque desce em cada objeto e coleta cada um price encontra. Uma planície $.store.book[*].price retornaria apenas os quatro preços dos livros, porque percorre uma rota fixa A diferença entre essas duas expressões é a diferença entre pedir preços em um local conhecido e pedir preços em qualquer lugar.
A descida recursiva é poderosa o suficiente para ser perigosa, no sentido de que pode corresponder mais do que você quis dizer É exatamente por isso que um testador importa aqui Correr $..name contra uma carga familiar e você pode descobrir que ela corresponde a um nome de usuário, um nome de produto e um nome de arquivo que você não tinha ideia de que compartilhava uma chave. Ver os caminhos na saída informa se deve restringir a expressão antes de confiar nela.
Como funcionam as expressões de filtro?
Um filtro mantém apenas os elementos para os quais uma condição é verdadeira e está escrito [?(...)] por @ representando o elemento atual. $.store.book[?(@.price < 10)] devolve os livros mais barato que dez Dentro do filtro pode comparar um campo contra um literal com os operadores ==, !=, <, <=, >, e >=, teste a mera presença de um campo e combine condições com && e ||.
Alguns exemplos concretos deixam a forma clara:
$.store.book[?(@.category == "fiction")]seleciona os títulos de ficção.$.store.book[?(@.price < 10 && @.category == "fiction")]reduz-se à ficção barata.$.store.book[?(@.isbn)]seleciona apenas os livros que possuem ISBN, usando existência em vez de comparação.$.vals[?(@ > 2)]filtra uma matriz simples de números, onde@por si só refere-se ao próprio elemento.
O único bug de filtro mais comum é uma incompatibilidade de tipo. Em JSON, "12" e 12 são valores diferentes, então um filtro que compara um campo numérico a um número citado, ou um campo de string a um número simples, silenciosamente não corresponde a nada Quando um filtro surpreende você, a primeira coisa a verificar é se o campo e o literal são do mesmo tipo Testar a expressão contra os dados reais, onde você pode ver os valores reais, é como você pega isso em segundos, em vez de depois de uma implantação com falha.
JSONPath versus JSON Pointer versus JSON diff
Todas essas três ferramentas tocam a estrutura JSON, mas respondem a perguntas diferentes, e escolher a errada desperdiça tempo. Veja como elas se comparam:
| aproximar-se | Respostas | fósfor | melhor para |
|---|---|---|---|
| JSONPath | Quais nós satisfazem essa consulta? | Zero, um ou muitos | Extraindo campos, filtrando matrizes, explorando formas desconhecidas |
| Ponteiro JSON (RFC 6901) | O que está neste local exato? | Sempre exatamente um | Referenciando um único campo fixo, como no esquema JSON $ref |
| Diferença JSON | O que mudou entre dois documentos? | Um conjunto de alterações | Comparando duas versões dos mesmos dados |
JSON Pointer, definido em RFC 6901, aborda um lugar preciso com um caminho separado por barra como /store/book/0/title& nã£o usa curingas ou filtros Alcance para ele quando voce precisa nomear um nico campo inequivocamente Alcance para JSONPath quando uma única expressã£o deve selecionar um conjunto de campos E quando sua pergunta real e o que difere entre duas cargas em vez do que uma consulta seleciona, a json diff é a ferramenta certa Saber qual dos três você realmente precisa é metade da batalha.
Por que minha expressão não retorna resultados?
Um resultado vazio quase sempre vem de uma das poucas causas, e um testador permite descartá-las rapidamente.
O primeiro é um descompasso estrutural Você escreveu $.data.items.name quando items é uma matriz, então você precisava $.data.items[*].name com um curinga A forma de ponto entra em um objeto, e uma matriz não é um objeto com um name chave, então os becos sem saída do caminho. Mudar a visualização de saída para caminhos e pisar na expressão um segmento de cada vez mostra exatamente onde ela para de corresponder.
O segundo é um erro de ortografia ou de invólucro As teclas JSON são sensíveis a maiúsculas e minúsculas, portanto $.userId não corresponderá a userID campo, e um espaço à direita ou um erro de digitação em um nome de chave produz o mesmo silencioso nada Porque o testador mostra-lhe o documento bem ao lado da expressão, estes são rápidos para detectar.
O terceiro, como abordado acima, é uma incompatibilidade de tipo de filtro, onde uma comparação numérica é executada contra um valor de string ou o inverso O quarto está assumindo que uma chave existe em cada elemento quando existe apenas em alguns Filtros recursivos de descida e existência são os remédios usuais Em todos os casos, a correção vem de observar quais nós a expressão toca, que é precisamente para o que um testador serve.
Se você construir através da pilha da maneira que EU faço, movendo-se entre uma API Laravel, um front-end React e o script shell ocasional, o JSONPath aparece em todos os três, e um testador baseado em navegador que nunca carrega seus dados é a ferramenta que EU escrevi sobre como utilitários como esse se encaixam em um kit mais amplo no Kit de ferramentas para desenvolvedores web, e o argumento para manter esse tipo de trabalho do lado do cliente está no Privacidade de dados em ferramentas online guia.
Como isso se encaixa com o resto do meu fluxo de trabalho JSON?
Um testador JSONPath raramente é a única ferramenta aberta Quando o JSON que estou consultando chegou minificado ou com recuo inconsistente, EU o executo através do formatador json primeiro para que EU possa ler a estrutura enquanto escrevo a expressão O formatador e o testador juntos são como EU passo de uma resposta de API ilegível para uma consulta de trabalho.
Uma vez que EU sei quais campos EU me importo, o próximo passo é muitas vezes reformulá-los Se EU precisar alimentar os valores selecionados em uma planilha ou um arquivo de ambiente, o Flattener JSON transforma a estrutura aninhada em chaves de notação de pontos, e sua sintaxe de caminho está próxima o suficiente do JSONPath para que os dois se reforcem Se EU estiver construindo um tipo para os dados no TypeScript, o json para digitar conversor gera a interface, e se EU precisar validar a forma em vez de apenas lê-la, o Gerador de esquema JSON produz um esquema ao qual posso adicionar restrições JSONPath é a etapa de exploração; essas ferramentas são o que faço com o que encontro.
Vale a pena repetir o ponto de privacidade porque o trabalho do JSONPath acontece com tanta frequência contra dados confidenciais As respostas da API carregam tokens, registros de usuários e IDs internos, e colá-los em uma ferramenta do lado do servidor significa confiar em outra pessoa & #39; s logs. Como o testador Toolz.dev analisa e avalia inteiramente em seu navegador, nada disso sai de sua máquina, e a ferramenta continua trabalhando com a rede desconectada Essa é a diferença entre uma ferramenta que você pode usar em uma carga útil de estadiamento e uma que você pode usar na coisa real.
Perguntas frequentes
Para que é utilizado o JSONPath?
JSONPath é usado para selecionar e extrair partes de um documento JSON com uma única expressão É a linguagem de consulta em ferramentas de teste de API, formatação de saída do Kubernetes, serviços em nuvem como AWS Step Functions e muitas plataformas de baixo código, onde quer que alguém precise puxar um campo ou filtrar uma matriz de uma carga JSON sem escrever código processual.
Como seleciono cada elemento de uma matriz no JSONPath?
Use o curinga, então $.items[*] retorna cada elemento da matriz de itens e $.items[*].id devolve o id de cada Poderá também seleccionar um elemento por índice com $.items[0], o último elemento com o índice negativo $.items[-1], um conjunto com uma união como $.items[0,2], ou um intervalo com uma fatia como $.items[1:3].
O que significa o ponto duplo no JSONPath?
O ponto duplo é uma descida recursiva, que procura em qualquer profundidade. $..author encontra todas as chaves de autor em qualquer lugar do documento, não importa quão profundamente aninhadas, e $..* retorna todos os valores em todos os níveis É a maneira mais rápida de extrair um campo de um documento cuja estrutura exata você não conhece com antecedência.
Como funcionam as expressões de filtro no JSONPath?
Um filtro [?(...)] mantém apenas os elementos para os quais uma condição é verdadeira, com @ referindo-se ao elemento atual. Por exemplo $.book[?(@.price < 10)] devolve livros mais baratos que dez, e você pode combinar condições com && e ||, como [?(@.price < 10 && @.category == "fiction")]. Você também pode testar a existência de um campo & #39; s com [?(@.isbn)].
Por que minha expressão JSONPath não retorna nada?
As duas causas mais comuns são uma incompatibilidade estrutural e uma incompatibilidade de tipos Verifique se cada chave existe e está escrita com o invólucro exacto, e se usou um curinga onde os dados são um array em vez de um objecto Em filtros, lembre - se que o & quot;12 & quot; e o 12 são valores diferentes, por isso compare um campo de cadeia com um valor citado e um campo numérico com um número simples.
Qual é a diferença entre JSONPath e JSON Pointer?
Um JSON Pointer endereça um local exato, como /store/book/0/title, e sempre retorna um único valor JSONPath é uma linguagem de consulta onde uma única expressão pode corresponder a muitos nós de uma só vez através de curingas, descida recursiva e filtros Use um ponteiro para referenciar um campo fixo e JSONPath para selecionar um conjunto de campos ou filtrar uma coleção.
Posso ver o caminho de cada partida, não apenas o valor?
Sim. alternar o modo de saída para caminhos para obter a localização normalizada de cada partida, ou entradas para obter o caminho eo valor juntos Vendo os caminhos reais é a maneira mais rápida de refinar uma expressão até que ele seleciona exatamente os nós que você pretendia, o que é especialmente útil com descida recursiva.
Meu JSON é carregado quando uso o testador?
Não. O documento é analisado e a expressão é avaliada no seu navegador com JavaScript, portanto nada é transmitido, registrado ou armazenado. Você pode confirmá-lo assistindo à guia de rede enquanto executa uma consulta ou desconectando-se da Internet, porque o testador continua funcionando offline assim que a página for carregada.
Experimente em seus próprios dados gratuitamente Testador JSONPath. Ele avalia curingas, descidas recursivas, fatias, uniões e expressões de filtro inteiramente em seu navegador, sem nada carregado.
