ConvertFrom-Json

  • Referência
Módulo:
Microsoft.PowerShell.Utility

Converte uma cadeia formatada em JSON num objeto personalizado ou numa tabela hash.

Sintaxe

ConvertFrom-Json
                [-InputObject] <String>
                [-AsHashtable]
                [-Depth <Int32>]
                [-NoEnumerate]
                [<CommonParameters>]

Description

O ConvertFrom-Json cmdlet converte uma cadeia de caracteres formatada em JSON (JavaScript Object Notation) em um objeto PSObject ou Hashtable personalizado que tem uma propriedade para cada campo na cadeia de caracteres JSON. JSON é comumente usado por sites para fornecer uma representação textual de objetos. O cmdlet adiciona as propriedades ao novo objeto à medida que processa cada linha da cadeia de caracteres JSON.

O padrão JSON permite nomes de chaves duplicados, que são proibidos nos tipos PSObject e Hashtable . Por exemplo, se a cadeia de caracteres JSON contiver chaves duplicadas, somente a última chave será usada por esse cmdlet. Veja outros exemplos abaixo.

Para gerar uma cadeia de caracteres JSON a partir de qualquer objeto, use o ConvertTo-Json cmdlet.

Este cmdlet foi introduzido no PowerShell 3.0.

Nota

A partir do PowerShell 6, o cmdlet oferece suporte a JSON com comentários. Os comentários JSON começam com duas barras (//) caracteres. Os comentários JSON não são capturados na saída de objetos pelo cmdlet. Antes do PowerShell 6, ConvertFrom-Json retornava um erro quando encontrava um comentário JSON.

Exemplos

Exemplo 1: Converter um objeto DateTime em um objeto JSON

Este comando usa os ConvertTo-Json cmdlets e ConvertFrom-Json para converter um objeto DateTime do Get-Date cmdlet em um objeto JSON e, em seguida, em um PSCustomObject.

Get-Date | Select-Object -Property * | ConvertTo-Json | ConvertFrom-Json

DisplayHint : 2
DateTime    : Friday, January 13, 2012 8:06:31 PM
Date        : 1/13/2012 8:00:00 AM
Day         : 13
DayOfWeek   : 5
DayOfYear   : 13
Hour        : 20
Kind        : 2
Millisecond : 400
Minute      : 6
Month       : 1
Second      : 31
Ticks       : 634620819914009002
TimeOfDay   : @{Ticks=723914009002; Days=0; Hours=20; Milliseconds=400; Minutes=6; Seconds=31; TotalDays=0.83786343634490734; TotalHours=20.108722472277776; TotalMilliseconds=72391400.900200009; TotalMinutes=1206.5233483366667;TotalSeconds=72391.4009002}
Year        : 2012

O exemplo usa o Select-Object cmdlet para obter todas as propriedades do objeto DateTime . Ele usa o ConvertTo-Json cmdlet para converter o objeto DateTime em uma cadeia de caracteres formatada como um objeto JSON e o ConvertFrom-Json cmdlet para converter a cadeia de caracteres formatada em JSON em um objeto PSCustomObject .

Exemplo 2: Obter cadeias de caracteres JSON de um serviço Web e convertê-las em objetos do PowerShell

Este comando usa o Invoke-WebRequest cmdlet para obter cadeias de caracteres JSON de um serviço Web e, em seguida, usa o ConvertFrom-Json cmdlet para converter conteúdo JSON em objetos que podem ser gerenciados no PowerShell.

# Ensures that Invoke-WebRequest uses TLS 1.2
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
$j = Invoke-WebRequest 'https://api.github.com/repos/PowerShell/PowerShell/issues' | ConvertFrom-Json

Você também pode usar o cmdlet, que converte automaticamente o Invoke-RestMethod conteúdo JSON em objetos.

Exemplo 3: Converter uma cadeia de caracteres JSON em um objeto personalizado

Este exemplo mostra como usar o ConvertFrom-Json cmdlet para converter um arquivo JSON em um objeto personalizado do PowerShell.

Get-Content -Raw JsonFile.JSON | ConvertFrom-Json

O comando usa o cmdlet Get-Content para obter as cadeias de caracteres em um arquivo JSON. O parâmetro Raw retorna o arquivo inteiro como um único objeto JSON. Em seguida, ele usa o operador de pipeline para enviar a cadeia de caracteres delimitada para o ConvertFrom-Json cmdlet, que a converte em um objeto personalizado.

Exemplo 4: converter uma cadeia JSON numa tabela hash

Este comando mostra um exemplo em que o -AsHashtable switch pode superar as limitações do comando.

'{ "key":"value1", "Key":"value2" }' | ConvertFrom-Json -AsHashtable

A cadeia de caracteres JSON contém dois pares de valores de chave com chaves que diferem apenas em invólucro. Sem o switch, o comando teria lançado um erro.

Exemplo 5: Ida e volta a uma matriz de elementos únicos

Este comando mostra um exemplo em que o -NoEnumerate switch é usado para fazer uma viagem de ida e volta a uma matriz JSON de um único elemento.

Write-Output "With -NoEnumerate: $('[1]' | ConvertFrom-Json -NoEnumerate | ConvertTo-Json -Compress)"
Write-Output "Without -NoEnumerate: $('[1]' | ConvertFrom-Json | ConvertTo-Json -Compress)"

With -NoEnumerate: [1]
Without -NoEnumerate: 1

A cadeia de caracteres JSON contém uma matriz com um único elemento. Sem o switch, converter o JSON em um PSObject e, em seguida, convertê-lo novamente com o ConvertTo-Json comando resulta em um único inteiro.

Parâmetros

-AsHashtable

Converte o JSON num objeto de tabela hash. Essa opção foi introduzida no PowerShell 6.0. A partir do PowerShell 7.3, o objeto é um OrderedHashtable e preserva a ordem das chaves do JSON. Em versões anteriores, o objeto é um Hashtable.

Há vários cenários em que ele pode superar algumas limitações do ConvertFrom-Json cmdlet.

  • Sem essa opção, quando duas ou mais chaves em um objeto JSON são idênticas sem distinção entre maiúsculas e minúsculas, elas são tratadas como chaves idênticas. Nesse caso, apenas a última dessas chaves idênticas sem distinção entre maiúsculas e minúsculas é incluída no objeto convertido.
  • Sem essa opção, o cmdlet lança um erro sempre que o JSON contém uma chave que é uma cadeia de caracteres vazia. PSCustomObject não pode ter nomes de propriedade que são cadeias de caracteres vazias. Por exemplo, isso pode ocorrer em project.lock.json arquivos.
  • As tabelas hash podem ser processadas mais rapidamente para determinadas estruturas de dados.
Tipo:SwitchParameter
Position:Named
Default value:False
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Depth

Obtém ou define a profundidade máxima que a entrada JSON pode ter. O padrão é 1024.

Esse parâmetro foi introduzido no PowerShell 6.2.

Tipo:Int32
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-InputObject

Especifica as cadeias de caracteres JSON a serem convertidas em objetos JSON. Insira uma variável que contenha a cadeia de caracteres ou digite um comando ou expressão que obtenha a cadeia de caracteres. Você também pode canalizar uma cadeia de caracteres para ConvertFrom-Json.

O parâmetro InputObject é necessário, mas seu valor pode ser uma cadeia de caracteres vazia. Quando o objeto de entrada é uma cadeia de caracteres vazia, ConvertFrom-Json não gera nenhuma saída. O valor InputObject não pode ser $null.

Tipo:String
Position:0
Default value:None
Necessário:True
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-NoEnumerate

Especifica que a saída não é enumerada.

A definição desse parâmetro faz com que as matrizes sejam enviadas como um único objeto, em vez de enviar cada elemento separadamente. Isso garante que o JSON possa ser rodado via ConvertTo-Json.

Tipo:SwitchParameter
Position:Named
Default value:False
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

Entradas

String

Você pode canalizar uma cadeia de caracteres JSON para ConvertFrom-Json.

Saídas

PSCustomObject

OrderedHashtable

Notas

Este cmdlet é implementado usando Newtonsoft Json.NET.

A partir do PowerShell 6, ConvertTo-Json tenta converter cadeias de caracteres formatadas como carimbos de data/hora em valores DateTime . O valor convertido é uma [datetime] instância com uma Kind propriedade definida da seguinte forma:

  • Unspecified, se não houver informações de fuso horário na cadeia de caracteres de entrada.
  • Utc, se as informações de fuso horário forem à direita Z.
  • Local, se a informação de fuso horário for dada como um deslocamento UTC à direita como +02:00. O deslocamento é convertido corretamente para o fuso horário configurado do chamador. A formatação de saída padrão não indica o deslocamento de fuso horário original.

O tipo PSObject mantém a ordem das propriedades conforme apresentado na cadeia de caracteres JSON. A partir do PowerShell 7.3, o parâmetro AsHashtable cria um OrderedHashtable. Os pares chave-valor são adicionados na ordem apresentada na cadeia de caracteres JSON. O OrderedHashtable preserva essa ordem.