ConvertFrom-Json

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

语法

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

说明

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

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

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

此 cmdlet 是在 PowerShell 3.0 中引入的。

注意

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

示例

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

此命令使用 ConvertTo-JsonConvertFrom-Json cmdlet 将 DateTime 对象从 Get-Date 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 字符串,然后使用 cmdlet 将 ConvertFrom-Json 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,该 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 中键的顺序。 在以前的版本中, 对象是 哈希表

在几种情况下,它可以克服 cmdlet 的某些 ConvertFrom-Json 限制。

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

-Depth

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

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

Type:Int32
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-InputObject

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

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

Type:String
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-NoEnumerate

指定不枚举输出。

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

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

输入

String

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

输出

PSCustomObject

OrderedHashtable

备注

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

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

  • Unspecified如果输入字符串中没有时区信息,则为 。
  • Utc如果时区信息为尾随 Z,则为 。
  • Local如果时区信息作为尾随 UTC 偏移量 提供,则为 ,例如 +02:00。 偏移量正确转换为调用方配置的时区。 默认输出格式不指示原始时区偏移量。

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