Sdílet prostřednictvím

ConvertFrom-Json

  • Reference
Modul:
Microsoft.PowerShell.Utility

Převede řetězec ve formátu JSON na vlastní objekt nebo tabulku hash.

Syntaxe

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

Description

Cmdlet ConvertFrom-Json převede řetězec ve formátu JSON (JavaScript Object Notation) na vlastní objekt PSObject nebo objekt Hashtable, který má vlastnost pro každé pole v řetězci JSON. JSON se běžně používá na webových webech k poskytnutí textové reprezentace objektů. Cmdlet přidá vlastnosti k novému objektu při zpracovávání každého řádku řetězce JSON.

Standard JSON umožňuje duplicitní jména klíčů, které jsou zakázány v PSObject a Hashtable typy. Pokud například řetězec JSON obsahuje duplicitní klíče, použije tato rutina pouze poslední klíč. Podívejte se na další příklady níže.

K vygenerování řetězce JSON z libovolného objektu použijte rutinu ConvertTo-Json.

Tato rutina byla představena v PowerShellu 3.0.

Poznámka

Ve Windows PowerShellu 5.1 ConvertFrom-Json vrátil chybu, když došlo k komentáři JSON. V PowerShellu verze 6 a vyšší, příkaz podporuje JSON s komentáři. Komentáře JSON nejsou zachyceny ve výstupu objektů příkazem cmdlet. Další informace najdete v části komentáře JSON článku about_Comments.

Příklady

Příklad 1: Převod objektu DateTime na objekt JSON

Tento příkaz používá rutiny ConvertTo-Json a ConvertFrom-Json k převodu objektu DateTime z rutiny Get-Date na objekt JSON a potom na 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

Příklad používá rutinu Select-Object k získání všech vlastností objektu DateTime. Používá rutinu ConvertTo-Json k převodu objektu DateTime na řetězec formátovaný jako objekt JSON a rutina ConvertFrom-Json k převodu řetězce ve formátu JSON na objekt PSCustomObject.

Příklad 2: Získání řetězců JSON z webové služby a jejich převod na objekty PowerShellu

Tento příkaz pomocí rutiny Invoke-WebRequest získá řetězce JSON z webové služby a pak pomocí rutiny ConvertFrom-Json převede obsah JSON na objekty, které je možné spravovat v PowerShellu.

# 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

Můžete také použít rutinu Invoke-RestMethod, která automaticky převede obsah JSON na objekty.

Příklad 3: Převod řetězce JSON na vlastní objekt

Tento příklad ukazuje, jak pomocí rutiny ConvertFrom-Json převést soubor JSON na vlastní objekt PowerShellu.

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

Příkaz používá rutinu Get-Content k získání řetězců v souboru JSON. Parametr Raw vrátí celý soubor jako jeden objekt JSON. Poté pomocí operátoru roury odešle řetězec s oddělovači do rutiny ConvertFrom-Json, která ho převede na uživatelský objekt.

Příklad 4: Převod řetězce JSON na tabulku hash

Tento příkaz ukazuje příklad, ve kterém přepínač -AsHashtable může překonat omezení příkazu.

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

Řetězec JSON obsahuje dva páry klíč-hodnota s klíči, které se liší pouze velikostí písmen. Bez přepínače by příkaz vyvolil chybu.

Příklad 5: Zaokrouhlování pole s jedním prvkem

Tento příkaz ukazuje příklad, ve kterém se přepínač -NoEnumerate používá k zaokrouhlování pole JSON s jedním prvkem.

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

Řetězec JSON obsahuje pole s jedním prvkem. Bez přepínače převedete JSON na objekt PSObject a následným převodem zpět pomocí příkazu ConvertTo-Json vznikne jedno celé číslo.

Parametry

-AsHashtable

Převede JSON na objekt tabulky hash. Tento přepínač byl představen v PowerShellu 6.0. Počínaje PowerShellem 7.3 je objekt OrderedHashtable a zachovává pořadí klíčů z JSON. V předchozích verzích je objekt hashtable.

Existuje několik scénářů, kdy může překonat některá omezení ConvertFrom-Json cmdletu.

  • Bez tohoto přepínače jsou v objektu JSON dva nebo více klíčů nerozlišující velká a malá písmena považovány za identické klíče. V takovém případě je do převedeného objektu zahrnut pouze poslední z těchto klíčů, které se nerozlišují podle velikosti písmen.
  • Bez tohoto přepínače rutina vyvolá chybu pokaždé, když JSON obsahuje klíč, který je prázdný řetězec. PSCustomObject nemůže mít názvy vlastností, které jsou prázdné řetězce. Může k tomu dojít například v project.lock.json souborech.
  • Tabulky hash je možné zpracovat rychleji pro určité datové struktury.
Typ:SwitchParameter
Position:Named
Default value:False
Vyžadováno:False
Přijmout vstup kanálu:False
Přijmout zástupné znaky:False

-DateKind

Určuje metodu použitou při analýze hodnot data a času v řetězci JSON. Přijatelné hodnoty pro tento parametr jsou:

  • Default
  • Local
  • Utc
  • Offset
  • String

Informace o tom, jak tyto hodnoty ovlivňují převod, naleznete v podrobnostech v NOTES.

Tento parametr byl představen v PowerShellu 7.5.

Typ:Microsoft.PowerShell.Commands.JsonDateKind
Přípustné hodnoty:Default, Local, Utc, Offset, String
Position:Named
Default value:Default
Vyžadováno:False
Přijmout vstup kanálu:False
Přijmout zástupné znaky:False

-Depth

Získá nebo nastaví maximální hloubku, kterou vstup JSON může mít. Výchozí hodnota je 1024.

Tento parametr byl představen v PowerShellu 6.2.

Typ:Int32
Position:Named
Default value:None
Vyžadováno:False
Přijmout vstup kanálu:False
Přijmout zástupné znaky:False

-InputObject

Určuje řetězce JSON, které se mají převést na objekty JSON. Zadejte proměnnou, která obsahuje řetězec, nebo zadejte příkaz nebo výraz, který řetězec získává. Řetězec můžete také přesměrovat do ConvertFrom-Json.

Je vyžadován parametr InputObject, ale jeho hodnota může být prázdný řetězec. Pokud je vstupním objektem prázdný řetězec, ConvertFrom-Json negeneruje žádný výstup. Hodnota InputObject nemůže být $null.

Typ:String
Position:0
Default value:None
Vyžadováno:True
Přijmout vstup kanálu:True
Přijmout zástupné znaky:False

-NoEnumerate

Určuje, že výstup není uveden.

Nastavení tohoto parametru způsobí, že pole budou odeslána jako jeden objekt místo odesílání každého prvku samostatně. To zaručuje, že JSON lze obousměrně přenášet přes ConvertTo-Json.

Typ:SwitchParameter
Position:Named
Default value:False
Vyžadováno:False
Přijmout vstup kanálu:False
Přijmout zástupné znaky:False

Vstupy

String

Řetězec JSON můžete převést na ConvertFrom-Json.

Výstupy

PSCustomObject

OrderedHashtable

Poznámky

Tato rutina se implementuje pomocí Newtonsoft Json.NET.

Počínaje verzí PowerShell 6 se ConvertTo-Json pokusí převést řetězce formátované jako časové značky na hodnoty DateTime.

PowerShell 7.5 přidal parametr DateKind, který umožňuje řídit způsob převodu časových razítek. Parametr přijímá následující hodnoty:

  • Default – převede časové razítko na instanci [datetime] podle následujících pravidel:
    • Pokud vstupní řetězec neobsahuje žádné informace o časovém pásmu, Json.NET serializátor převede hodnotu jako nezadanou časovou hodnotu.
    • Pokud jsou informace o časovém pásmu koncovou Z, serializátor Json.NET převede časové razítko na hodnotu UTC.
    • Pokud časové razítko obsahuje posun UTC, jako je +02:00, posun se převede na nakonfigurované časové pásmo volajícího. Výchozí formátování výstupu neznačí původní posun časového pásma.
  • Local – převede časové razítko na instanci [datetime] v místním čase . Pokud časové razítko obsahuje posun UTC, tento posun se přepočítá na časové pásmo nastavené volajícím. Výchozí formátování výstupu neznačí původní posun časového pásma.
  • Utc – převede hodnotu na instanci [datetime] v čase UTC.
  • Offset – převede časové razítko na instanci [DateTimeOffset] tak, že je v ní zachován posun časového pásma původního řetězce. Pokud nezpracovaný řetězec neobsahuje posun časového pásma, hodnota DateTimeOffset bude určena v místním časovém pásmu.
  • String – zachová hodnotu instance [string]. Tím se zajistí, že na nezpracovanou řetězcovou hodnotu se dá použít jakákoli vlastní logika analýzy.

Typ PSObject udržuje pořadí vlastností, jak je znázorněno v řetězci JSON. Počínaje verzí PowerShell 7.3, parametr AsHashtable vytváří OrderedHashtable. Páry klíč-hodnota se přidají v pořadí uvedeném v řetězci JSON. OrderedHashtable zachová toto pořadí.