ConvertFrom-Json (Microsoft.PowerShell.Utility)

ConvertFrom-Json

将 JSON 格式的字符串转换为自定义对象或哈希表。

句法

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

描述

ConvertFrom-Json cmdlet 将 JavaScript 对象表示法 (JSON) 格式的字符串转换为具有每个字段属性的自定义 PSObject 或 Hashtable 对象在 JSON 字符串中。网站通常使用 JSON 来提供对象的文本表示。该 cmdlet 在处理 JSON 字符串的每一行时将属性添加到新对象。

JSON 标准允许重复的键名称，这在 PSObject 和 Hashtable 类型中是被禁止的。例如，如果 JSON 字符串包含重复键，则此 cmdlet 仅使用最后一个键。请参阅下面的其他示例。

要从任何对象生成 JSON 字符串，请使用 ConvertTo-Json cmdlet。

此 cmdlet 是在 PowerShell 3.0 中引入的。

笔记

从 PowerShell 6 开始，cmdlet 支持带注释的 JSON。 JSON 注释以两个正斜杠 (//) 字符开头。 JSON 注释不会在 cmdlet 输出的对象中捕获。在 PowerShell 6 之前，ConvertFrom-Json 在遇到 JSON 注释时会返回错误。

示例

示例 1：将 DateTime 对象转换为 JSON 对象

此命令使用 ConvertTo-Json 和 ConvertFrom-Json cmdlet 从 Get-Date 转换 DateTime 对象cmdlet 到 JSON 对象，然后到 PSCustomObject。

Get-Date | Select-Object -Property * | ConvertTo-Json | ConvertFrom-Json

DisplayHint : 2
DateTime    : Friday, January 13, 2012 8:06:31 PM
Date        : 1/13/2012 8:00:00 AM
Day         : 13
DayOfWeek   : 5
DayOfYear   : 13
Hour        : 20
Kind        : 2
Millisecond : 400
Minute      : 6
Month       : 1
Second      : 31
Ticks       : 634620819914009002
TimeOfDay   : @{Ticks=723914009002; Days=0; Hours=20; Milliseconds=400; Minutes=6; Seconds=31; TotalDays=0.83786343634490734; TotalHours=20.108722472277776; TotalMilliseconds=72391400.900200009; TotalMinutes=1206.5233483366667;TotalSeconds=72391.4009002}
Year        : 2012

该示例使用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 中键的顺序。在以前的版本中，该对象是哈希表。

在多种情况下，它可以克服 ConvertFrom-Json cmdlet 的一些限制。

• 如果没有此开关，当 JSON 对象中的两个或多个键不区分大小写地相同时，它们将被视为相同的键。在这种情况下，只有最后一个不区分大小写的相同键包含在转换后的对象中。
• 如果没有此开关，只要 JSON 包含空字符串键，cmdlet 就会引发错误。 PSCustomObject 的属性名称不能为空字符串。例如，这可能发生在 project.lock.json 文件中。
• 对于某些数据结构，哈希表可以更快地处理。

SwitchParameter

命名

False

False

False

False

-Depth

获取或设置允许 JSON 输入具有的最大深度。默认值为 1024。

此参数是在 PowerShell 6.2 中引入的。

整数32

命名

None

False

False

False

-InputObject

指定要转换为 JSON 对象的 JSON 字符串。输入包含字符串的变量，或键入获取字符串的命令或表达式。您还可以通过管道将字符串传递给 ConvertFrom-Json。

InputObject 参数是必需的，但其值可以是空字符串。当输入对象为空字符串时，ConvertFrom-Json 不会生成任何输出。 InputObject 值不能为 $null。

String

0

None

True

True

False

-NoEnumerate

指定不枚举输出。

设置此参数会导致数组作为单个对象发送，而不是单独发送每个元素。这保证了 JSON 可以通过 ConvertTo-Json 进行往返。

SwitchParameter

命名

False

False

False

False

输入

字符串

您可以通过管道将 JSON 字符串传递给 ConvertFrom-Json。

输出

PSCustomObject

有序哈希表

笔记

此 cmdlet 是使用 Newtonsoft Json.NET 实现的。

从 PowerShell 6 开始，ConvertTo-Json 尝试将时间戳格式的字符串转换为 DateTime 值。转换后的值是一个 [datetime] 实例，其 Kind 属性设置如下：

• 未指定，如果输入字符串中没有时区信息。
• Utc，如果时区信息是尾随 Z。
• 本地，如果时区信息以尾随 UTC 偏移 形式给出，例如 +02:00。偏移量已正确转换为调用者配置的时区。默认输出格式不指示原始时区偏移。

PSObject 类型维护 JSON 字符串中呈现的属性顺序。从 PowerShell 7.3 开始，AsHashtable 参数创建一个 OrderedHashtable。键值对按照 JSON 字符串中显示的顺序添加。 OrderedHashtable 保留该顺序。