Freigeben über

ConvertFrom-Json

  • Referenz
Modul:
Microsoft.PowerShell.Utility

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

Syntax

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

Beschreibung

Das cmdlet ConvertFrom-Json konvertiert eine json-formatierte Zeichenfolge (JavaScript Object Notation) in eine benutzerdefinierte 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 Cmdlet ConvertTo-Json, um eine JSON-Zeichenfolge aus einem beliebigen Objekt zu generieren.

Dieses Cmdlet wurde in PowerShell 3.0 eingeführt.

Anmerkung

In Windows PowerShell 5.1 hat ConvertFrom-Json einen Fehler zurückgegeben, als es auf einen JSON-Kommentar getroffen ist. In PowerShell 6 und höher unterstützt das Cmdlet JSON mit Kommentaren. JSON-Kommentare werden nicht in den vom Cmdlet ausgegebenen Objekten erfasst. Weitere Informationen finden Sie unter dem Abschnitt JSON-Kommentare im Artikel about_Comments.

Beispiele

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

Dieser Befehl verwendet die Cmdlets ConvertTo-Json und ConvertFrom-Json, um ein DateTime--Objekt aus dem Cmdlet Get-Date 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 cmdlet Select-Object verwendet, um alle Eigenschaften des DateTime--Objekts abzurufen. Es verwendet das Cmdlet ConvertTo-Json, um das DateTime--Objekt in eine Zeichenfolge zu konvertieren, die als JSON-Objekt formatiert ist, und das cmdlet ConvertFrom-Json, 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 Cmdlet Invoke-WebRequest zum Abrufen von JSON-Zeichenfolgen aus einem Webdienst und verwendet dann das Cmdlet ConvertFrom-Json zum Konvertieren von JSON-Inhalten in Objekte, 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 Cmdlet Invoke-RestMethod 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 das cmdlet ConvertFrom-Json verwenden, um eine JSON-Datei in ein benutzerdefiniertes PowerShell-Objekt zu konvertieren.

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

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

Beispiel 4: Konvertieren einer JSON-Zeichenfolge in eine Hashtabelle

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

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

Die JSON-Zeichenfolge enthält zwei Schlüssel-Wert-Paare mit Schlüsseln, die sich nur in der Schreibweise unterscheiden. Ohne den Schalter hätte der Befehl einen Fehler ausgelöst.

Beispiel 5: Abrundung eines Arrays mit einem einzigen Element

Dieser Befehl zeigt ein Beispiel, in dem der Schalter -NoEnumerate verwendet wird, um ein JSON-Array mit einem einzelnen Element zu runden.

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 führt die Konvertierung des JSON in ein PSObject und die anschließende Rückkonvertierung mit dem ConvertTo-Json Befehl zu einer einzigen Ganzzahl.

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 Hashtabelle.

Es gibt mehrere Szenarien, in denen einige Einschränkungen des cmdlets ConvertFrom-Json überwunden werden können.

  • Ohne diesen Schalter werden zwei oder mehr Schlüssel in einem JSON-Objekt, die nur hinsichtlich der Groß- und Kleinschreibung identisch sind, als identische Schlüssel behandelt. In diesem Fall wird nur der letzte dieser case-insensitiv identischen Schlüssel in das konvertierte Objekt aufgenommen.
  • 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- darf keine Eigenschaftsnamen haben, die leere Zeichenfolgen sind. Dies kann beispielsweise in project.lock.json Dateien auftreten.
  • Hashtabellen können für bestimmte Datenstrukturen schneller verarbeitet werden.
Typ:SwitchParameter
Position:Named
Standardwert:False
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren: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 der NOTES.

Dieser Parameter wurde in PowerShell 7.5 eingeführt.

Typ:Microsoft.PowerShell.Commands.JsonDateKind
Zulässige Werte:Default, Local, Utc, Offset, String
Position:Named
Standardwert:Default
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren: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.

Typ:Int32
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren: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 übergeben.

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

Typ:String
Position:0
Standardwert:None
Erforderlich:True
Pipelineeingabe akzeptieren:True
Platzhalterzeichen akzeptieren: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. Dies garantiert, dass JSON einen Round-Trip über ConvertTo-Json durchführen kann.

Typ:SwitchParameter
Position:Named
Standardwert:False
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

Eingaben

String

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

Ausgaben

PSCustomObject

OrderedHashtable

Hinweise

Dieses Cmdlet wird mit Newtonsoft Json.NETimplementiert.

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

PowerShell 7.5 hat den parameter DateKind 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 Serialisierer den Wert als nicht angegebenen Zeitwert.
    • Wenn es sich bei den Zeitzoneninformationen um eine nachfolgende Zhandelt, konvertiert der Json.NET Serializer den Zeitstempel in einen UTC- Wert.
    • Wenn der Zeitstempel einen UTC-Offset wie +02:00enthält, wird der 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 – Wandelt den Zeitstempel in eine [DateTimeOffset] Instanz um, wobei der Zeitzonenoffset der ursprünglichen Zeichenfolge in dieser Instanz beibehalten wird. Wenn die unformatierte Zeichenfolge keinen Zeitzonenversatz 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 Parameter AsHashtable eine OrderedHashtable. Die Schlüssel-Wert-Paare werden in der Reihenfolge hinzugefügt, die in der JSON-Zeichenfolge dargestellt wird. Die OrderedHashtable bewahrt diese Reihenfolge.