ConvertTo-Json

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

Converte um objeto numa cadeia formatada em JSON.

Syntax

ConvertTo-Json
              [-InputObject] <Object>
              [-Depth <Int32>]
              [-Compress]
              [-EnumsAsStrings]
              [-AsArray]
              [-EscapeHandling <StringEscapeHandling>]
              [<CommonParameters>]

Description

O ConvertTo-Json cmdlet converte qualquer objeto .NET numa cadeia no formato JavaScript Object Notation (JSON). As propriedades são convertidas em nomes de campos, os valores dos campos são convertidos em valores de propriedade e os métodos são removidos.

Nota

A partir do PowerShell 7.2, as propriedades do Sistema de Tipos Expandidos dos objetos DateTime e String já não são serializadas e apenas o objeto simples é convertido em formato JSON

Em seguida, pode utilizar o ConvertFrom-Json cmdlet para converter uma cadeia formatada em JSON num objeto JSON, que é facilmente gerido no PowerShell.

Muitos sites utilizam JSON em vez de XML para serializar dados para comunicação entre servidores e aplicações baseadas na Web.

A partir do PowerShell 7.1, ConvertTo-Json emite um aviso se a profundidade do objeto de entrada exceder a profundidade especificada para o comando. Isto impede a perda de dados indesejada ao converter objetos.

Este cmdlet foi introduzido no Windows PowerShell 3.0.

Exemplos

Exemplo 1

(Get-UICulture).Calendar | ConvertTo-Json

{
  "MinSupportedDateTime": "0001-01-01T00:00:00",
  "MaxSupportedDateTime": "9999-12-31T23:59:59.9999999",
  "AlgorithmType": 1,
  "CalendarType": 1,
  "Eras": [
    1
  ],
  "TwoDigitYearMax": 2029,
  "IsReadOnly": true
}

Este comando utiliza o ConvertTo-Json cmdlet para converter um objeto GregorrianCalendar numa cadeia formatada em JSON.

Exemplo 2

Get-Date | ConvertTo-Json; Get-Date | ConvertTo-Json -AsArray

"2021-08-05T16:13:05.6394416-07:00"
[
  "2021-08-05T16:13:05.6421709-07:00"
]

Este exemplo mostra o resultado do ConvertTo-Json cmdlet com e sem o parâmetro de comutador AsArray . Pode ver que a segunda parte da saída está encapsulada em parênteses de matriz.

Exemplo 3

@{Account="User01";Domain="Domain01";Admin="True"} | ConvertTo-Json -Compress

{"Domain":"Domain01","Account":"User01","Admin":"True"}

Este comando mostra o efeito da utilização do parâmetro Comprimir de ConvertTo-Json. A compressão afeta apenas o aspeto da cadeia, não a sua validade.

Exemplo 4

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

{
  "DisplayHint": 2,
  "DateTime": "October 12, 2018 10:55:32 PM",
  "Date": "2018-10-12T00:00:00-05:00",
  "Day": 12,
  "DayOfWeek": 5,
  "DayOfYear": 285,
  "Hour": 22,
  "Kind": 2,
  "Millisecond": 639,
  "Minute": 55,
  "Month": 10,
  "Second": 32,
  "Ticks": 636749817326397744,
  "TimeOfDay": {
    "Ticks": 825326397744,
    "Days": 0,
    "Hours": 22,
    "Milliseconds": 639,
    "Minutes": 55,
    "Seconds": 32,
    "TotalDays": 0.95523888627777775,
    "TotalHours": 22.925733270666665,
    "TotalMilliseconds": 82532639.774400011,
    "TotalMinutes": 1375.54399624,
    "TotalSeconds": 82532.6397744
  },
  "Year": 2018
}

Este exemplo utiliza o ConvertTo-Json cmdlet para converter um objeto System.DateTime do Get-Date cmdlet para uma cadeia formatada em JSON. O comando utiliza o Select-Object cmdlet para obter todas (*) das propriedades do objeto DateTime . O resultado mostra a cadeia JSON que ConvertTo-Json devolveu.

Exemplo 5

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

DisplayHint : 2
DateTime    : October 12, 2018 10:55:52 PM
Date        : 2018-10-12 12:00:00 AM
Day         : 12
DayOfWeek   : 5
DayOfYear   : 285
Hour        : 22
Kind        : 2
Millisecond : 768
Minute      : 55
Month       : 10
Second      : 52
Ticks       : 636749817527683372
TimeOfDay   : @{Ticks=825527683372; Days=0; Hours=22; Milliseconds=768; Minutes=55; Seconds=52;
              TotalDays=0.95547185575463; TotalHours=22.9313245381111; TotalMilliseconds=82552768.3372;
              TotalMinutes=1375.87947228667; TotalSeconds=82552.7683372}
Year        : 2018

Este exemplo mostra como utilizar os ConvertTo-Json cmdlets e ConvertFrom-Json para converter um objeto numa cadeia JSON e num objeto JSON.

Parâmetros

-AsArray

Produz o objeto entre parênteses retos de matriz, mesmo que a entrada seja um único objeto.

Type:SwitchParameter
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-Compress

Omite o espaço em branco e a formatação com avanço na cadeia de saída.

Type:SwitchParameter
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-Depth

Especifica quantos níveis de objetos contidos estão incluídos na representação JSON. O valor pode ser qualquer número de 0 para 100. O valor predefinido é 2. ConvertTo-Json emite um aviso se o número de níveis num objeto de entrada exceder este número.

Type:Int32
Position:Named
Default value:2
Accept pipeline input:False
Accept wildcard characters:False

-EnumsAsStrings

Fornece uma opção de serialização alternativa que converte todas as enumerações na respetiva representação de cadeia.

Type:SwitchParameter
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-EscapeHandling

Controla a forma como determinados carateres são escapados na saída JSON resultante. Por predefinição, apenas os carateres de controlo (como newline) são escapados.

Os valores aceitáveis são:

  • Predefinição – apenas os carateres de controlo são escapados.
  • EscapeNonAscii – todos os carateres não ASCII e de controlo são escapados.
  • EscapeHtml – os carateres html (<, >, &, ', ") e de controlo são escapados.

Este parâmetro foi introduzido no PowerShell 6.2.

Type:Newtonsoft.Json.StringEscapeHandling
Position:Named
Default value:Default
Accept pipeline input:False
Accept wildcard characters:False

-InputObject

Especifica os objetos a converter em formato JSON. Introduza uma variável que contenha os objetos ou escreva um comando ou expressão que obtenha os objetos. Também pode encaminhar um objeto para ConvertTo-Json.

O parâmetro InputObject é necessário, mas o respetivo valor pode ser nulo ($null) ou uma cadeia vazia. Quando o objeto de entrada é $null, ConvertTo-Json devolve a representação JSON de null. Quando o objeto de entrada é uma cadeia vazia, ConvertTo-Json devolve a representação JSON de uma cadeia vazia.

Type:Object
Position:0
Default value:None
Accept pipeline input:True
Accept wildcard characters:False

Entradas

Object

Pode encaminhar qualquer objeto para este cmdlet.

Saídas

String

Este cmdlet devolve uma cadeia que representa o objeto de entrada convertido numa cadeia JSON.

Notas

O ConvertTo-Json cmdlet é implementado com newtonsoft Json.NET.