ConvertFrom-Json

模組:

Microsoft.PowerShell.Utility

將 JSON 格式的字串轉換成自訂物件或哈希表。

語法

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

Description

ConvertFrom-Json Cmdlet 會將 JavaScript 物件表示法 （JSON） 格式化的字串轉換成自定義 PSObject 或 Hashtable 物件，該物件具有 JSON 字串中每個字段的屬性。 網站通常會使用 JSON 來提供物件的文字表示法。 Cmdlet 會在處理 JSON 字串的每一行時，將屬性新增至新的物件。

JSON 標準允許重複的索引鍵名稱，這些名稱在 PSObject 和 哈希表 類型中禁止。 例如，如果 JSON 字串包含重複的索引鍵，則此 Cmdlet 只會使用最後一個索引鍵。 請參閱下列其他範例。

若要從任何對象產生 JSON 字串，請使用 ConvertTo-Json Cmdlet。

此 Cmdlet 已在 PowerShell 3.0 中引進。

注意

在 Windows PowerShell 5.1 中，ConvertFrom-Json 在遇到 JSON 批注時傳回錯誤。 在 PowerShell 6 和更新版本中，Cmdlet 支援具有批注的 JSON。 Cmdlet 不會在 對象輸出中擷取 JSON 批注。 如需詳細資訊，請參閱 about_Comments 文章 JSON 批注 一節。

範例

範例 1：將 DateTime 物件轉換為 JSON 物件

此命令會使用 ConvertTo-Json 和 ConvertFrom-Json Cmdlet，將 DateTime 物件從 Get-Date Cmdlet 轉換成 JSON 物件，然後轉換成 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

此範例會使用 Select-Object Cmdlet 來取得 DateTime 物件的所有屬性。 它會使用 ConvertTo-Json Cmdlet，將 DateTime 物件轉換成格式化為 JSON 物件的字串，而 ConvertFrom-Json Cmdlet 將 JSON 格式化的字串轉換成 PSCustomObject 物件。

範例 2：從 Web 服務取得 JSON 字串，並將其轉換為 PowerShell 物件

此命令會使用 Invoke-WebRequest Cmdlet 從 Web 服務取得 JSON 字串，然後使用 ConvertFrom-Json Cmdlet 將 JSON 內容轉換成可在 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

您也可以使用 Invoke-RestMethod Cmdlet，其會自動將 JSON 內容轉換成物件。

範例 3：將 JSON 字串轉換成自定義物件

此範例示範如何使用 ConvertFrom-Json Cmdlet 將 JSON 檔案轉換成 PowerShell 自定義物件。

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

命令會使用 Get-Content Cmdlet 來取得 JSON 檔案中的字串。 Raw 參數會以單一 JSON 物件的形式傳回整個檔案。 然後，它會使用管線運算符，將分隔字串傳送至 ConvertFrom-Json Cmdlet，以將它轉換成自定義物件。

範例 4：將 JSON 字串轉換成哈希表

此命令展示一個範例，其中 -AsHashtable 開關可以克服命令的限制。

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

JSON 字串包含兩個索引鍵值組，其索引鍵在大小寫上只不同。 如果沒有開關，命令將會拋出錯誤。

範例 5：單一元素陣列的來回行程

此命令顯示一個範例，其中 -NoEnumerate 開關被用來雙向處理單一元素 JSON 格式陣列。

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

JSON 字串包含具有單一元素的陣列。 如果沒有開關，將 JSON 轉換為 PSObject，然後使用 ConvertTo-Json 命令將其轉換回來，結果會是單一的整數。

參數

-AsHashtable

將 JSON 轉換為哈希表物件。 這個參數是在 PowerShell 6.0 中引進的。 從 PowerShell 7.3 開始，對像是 OrderedHashtable，並保留 JSON 中的索引鍵順序。 在舊版中，物件是 "Hashtable"。

有幾個情境可以克服 ConvertFrom-Json Cmdlet 的一些限制。

• 如果沒有此參數，當 JSON 物件中的兩個或多個索引鍵不區分大小寫時，它們會被視為相同的索引鍵。 在此情況下，轉換的物件中只會包含那些不區分大小寫的相同索引鍵中的最後一個。
• 若沒有此參數，每當 JSON 包含空字串的索引鍵時，cmdlet 就會拋出錯誤。 PSCustomObject 不能有空字串的屬性名稱。 例如，這可能發生在 project.lock.json 檔案中。
• 哈希表可以更快速地處理特定數據結構。

類型:	SwitchParameter
Position:	Named
預設值:	False
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-DateKind

指定剖析 JSON 字串中日期時間值時所使用的方法。 此參數可接受的值為：

• Default
• Local
• Utc
• Offset
• String

如需這些值如何影響轉換的資訊，請參閱 NOTES中的詳細數據。

此參數是在 PowerShell 7.5 中引進的。

類型:	Microsoft.PowerShell.Commands.JsonDateKind
接受的值:	Default, Local, Utc, Offset, String
Position:	Named
預設值:	Default
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-Depth

取得或設定允許 JSON 輸入的最大深度。 預設值為 1024。

此參數是在 PowerShell 6.2 中引進的。

類型:	Int32
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-InputObject

指定要轉換成 JSON 物件的 JSON 字串。 輸入包含字串的變數，或輸入取得字串的命令或表達式。 您也可以使用管線將字串傳送至 ConvertFrom-Json。

需要 InputObject 參數，但其值可以是空字串。 當輸入物件是空字串時，ConvertFrom-Json 不會產生任何輸出。 InputObject 值不能是 $null。

類型:	String
Position:	0
預設值:	None
必要:	True
接受管線輸入:	True
接受萬用字元:	False

-NoEnumerate

指定輸出不被列舉。

設定此參數會導致陣列以單一物件的形式傳送，而不是個別傳送每個元素。 這可確保 JSON 可以透過 ConvertTo-Json四捨五入。

類型:	SwitchParameter
Position:	Named
預設值:	False
必要:	False
接受管線輸入:	False
接受萬用字元:	False

輸入

String

您可以將 JSON 字串傳送至 ConvertFrom-Json。

輸出

PSCustomObject

OrderedHashtable

備註

此 Cmdlet 是使用 Newtonsoft Json.NET來實作。

從 PowerShell 6 開始，ConvertTo-Json 嘗試將格式化為時間戳的字串轉換成 DateTime 值。

PowerShell 7.5 新增了 DateKind 參數，可讓您控制時間戳字串的轉換方式。 參數接受下列值：

• Default - 根據下列規則，將時間戳轉換成 [datetime] 實例：
  • 如果輸入字串中沒有時區資訊，Json.NET 串行化程式會將值轉換成未指定的時間值。
  • 如果時區資訊是尾端 Z，則 Json.NET 串行化程式會將時間戳轉換成 UTC 值。
  • 如果時間戳包含 UTC 位移，例如 +02:00，則會將位移轉換成呼叫端設定的時區。 默認輸出格式不會指出原始時區位移。
• Local - 在本機 [datetime]，將時間戳轉換成 實例。 如果時間戳包含 UTC 位移，則會將位移轉換成呼叫端設定的時區。 默認輸出格式不會指出原始時區位移。
• Utc - 以 UTC 時間將值轉換成 [datetime] 實例。
• Offset - 將時間戳轉換成 [DateTimeOffset] 實例，並在該實例中保留原始字串的時區位移。 如果原始字串未包含時區位移，則會在本機時區中指定 DateTimeOffset 值。
• String - 保留 [string] 實例的值。 這可確保任何自定義剖析邏輯都可以套用至原始字串值。

PSObject 類型會維護 JSON 字串中所呈現的屬性順序。 從 PowerShell 7.3 開始，AsHashtable 參數會建立 OrderedHashtable。 索引鍵/值組會以 JSON 字串中顯示的順序新增。 OrderHashtable 會保留該順序。

相關連結

• JavaScript 和 .NET 中的 JavaScript 物件表示法簡介
• ConvertTo-Json
• Invoke-WebRequest
• Invoke-RestMethod
• 日期時間
• DateTimeOffset