Compartilhar via

ConvertFrom-Json

Módulo:
Microsoft.PowerShell.Utility Module

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

Sintaxe

Default (Padrão) 

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

Description

O cmdlet ConvertFrom-Json converte uma cadeia de caracteres no formato JSON (JavaScript Object Notation) em um PSObject personalizado ou em um objeto Hashtable que tem uma propriedade para cada campo na cadeia de caracteres JSON. O JSON é comumente usado 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 cmdlet ConvertTo-Json.

Esse cmdlet foi introduzido no PowerShell 3.0.

Observação

No Windows PowerShell 5.1, ConvertFrom-Json retornou um erro quando encontrou um comentário JSON. No PowerShell 6 e superior, o cmdlet dá suporte a JSON com comentários. Os comentários JSON não são capturados na saída de objetos pelo cmdlet. Para obter mais informações, consulte a seção Comentários JSON do artigo about_Comments.

Exemplos

Exemplo 1: Converter um objeto DateTime em um objeto JSON

Esse comando usa os cmdlets ConvertTo-Json e ConvertFrom-Json para converter um objeto DateTime do cmdlet Get-Date 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 cmdlet Select-Object para obter todas as propriedades do objeto DateTime. Ele usa o cmdlet ConvertTo-Json para converter o objeto DateTime em uma cadeia de caracteres formatada como um objeto JSON e o cmdlet ConvertFrom-Json 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 cmdlet Invoke-WebRequest para obter cadeias de caracteres JSON de um serviço Web e usa o cmdlet ConvertFrom-Json 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 Invoke-RestMethod, que converte automaticamente o conteúdo JSON em objetos.

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

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

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

O comando usa Get-Content cmdlet para obter as cadeias de caracteres em um arquivo JSON. O parâmetro Raw retorna todo o arquivo como um único objeto JSON. Em seguida, ele usa o operador de pipeline para enviar a cadeia de caracteres delimitada para o cmdlet ConvertFrom-Json, 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 a opção -AsHashtable pode superar as limitações do comando.

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

A cadeia de caracteres JSON contém dois pares chave-valor, com chaves que diferem apenas no uso de maiúsculas e minúsculas. Sem a opção, o comando teria gerado um erro.

Exemplo 5: viagem de ida e volta em uma matriz de um único elemento

Este comando mostra um exemplo em que o comutador -NoEnumerate é usado para realizar um ciclo completo em 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 cadeia de caracteres JSON contém uma matriz com um único elemento. Sem o interruptor, converter o JSON em um PSObject e convertê-lo novamente com o comando ConvertTo-Json 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 é um Hashtable.

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

  • Sem essa opção, quando duas ou mais chaves em um objeto JSON são idênticas sem diferenciação de maiúsculas de minúsculas, elas são tratadas como chaves idênticas. Nesse caso, somente a última dessas chaves idênticas sem distinção entre maiúsculas e minúsculas é incluída no objeto transformado.
  • Sem essa opção, o cmdlet gerará um erro sempre que o JSON contiver uma chave que seja 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 arquivos project.lock.json.
  • As tabelas de hash podem ser processadas mais rapidamente para determinadas estruturas de dados.

Propriedades do parâmetro

Tipo:SwitchParameter
Valor padrão:False
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-DateKind

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

  • Default
  • Local
  • Utc
  • Offset
  • String

Para obter informações sobre como esses valores afetam a conversão, consulte os detalhes no NOTES.

Esse parâmetro foi introduzido no PowerShell 7.5.

Propriedades do parâmetro

Tipo:Microsoft.PowerShell.Commands.JsonDateKind
Valor padrão:Default
Valores aceitos:Default, Local, Utc, Offset, String
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-Depth

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

Esse parâmetro foi introduzido no PowerShell 6.2.

Propriedades do parâmetro

Tipo:Int32
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes: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 obtém a cadeia de caracteres. Você também pode redirecionar 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 do InputObject não pode ser $null.

Propriedades do parâmetro

Tipo:String
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:0
Obrigatório:True
Valor do pipeline:True
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-NoEnumerate

Especifica que a saída não está 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 fazer uma viagem de ida e volta por meio de ConvertTo-Json.

Propriedades do parâmetro

Tipo:SwitchParameter
Valor padrão:False
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

CommonParameters

Este cmdlet suporta os parâmetros comuns: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Para obter mais informações, consulte about_CommonParameters.

Entradas

String

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

Saídas

PSCustomObject

OrderedHashtable

Observações

Esse 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 PowerShell 7.5 adicionou o parâmetro DateKind, que permite controlar como a string de timestamp é convertida. O parâmetro aceita os seguintes valores:

  • Default - converte o timestamp em uma instância de [datetime] 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 tempo não especificado.
    • Se as informações de fuso horário forem Z à direita, o serializador de Json.NET converterá o carimbo de data/hora em um valor UTC.
    • Se o timestamp incluir um deslocamento UTC como +02:00, o deslocamento será ajustado para o fuso horário configurado pelo 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 instância [datetime] no horário local. Se o carimbo de data/hora incluir uma diferença UTC, a diferença será convertida para o fuso horário definido pelo 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 instância de [datetime] em tempo UTC.
  • Offset – converte o carimbo de data/hora em uma instância [DateTimeOffset], com a diferença de fuso horário da cadeia de caracteres 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 instância [string]. Isso garante que qualquer lógica de análise personalizada possa ser aplicada ao valor bruto da cadeia de caracteres.

O tipo PSObject mantém a ordem das propriedades, conforme apresentado na string 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.