ConvertFrom-Json

Modul:
Microsoft.PowerShell.Utility Module

Konvertiert eine JSON-formatierte Zeichenfolge in ein benutzerdefiniertes Objekt oder eine Hashtabelle.

Syntax

Default (Standard) 

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

Beschreibung

Das ConvertFrom-Json Cmdlet konvertiert eine json-formatierte Zeichenfolge (JavaScript Object Notation) in ein benutzerdefiniertes PSObject - oder Hashtable-Objekt , das über eine Eigenschaft für jedes Feld in der JSON-Zeichenfolge verfügt. JSON wird häufig von Websites verwendet, um eine textbezogene Darstellung von Objekten bereitzustellen. Das Cmdlet fügt dem neuen Objekt die Eigenschaften hinzu, während jede Zeile der JSON-Zeichenfolge verarbeitet wird.

Der JSON-Standard ermöglicht doppelte Schlüsselnamen, die in PSObject - und Hashtable-Typen verboten sind. Wenn beispielsweise die JSON-Zeichenfolge doppelte Schlüssel enthält, wird nur der letzte Schlüssel von diesem Cmdlet verwendet. Weitere Beispiele finden Sie unten.

Verwenden Sie das ConvertTo-Json Cmdlet, um eine JSON-Zeichenfolge aus einem beliebigen Objekt zu generieren.

Dieses Cmdlet wurde in PowerShell 3.0 eingeführt.

Note

In Windows PowerShell 5.1 hat ConvertFrom-Json beim Auftreten eines JSON-Kommentars einen Fehler zurückgegeben. In PowerShell 6 und höher unterstützt das Cmdlet JSON mit Kommentaren. JSON-Kommentare werden nicht in der Vom Cmdlet ausgegebenen Objekte erfasst. Weitere Informationen finden Sie im Abschnitt "JSON-Kommentare " des artikels about_Comments .

Beispiele

Beispiel 1: Konvertieren eines DateTime-Objekts in ein JSON-Objekt

Dieser Befehl verwendet und ConvertTo-JsonConvertFrom-Json cmdlets, um ein DateTime-Objekt aus dem Get-Date Cmdlet in ein JSON-Objekt zu konvertieren und dann in ein 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

Im Beispiel wird das Select-Object Cmdlet verwendet, um alle Eigenschaften des DateTime-Objekts abzurufen. Es verwendet das ConvertTo-Json Cmdlet, um das DateTime-Objekt in eine Zeichenfolge zu konvertieren, die als JSON-Objekt formatiert ist, und das ConvertFrom-Json Cmdlet, um die JSON-formatierte Zeichenfolge in ein PSCustomObject-Objekt zu konvertieren.

Beispiel 2: Abrufen von JSON-Zeichenfolgen aus einem Webdienst und Konvertieren in PowerShell-Objekte

Dieser Befehl verwendet das Invoke-WebRequest Cmdlet, um JSON-Zeichenfolgen aus einem Webdienst abzurufen, und anschließend wird das ConvertFrom-Json Cmdlet zum Konvertieren von JSON-Inhalten in Objekte verwendet, die in PowerShell verwaltet werden können.

# 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

Sie können auch das Invoke-RestMethod Cmdlet verwenden, das JSON-Inhalte automatisch in Objekte konvertiert.

Beispiel 3: Konvertieren einer JSON-Zeichenfolge in ein benutzerdefiniertes Objekt

In diesem Beispiel wird gezeigt, wie Sie mithilfe des ConvertFrom-Json Cmdlets eine JSON-Datei in ein benutzerdefiniertes PowerShell-Objekt konvertieren.

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

Der Befehl verwendet Get-Content Cmdlet, um die Zeichenfolgen in einer JSON-Datei abzurufen. Der Raw-Parameter gibt die gesamte Datei als einzelnes JSON-Objekt zurück. Anschließend wird der Pipelineoperator verwendet, um die durch Trennzeichen getrennte Zeichenfolge an das ConvertFrom-Json Cmdlet zu senden, wodurch sie in ein benutzerdefiniertes Objekt konvertiert wird.

Beispiel 4: Konvertieren einer JSON-Zeichenfolge in eine Hashtabelle

Dieser Befehl zeigt ein Beispiel, in dem der -AsHashtable Schalter Einschränkungen des Befehls überwinden kann.

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

Die JSON-Zeichenfolge enthält zwei Schlüsselwertpaare mit Schlüsseln, die sich nur bei der Groß-/Kleinschreibung unterscheiden. Ohne den Schalter hätte der Befehl einen Fehler ausgelöst.

Beispiel 5: Roundtrip für ein einzelnes Elementarray

Dieser Befehl zeigt ein Beispiel, in dem der -NoEnumerate Switch verwendet wird, um ein einzelnes ELEMENT-JSON-Array zu roundtripen.

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

Die JSON-Zeichenfolge enthält ein Array mit einem einzelnen Element. Ohne den Schalter wird der JSON-Code in ein PSObject konvertiert und dann mit dem ConvertTo-Json Befehl wieder in eine einzelne ganze Zahl konvertiert.

Parameter

-AsHashtable

Konvertiert den JSON-Code in ein Hashtabellenobjekt. Dieser Switch wurde in PowerShell 6.0 eingeführt. Ab PowerShell 7.3 ist das Objekt eine OrderedHashtable und behält die Reihenfolge der Schlüssel aus dem JSON-Code bei. In früheren Versionen ist das Objekt eine Hashtable.

Es gibt mehrere Szenarien, in denen sie einige Einschränkungen des ConvertFrom-Json Cmdlets überwinden kann.

  • Ohne diesen Schalter werden zwei oder mehr Schlüssel in einem JSON-Objekt ohne Berücksichtigung der Groß-/Kleinschreibung identisch behandelt, sie werden als identische Schlüssel behandelt. In diesem Fall ist nur der letzte dieser Nicht-Groß-/Kleinschreibung identische Schlüssel im konvertierten Objekt enthalten.
  • Ohne diesen Schalter löst das Cmdlet einen Fehler aus, wenn der JSON-Code einen Schlüssel enthält, der eine leere Zeichenfolge ist. PSCustomObject kann keine Eigenschaftsnamen haben, die leere Zeichenfolgen sind. Dies kann z. B. in project.lock.json Dateien auftreten.
  • Hashtabellen können für bestimmte Datenstrukturen schneller verarbeitet werden.

Parametereigenschaften

Typ:SwitchParameter
Standardwert:False
Unterstützt Platzhalter:False
Nicht anzeigen:False

Parametersätze

(All)
Position:Named
Obligatorisch.:False
Wert aus Pipeline:False
Wert aus Pipeline nach dem Eigenschaftsnamen:False
Wert aus verbleibenden Argumenten:False

-DateKind

Gibt die Methode an, die beim Analysieren von Datumszeitwerten in der JSON-Zeichenfolge verwendet wird. Die zulässigen Werte für diesen Parameter sind:

  • Default
  • Local
  • Utc
  • Offset
  • String

Informationen dazu, wie sich diese Werte auf die Konvertierung auswirken, finden Sie in den Details in den NOTIZEN.

Dieser Parameter wurde in PowerShell 7.5 eingeführt.

Parametereigenschaften

Typ:JsonDateKind
Standardwert:Default
Zulässige Werte:Default, Local, Utc, Offset, String
Unterstützt Platzhalter:False
Nicht anzeigen:False

Parametersätze

(All)
Position:Named
Obligatorisch.:False
Wert aus Pipeline:False
Wert aus Pipeline nach dem Eigenschaftsnamen:False
Wert aus verbleibenden Argumenten:False

-Depth

Ruft die maximale Tiefe ab, über die die JSON-Eingabe verfügen darf, oder legt sie fest. Der Standardwert ist 1024.

Dieser Parameter wurde in PowerShell 6.2 eingeführt.

Parametereigenschaften

Typ:Int32
Standardwert:None
Unterstützt Platzhalter:False
Nicht anzeigen:False

Parametersätze

(All)
Position:Named
Obligatorisch.:False
Wert aus Pipeline:False
Wert aus Pipeline nach dem Eigenschaftsnamen:False
Wert aus verbleibenden Argumenten:False

-InputObject

Gibt die JSON-Zeichenfolgen an, die in JSON-Objekte konvertiert werden sollen. Geben Sie eine Variable ein, die die Zeichenfolge enthält, oder geben Sie einen Befehl oder Ausdruck ein, der die Zeichenfolge abruft. Sie können auch eine Zeichenfolge an ConvertFrom-Json.

Der InputObject-Parameter ist erforderlich, der Wert kann jedoch eine leere Zeichenfolge sein. Wenn das Eingabeobjekt eine leere Zeichenfolge ist, ConvertFrom-Json wird keine Ausgabe generiert. Der InputObject-Wert kann nicht sein $null.

Parametereigenschaften

Typ:String
Standardwert:None
Unterstützt Platzhalter:False
Nicht anzeigen:False

Parametersätze

(All)
Position:0
Obligatorisch.:True
Wert aus Pipeline:True
Wert aus Pipeline nach dem Eigenschaftsnamen:False
Wert aus verbleibenden Argumenten:False

-NoEnumerate

Gibt an, dass die Ausgabe nicht aufgezählt wird.

Wenn Sie diesen Parameter festlegen, werden Arrays als einzelnes Objekt gesendet, anstatt jedes Element separat zu senden. Dadurch wird sichergestellt, dass JSON per ConvertTo-JsonRoundtripped erfolgen kann.

Parametereigenschaften

Typ:SwitchParameter
Standardwert:False
Unterstützt Platzhalter:False
Nicht anzeigen:False

Parametersätze

(All)
Position:Named
Obligatorisch.:False
Wert aus Pipeline:False
Wert aus Pipeline nach dem Eigenschaftsnamen:False
Wert aus verbleibenden Argumenten:False

CommonParameters

Dieses Cmdlet unterstützt die allgemeinen Parameter -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction und -WarningVariable. Weitere Informationen findest du unter about_CommonParameters.

Eingaben

String

Sie können eine JSON-Zeichenfolge an ConvertFrom-Json.

Ausgaben

PSCustomObject

OrderedHashtable

Hinweise

Dieses Cmdlet wird mit Newtonsoft Json.NET implementiert.

Ab PowerShell 6 versucht, Zeichenfolgen, die als Zeitstempel formatiert sind, ConvertTo-Json in DateTime-Werte zu konvertieren.

PowerShell 7.5 hat den DateKind-Parameter hinzugefügt, mit dem Sie steuern können, wie Zeitstempelzeichenfolgen konvertiert werden. Der Parameter akzeptiert die folgenden Werte:

  • Default - Wandelt den Zeitstempel gemäß den folgenden Regeln in eine [datetime] Instanz um:
    • Wenn in der Eingabezeichenfolge keine Zeitzoneninformationen vorhanden sind, konvertiert der Json.NET Serializer den Wert als nicht angegebenen Zeitwert.
    • Wenn es sich bei den Zeitzoneninformationen um eine nachfolgende Z handelt, konvertiert der Json.NET Serializer den Zeitstempel in einen UTCWert.
    • Wenn der Zeitstempel einen UTC-Offset enthält, wird +02:00der Offset in die konfigurierte Zeitzone des Anrufers konvertiert. Die Standardmäßige Ausgabeformatierung gibt nicht den ursprünglichen Zeitzonenoffset an.
  • Local – Konvertiert den Zeitstempel in eine [datetime] Instanz in der lokalen Zeit. Wenn der Zeitstempel einen UTC-Offset enthält, wird der Offset in die konfigurierte Zeitzone des Aufrufers konvertiert. Die Standardmäßige Ausgabeformatierung gibt nicht den ursprünglichen Zeitzonenoffset an.
  • Utc – Wandelt den Wert in eine [datetime] Instanz in UTC-Zeit um.
  • Offset – Konvertiert den Zeitstempel in eine [DateTimeOffset] Instanz mit dem Zeitzonenoffset der ursprünglichen Zeichenfolge, die in dieser Instanz beibehalten wird. Wenn die unformatierte Zeichenfolge keinen Zeitzonenoffset-Offset enthält, wird der DateTimeOffset-Wert in der lokalen Zeitzone angegeben.
  • String – Behält den Wert der [string] Instanz bei. Dadurch wird sichergestellt, dass jede benutzerdefinierte Analyselogik auf den Unformatierten Zeichenfolgenwert angewendet werden kann.

Der PSObject-Typ behält die Reihenfolge der Eigenschaften bei, wie in der JSON-Zeichenfolge dargestellt. Ab PowerShell 7.3 erstellt der AsHashtable-Parameter eine OrderedHashtable. Die Schlüssel-Wert-Paare werden in der Reihenfolge hinzugefügt, die in der JSON-Zeichenfolge dargestellt wird. Die OrderedHashtable behält diese Reihenfolge bei.