ConvertFrom-Json (Microsoft.PowerShell.Utility)

ConvertFrom-Json

Модуль:

Microsoft.PowerShell.Utility

Преобразует строку в формате JSON в пользовательский объект или хеш-таблицу.

Синтаксис

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

Описание

Командлет ConvertFrom-Json преобразует строку в формате JavaScript Object Notation (JSON) в пользовательский объект PSObject или Hashtable, который имеет свойство для каждого поля. в строке JSON. JSON обычно используется веб-сайтами для текстового представления объектов. Командлет добавляет свойства к новому объекту при обработке каждой строки строки JSON.

Стандарт JSON допускает дублирование имен ключей, что запрещено в типах PSObject и Hashtable. Например, если строка JSON содержит повторяющиеся ключи, этот командлет использует только последний ключ. Другие примеры смотрите ниже.

Чтобы создать строку JSON из любого объекта, используйте командлет ConvertTo-Json.

Этот командлет был представлен в PowerShell 3.0.

Примеры

Пример 1. Преобразование объекта DateTime в объект JSON

Эта команда использует командлеты ConvertTo-Json и ConvertFrom-Json для преобразования объекта DateTime из Get-Date командлет в объект 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 для получения всех свойств объекта DateTime. Он использует командлет ConvertTo-Json для преобразования объекта DateTime в строку, отформатированную как объект JSON, и командлет ConvertFrom-Json для преобразования Строка в формате JSON для объекта PSCustomObject.

Пример 2. Получите строки JSON из веб-службы и преобразуйте их в объекты PowerShell.

Эта команда использует командлет Invoke-WebRequest для получения строк JSON из веб-службы, а затем использует командлет 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, который автоматически преобразует содержимое JSON в объекты.

Пример 3. Преобразование строки JSON в пользовательский объект

В этом примере показано, как использовать командлет ConvertFrom-Json для преобразования файла JSON в пользовательский объект PowerShell.

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

Команда использует командлет Get-Content для получения строк в файле JSON. Параметр Raw возвращает весь файл как один объект JSON. Затем он использует оператор конвейера для отправки строки с разделителями в командлет ConvertFrom-Json, который преобразует ее в пользовательский объект.

Пример 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

Принимайте подстановочные знаки:

False

-Depth

Получает или задает максимальную глубину, которую разрешено иметь входным данным JSON. По умолчанию — 1024.

Этот параметр был введен в PowerShell 6.2.

Тип :

Int32

Позиция:

Именованный

Значение по умолчанию:

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

OrderedHashtable

Примечания

Этот командлет реализован с использованием Newtonsoft Json.NET.

Начиная с PowerShell 6, ConvertTo-Json пытается преобразовать строки, отформатированные как метки времени, в значения DateTime. Преобразованное значение представляет собой экземпляр [datetime] со свойством Kind, установленным следующим образом:

• Не указано, если во входной строке нет информации о часовом поясе.
• Utc, если информация о часовом поясе завершается Z.
• Локальный, если информация о часовом поясе указана в виде завершающего значения UTC смещение, например +02:00. Смещение правильно преобразуется в настроенный часовой пояс вызывающего абонента. Форматирование вывода по умолчанию не указывает исходное смещение часового пояса.

Тип PSObject поддерживает порядок свойств, представленный в строке JSON. Начиная с PowerShell 7.3, параметр AsHashtable создает OrderedHashtable. Пары ключ-значение добавляются в порядке, указанном в строке JSON. OrderedHashtable сохраняет этот порядок.