ConvertFrom-Json
Преобразует строку в формате JSON в пользовательский объект или хэш-таблицу.
Синтаксис
Default (по умолчанию)
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.
Замечание
В Windows PowerShell 5.1 ConvertFrom-Json вернул ошибку при возникновении комментария JSON. В PowerShell 6 и более поздних версиях командлет поддерживает JSON с комментариями. Комментарии JSON не сохраняются в выходных данных объектов, создаваемых командлетом. Для получения дополнительной информации см. раздел Комментарии JSON статьи about_Comments.
Примеры
Пример 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. В предыдущих версиях объект представляет собой таблицу хэширования.
Существует несколько сценариев, в которых можно преодолеть некоторые ограничения командлета ConvertFrom-Json.
- Без этого параметра, если два или более ключей в объекте JSON совпадают без учета регистра, они обрабатываются как одинаковые ключи. В этом случае в преобразованный объект включен только последний из этих идентичных (без учета регистра) ключей.
- Без этого параметра командлет выдает ошибку всякий раз, когда JSON содержит ключ, который является пустой строкой.
PSCustomObject не могут иметь имена свойств, которые являются пустыми строками. Например, это может произойти в файлах
project.lock.json. - Хэш-таблицы можно обрабатывать быстрее для определенных структур данных.
Свойства параметра
| Тип: | SwitchParameter |
| Default value: | False |
| Поддерживаются подстановочные знаки: | False |
| DontShow: | False |
Наборы параметров
(All)
| Position: | Named |
| Обязательно: | False |
| Значение из конвейера: | False |
| Значение из конвейера по имени свойства: | False |
| Значение из оставшихся аргументов: | False |
-Depth
Возвращает или задает максимальную глубину входных данных JSON. Значение по умолчанию — 1024.
Этот параметр появился в PowerShell 6.2.
Свойства параметра
| Тип: | Int32 |
| Default value: | None |
| Поддерживаются подстановочные знаки: | False |
| DontShow: | False |
Наборы параметров
(All)
| Position: | Named |
| Обязательно: | False |
| Значение из конвейера: | False |
| Значение из конвейера по имени свойства: | False |
| Значение из оставшихся аргументов: | False |
-InputObject
Указывает строки JSON для преобразования в объекты JSON. Введите переменную, содержащую строку, или введите команду или выражение, которое получает строку. Можно также переслать строку в ConvertFrom-Json.
Параметр InputObject является обязательным, но его значение может быть пустой строкой. Если входной объект является пустой строкой, ConvertFrom-Json не создает выходные данные. Значение объекта ввода не может быть $null.
Свойства параметра
| Тип: | String |
| Default value: | None |
| Поддерживаются подстановочные знаки: | False |
| DontShow: | False |
Наборы параметров
(All)
| Position: | 0 |
| Обязательно: | True |
| Значение из конвейера: | True |
| Значение из конвейера по имени свойства: | False |
| Значение из оставшихся аргументов: | False |
-NoEnumerate
Указывает, что выходные данные не перечисляются.
Установка этого параметра приводит к отправке массивов в виде одного объекта вместо отправки каждого элемента отдельно. Это гарантирует, что JSON можно передавать туда и обратно с помощью ConvertTo-Json.
Свойства параметра
| Тип: | SwitchParameter |
| Default value: | False |
| Поддерживаются подстановочные знаки: | False |
| DontShow: | False |
Наборы параметров
(All)
| Position: | Named |
| Обязательно: | False |
| Значение из конвейера: | False |
| Значение из конвейера по имени свойства: | False |
| Значение из оставшихся аргументов: | False |
CommonParameters
Этот командлет поддерживает общие параметры: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction и -WarningVariable. Дополнительные сведения см. в разделе about_CommonParameters.
Входные данные
String
Строку JSON можно передать в ConvertFrom-Json.
Выходные данные
PSCustomObject
OrderedHashtable
Примечания
Этот командлет реализован с помощью 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. OrderHashtable сохраняет этот порядок.
