ConvertFrom-Json

模組:
Microsoft.PowerShell.Utility Module

將 JSON 格式的字串轉換為自訂物件或雜湊表。

語法

Default (預設值) 

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

Description

這個 ConvertFrom-Json cmdlet 會將 JavaScript 物件符號（JSON）格式的字串轉換成自訂的 PSObject 或 Hashtable 物件，該物件對 JSON 字串中的每個欄位都有屬性。 JSON 常被網站用來提供物件的文字表示。 指令長在處理 JSON 字串的每一行時，會將屬性加入新物件。

JSON 標準允許重複鍵名，而 PSObject 和 雜湊表 類型禁止重複鍵名。 例如，如果 JSON 字串包含重複的鍵，這個 cmdlet 只會使用最後一個鍵。 請參考下方其他範例。

要從任何物件產生 JSON 字串，請使用 ConvertTo-Json cmdlet。

此 Cmdlet 已在 PowerShell 3.0 中引進。

Note

在 PowerShell 5.1 Windows 中，ConvertFrom-Json 遇到 JSON 註解時會回傳錯誤。 在 PowerShell 6 及以上版本中，該 cmdlet 支援帶有註解的 JSON 檔案。 JSON 註解不會被 cmdlet 在物件輸出中擷取。 欲了解更多資訊，請參閱about_Comments文章的 JSON 評論區。

範例

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

此指令使用 ConvertTo-Json and ConvertFrom-Json cmdlets 將 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 物件的所有屬性。 它使用 cmdlet 將 DateTime 物件轉換成格式化為 JSON 物件的字串，並ConvertFrom-Json使用 ConvertTo-Json cmdlet 將 JSON 格式的字串轉換成 PSCustomObject 物件。

範例 2：從網路服務取得 JSON 字串並轉換成 PowerShell 物件

這個指令使用 Invoke-WebRequest cmdlet 從網路服務取得 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 。

  • 若沒有此切換，當 JSON 物件中的兩個或以上鍵不區分大小寫相同時，它們會被視為相同的鍵。 此時，轉換物件中僅包含最後一個大小寫不區分相同的鍵。
  • 如果沒有這個切換，當 JSON 包含空字串的鍵時，指令長子就會拋出錯誤。 PSCustomObject 不能有空字串的屬性名稱。 例如，這可能發生在 project.lock.json 檔案中。
  • 雜湊表對於某些資料結構可以更快處理。

參數屬性

類型:SwitchParameter
預設值:False
支援萬用字元:False
不要顯示:False

參數集

(All)
Position:Named
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-DateKind

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

  • Default
  • Local
  • Utc
  • Offset
  • String

關於這些數值如何影響轉換的資訊，請參閱 備註中的詳細資訊。

此參數於 PowerShell 7.5 中引入。

參數屬性

類型:JsonDateKind
預設值:Default
接受的值:Default, Local, Utc, Offset, String
支援萬用字元:False
不要顯示:False

參數集

(All)
Position:Named
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-Depth

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

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

參數屬性

類型:Int32
預設值:None
支援萬用字元:False
不要顯示:False

參數集

(All)
Position:Named
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-InputObject

指定要轉換成 JSON 物件的 JSON 字串。 輸入包含該字串的變數，或輸入指令或表達式取得該字串。 你也可以把一條線管接到 ConvertFrom-Json。

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

參數屬性

類型:String
預設值:None
支援萬用字元:False
不要顯示:False

參數集

(All)
Position:0
必要:True
來自管線的值:True
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-NoEnumerate

明確表示輸出不會被列舉。

設定此參數後，陣列會作為單一物件傳送，而非分別傳送每個元素。 這確保了 JSON 可以透過 進行循環運算 ConvertTo-Json。

參數屬性

類型:SwitchParameter
預設值:False
支援萬用字元:False
不要顯示:False

參數集

(All)
Position:Named
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

CommonParameters

此 cmdlet 支援常見參數：-Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction 和 -WarningVariable。 如需詳細資訊，請參閱 about_CommonParameters。

輸入

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 字串的順序相加。 OrderedHashtable 會保留這個順序。