Compartilhar via

ConvertFrom-Json

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

Converte uma cadeia de caracteres formatada em JSON em um objeto personalizado ou em uma tabela de hash.

Sintaxe

ConvertFrom-Json
                [-InputObject] <String>
                [-AsHashtable]
                [-DateKind <JsonDateKind>]
                [-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 utilizado comumente por sites da web 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 chave 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 de qualquer objeto, use o ConvertTo-Json cmdlet.

Esse cmdlet foi introduzido no PowerShell 3.0.

Observação

A partir do PowerShell 6, o cmdlet dá suporte a JSON com comentários. Os comentários JSON começam com dois caracteres de barras (//). 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

Esse 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    : Monday, January 29, 2024 3:10:26 PM
Date        : 1/29/2024 12:00:00 AM
Day         : 29
DayOfWeek   : 1
DayOfYear   : 29
Hour        : 15
Kind        : 2
Millisecond : 931
Microsecond : 47
Nanosecond  : 600
Minute      : 10
Month       : 1
Second      : 26
Ticks       : 638421378269310476
TimeOfDay   : @{Ticks=546269310476; Days=0; Hours=15; Milliseconds=931; Microseconds=47;
              Nanoseconds=600; Minutes=10; Seconds=26; TotalDays=0.632256146384259;
              TotalHours=15.1741475132222; TotalMilliseconds=54626931.0476;
              TotalMicroseconds=54626931047.6; TotalNanoseconds=54626931047600;
              TotalMinutes=910.448850793333; TotalSeconds=54626.9310476}
Year        : 2024

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

Esse comando usa o Invoke-WebRequest cmdlet para obter cadeias de caracteres JSON de um serviço Web e, em seguida, usa o cmdlet para converter conteúdo ConvertFrom-Json 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 de caracteres JSON em uma tabela de 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-chave com chaves que diferem apenas em maiúsculas e minúsculas. Sem o switch, o comando teria gerado um erro.

Exemplo 5: Viagem de ida e volta de uma única matriz de elemento

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

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 string JSON contém uma matriz com um único elemento. Sem a opção, 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 em um objeto de tabela de hash. Essa opção foi introduzida no PowerShell 6.0. A partir do PowerShell 7.3, o objeto é um OrderedHashtable e preserva a ordenação das chaves do JSON. Nas versões anteriores, o objeto é uma tabela de hash.

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 que não diferenciam maiúsculas de minúsculas é incluída no objeto convertido.
  • Sem essa opção, o cmdlet gera 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 sejam cadeias de caracteres vazias. Por exemplo, isso pode ocorrer em project.lock.json arquivos.
  • As tabelas de hash podem ser processadas mais rapidamente para determinadas estruturas de dados.
Tipo:SwitchParameter
Cargo:Named
Valor padrão:False
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-DateKind

Especifica o método usado ao analisar valores de data e hora na cadeia de caracteres JSON. Os valores aceitáveis para esse parâmetro são:

  • Default
  • Local
  • Utc
  • Offset
  • String

Para obter informações sobre como esses valores afetam a conversão, consulte os detalhes nas OBSERVAÇÕES.

Esse parâmetro foi introduzido no PowerShell 7.5.

Tipo:Microsoft.PowerShell.Commands.JsonDateKind
Valores aceitos:Default, Local, Utc, Offset, String
Cargo:Named
Valor padrão:Default
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-InputObject

Especifica as cadeias de caracteres JSON a converter em objetos JSON. Insira uma variável que contenha a cadeia de caracteres ou digite um comando ou expressão que obtenha essa cadeia. Você também pode canalizar uma string 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
Cargo:0
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga:False

-NoEnumerate

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

Definir esse 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 tripulado via ConvertTo-Json.

Tipo:SwitchParameter
Cargo:Named
Valor padrão:False
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

Entradas

String

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

Saídas

PSCustomObject

OrderedHashtable

Observações

Esse cmdlet é implementado usando o 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 PowerShell 7.5 adicionou o parâmetro DateKind, que permite controlar como a cadeia de caracteres de carimbo de data/hora é convertida. O parâmetro aceita os seguintes valores:

  • Default - Converte o carimbo de data/hora em uma [datetime] instância de acordo com as seguintes regras:
    • Se não houver informações de fuso horário na cadeia de caracteres de entrada, o serializador Json.NET converterá o valor como um valor de hora não especificado.
    • Se as informações de fuso horário forem um trailing Z, o serializador Json.NET converterá o carimbo de data/hora em um valor UTC .
    • Se o carimbo de data/hora incluir um deslocamento UTC como +02:00, o deslocamento será convertido 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.
  • Local - Converte o carimbo de data/hora em uma [datetime] instância na hora local . Se o carimbo de data/hora incluir um deslocamento UTC, o deslocamento será convertido 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.
  • Utc - Converte o valor em uma [datetime] instância no horário UTC.
  • Offset - Converte o carimbo de data/hora em uma [DateTimeOffset] instância com o deslocamento de fuso horário da string original preservada nessa instância. Se a cadeia de caracteres bruta não contiver um deslocamento de fuso horário, o valor DateTimeOffset será especificado no fuso horário local.
  • String - Preserva o valor da [string] instância. Isso garante que qualquer lógica de análise personalizada possa ser aplicada ao valor da cadeia de caracteres bruta.

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 de chave-valor são adicionados na ordem apresentada na cadeia de caracteres JSON. O OrderedHashtable preserva essa ordem.