Udostępnij za pośrednictwem

ConvertFrom-Json

  • Odwołanie
Moduł:
Microsoft.PowerShell.Utility

Konwertuje ciąg w formacie JSON na obiekt niestandardowy lub tabelę skrótów.

Składnia

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

Opis

Cmdlet ConvertFrom-Json konwertuje ciąg w formacie JSON na niestandardowy obiekt PSObject lub obiekt Hashtable, który ma właściwość dla każdego pola w ciągu JSON. Kod JSON jest często używany przez witryny sieci Web w celu zapewnienia tekstowej reprezentacji obiektów. Polecenie cmdlet dodaje właściwości do nowego obiektu podczas przetwarzania każdego wiersza ciągu JSON.

Standard JSON zezwala na zduplikowane nazwy kluczy, które są zabronione w typach PSObject i Hashtable. Jeśli na przykład ciąg JSON zawiera zduplikowane klucze, tylko ostatni klucz jest używany przez to polecenie cmdlet. Zobacz inne przykłady poniżej.

Aby wygenerować ciąg JSON z dowolnego obiektu, użyj polecenia cmdlet ConvertTo-Json.

Ten cmdlet został wprowadzony w programie PowerShell 3.0.

Notatka

W programie Windows PowerShell 5.1 ConvertFrom-Json zwrócił błąd, gdy napotkał komentarz JSON. W PowerShell 6 i wyższych wersjach, polecenie cmdlet obsługuje JSON z komentarzami. Komentarze JSON nie są przechwytywane w danych wyjściowych obiektów przez polecenie cmdlet . Aby uzyskać więcej informacji, zobacz sekcję komentarzy JSON artykułu about_Comments.

Przykłady

Przykład 1. Konwertowanie obiektu DateTime na obiekt JSON

To polecenie używa poleceń cmdlet ConvertTo-Json i ConvertFrom-Json do konwertowania obiektu DateTime z polecenia cmdlet Get-Date do obiektu JSON, a następnie do obiektu 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

W przykładzie użyto polecenia cmdlet Select-Object, aby pobrać wszystkie właściwości obiektu DateTime. Używa on polecenia cmdlet ConvertTo-Json do konwertowania obiektu DateTime na ciąg sformatowany jako obiekt JSON i polecenie cmdlet ConvertFrom-Json w celu przekonwertowania ciągu w formacie JSON na obiekt PSCustomObject.

Przykład 2. Pobieranie ciągów JSON z usługi internetowej i konwertowanie ich na obiekty programu PowerShell

To polecenie używa polecenia cmdlet Invoke-WebRequest do pobierania ciągów JSON z usługi internetowej, a następnie używa polecenia cmdlet ConvertFrom-Json do konwertowania zawartości JSON na obiekty, którymi można zarządzać w programie 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

Możesz również użyć polecenia cmdlet Invoke-RestMethod, które automatycznie konwertuje zawartość JSON na obiekty.

Przykład 3. Konwertowanie ciągu JSON na obiekt niestandardowy

W tym przykładzie pokazano, jak za pomocą polecenia cmdlet ConvertFrom-Json przekonwertować plik JSON na obiekt niestandardowy programu PowerShell.

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

Polecenie używa Get-Content cmdlet, aby pobrać ciągi w pliku JSON. Parametr Raw zwraca cały plik jako pojedynczy obiekt JSON. Następnie używa operatora potoku, aby wysłać rozdzielany ciąg do polecenia cmdlet ConvertFrom-Json, które konwertuje go na obiekt niestandardowy.

Przykład 4. Konwertowanie ciągu JSON na tabelę skrótów

To polecenie pokazuje przykład, w którym przełącznik -AsHashtable może przezwyciężyć ograniczenia polecenia.

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

Ciąg JSON zawiera dwie pary wartości klucza z kluczami, które różnią się tylko wielkością liter. Bez przełącznika polecenie spowodowałoby wystąpienie błędu.

Przykład 5. Zaokrąglanie pojedynczej tablicy elementów

To polecenie pokazuje przykład, w którym przełącznik -NoEnumerate jest używany do przetwarzania tablicy JSON z jednym elementem w obie strony.

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

Ciąg JSON zawiera tablicę z jednym elementem. Bez przełącznika konwertowanie kodu JSON na obiekt PSObject, a następnie konwertowanie go z powrotem przy użyciu polecenia ConvertTo-Json powoduje utworzenie pojedynczej liczby całkowitej.

Parametry

-AsHashtable

Konwertuje kod JSON na obiekt tabeli skrótów. Ten przełącznik został wprowadzony w programie PowerShell 6.0. Począwszy od PowerShell 7.3, obiekt jest OrderedHashtable i zachowuje kolejność kluczy z formatu JSON. W poprzednich wersjach obiekt jest hashtable.

Istnieje kilka scenariuszy, w których można przezwyciężyć pewne ograniczenia polecenia cmdlet ConvertFrom-Json.

  • Bez tego przełącznika, gdy co najmniej dwa klucze w obiekcie JSON są bez uwzględniania wielkości liter, są traktowane jako identyczne klucze. W takim przypadku w przekonwertowanym obiekcie znajduje się tylko ostatni z tych kluczy, które są identyczne bez względu na wielkość liter.
  • Bez tego przełącznika polecenie cmdlet zgłasza błąd za każdym razem, gdy kod JSON zawiera klucz, który jest pustym ciągiem. PSCustomObject nie może mieć nazw właściwości, które są pustymi ciągami. Na przykład może to wystąpić w plikach project.lock.json.
  • Tabele skrótów mogą być przetwarzane szybciej dla niektórych struktur danych.
Typ:SwitchParameter
Position:Named
Domyślna wartość:False
Wymagane:False
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych:False

-DateKind

Określa metodę używaną podczas parsowania daty i czasu w ciągu JSON. Dopuszczalne wartości tego parametru to:

  • Default
  • Local
  • Utc
  • Offset
  • String

Aby uzyskać informacje na temat wpływu tych wartości na konwersję, zobacz szczegóły w NOTES.

Ten parametr został wprowadzony w programie PowerShell 7.5.

Typ:Microsoft.PowerShell.Commands.JsonDateKind
Dopuszczalne wartości:Default, Local, Utc, Offset, String
Position:Named
Domyślna wartość:Default
Wymagane:False
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych:False

-Depth

Pobiera lub ustawia maksymalną dozwoloną głębokość dla danych wejściowych JSON. Wartość domyślna to 1024.

Ten parametr został wprowadzony w programie PowerShell 6.2.

Typ:Int32
Position:Named
Domyślna wartość:None
Wymagane:False
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych:False

-InputObject

Określa ciągi JSON do konwersji na obiekty JSON. Wprowadź zmienną zawierającą ciąg lub wpisz polecenie lub wyrażenie, które pobiera ciąg. Możesz również przekazać ciąg do ConvertFrom-Json.

Parametr InputObject jest wymagany, ale jego wartość może być pustym ciągiem. Gdy obiekt wejściowy jest pustym ciągiem, ConvertFrom-Json nie generuje żadnych danych wyjściowych. Wartość obiektu InputObject nie może być $null.

Typ:String
Position:0
Domyślna wartość:None
Wymagane:True
Akceptowanie danych wejściowych potoku:True
Akceptowanie symboli wieloznacznych:False

-NoEnumerate

Określa, że dane wyjściowe nie są wyliczane.

Ustawienie tego parametru powoduje wysyłanie tablic jako pojedynczego obiektu zamiast wysyłania każdego elementu oddzielnie. Gwarantuje to, że kod JSON może być zaokrąglony za pośrednictwem ConvertTo-Json.

Typ:SwitchParameter
Position:Named
Domyślna wartość:False
Wymagane:False
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych:False

Dane wejściowe

String

Możesz przekazać ciąg JSON do ConvertFrom-Json.

Dane wyjściowe

PSCustomObject

OrderedHashtable

Uwagi

To polecenie cmdlet jest implementowane przy użyciu Newtonsoft Json.NET.

Począwszy od programu PowerShell 6, ConvertTo-Json próbuje przekonwertować ciągi sformatowane jako znaczniki czasu na wartości DateTime.

Program PowerShell 7.5 dodał parametr DateKind, który pozwala kontrolować sposób konwertowania ciągu znacznika czasu. Parametr akceptuje następujące wartości:

  • Default — konwertuje znacznik czasu na wystąpienie [datetime] zgodnie z następującymi regułami:
    • Jeśli w ciągu wejściowym nie ma informacji o strefie czasowej, Json.NET serializator konwertuje wartość jako nieokreśloną wartość czasu.
    • Jeśli informacje o strefie czasowej występują na końcu jako Z, serializator Json.NET konwertuje znacznik czasu na wartość UTC.
    • Jeśli znacznik czasu zawiera przesunięcie UTC, takie jak +02:00, przesunięcie jest konwertowane na skonfigurowaną strefę czasową osoby wywołującej. Domyślne formatowanie danych wyjściowych nie wskazuje oryginalnego przesunięcia strefy czasowej.
  • Local — konwertuje znacznik czasu na wystąpienie [datetime] w lokalnym czasie. Jeśli znacznik czasu zawiera przesunięcie UTC, przesunięcie jest konwertowane na skonfigurowaną strefę czasową osoby wywołującej. Domyślne formatowanie danych wyjściowych nie wskazuje oryginalnego przesunięcia strefy czasowej.
  • Utc — konwertuje wartość na wystąpienie [datetime] w czasie UTC.
  • Offset — przekształca znacznik czasu na instancję [DateTimeOffset], zachowując przesunięcie strefy czasowej oryginalnego ciągu w tej instancji. Jeśli nieprzetworzony ciąg nie zawiera przesunięcia strefy czasowej, wartość DateTimeOffset zostanie określona w lokalnej strefie czasowej.
  • String przechowuje wartość wystąpienia [string]. Dzięki temu można zastosować dowolną niestandardową logikę analizowania do nieprzetworzonej wartości ciągu.

Typ PSObject zachowuje kolejność właściwości, jak przedstawiono w ciągu JSON. Począwszy od wersji 7.3 programu PowerShell, parametr AsHashtable tworzy OrderedHashtable. Pary klucz-wartość są dodawane w kolejności przedstawionej w ciągu JSON. OrderedHashtable zachowuje kolejność.