Compartir a través de

ConvertFrom-Json

  • Referencia
Módulo:
Microsoft.PowerShell.Utility

Convierte una cadena con formato JSON en un objeto personalizado o en una tabla hash.

Sintaxis

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

Description

El cmdlet ConvertFrom-Json convierte una cadena con formato de notación de objetos JavaScript (JSON) en un PSObject personalizado o en un objeto Hashtable que tiene una propiedad para cada campo de la cadena JSON. Los sitios web suelen usar JSON para proporcionar una representación textual de los objetos. El cmdlet agrega las propiedades al nuevo objeto a medida que procesa cada línea de la cadena JSON.

El estándar JSON permite nombres de clave duplicados, los cuales están prohibidos en los tipos PSObject y Hashtable. Por ejemplo, si la cadena JSON contiene claves duplicadas, este cmdlet usa solo la última clave. Vea otros ejemplos a continuación.

Para generar una cadena JSON a partir de cualquier objeto, use el cmdlet ConvertTo-Json.

Este cmdlet se introdujo en PowerShell 3.0.

Nota

En Windows PowerShell 5.1, ConvertFrom-Json devolvió un error cuando encontró un comentario JSON. En PowerShell 6 y versiones posteriores, el cmdlet admite JSON con comentarios. El cmdlet no captura los comentarios JSON en la salida de los objetos. Para obtener más información, consulte la sección comentarios JSON del artículo about_Comments.

Ejemplos

Ejemplo 1: Convertir un objeto DateTime en un objeto JSON

Este comando usa los cmdlets ConvertTo-Json y ConvertFrom-Json para convertir un objeto DateTime del cmdlet Get-Date a un objeto JSON y, a continuación, a un 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

En el ejemplo se usa el cmdlet Select-Object para obtener todas las propiedades del objeto DateTime. Usa el cmdlet ConvertTo-Json para convertir el objeto DateTime en una cadena con formato JSON y el cmdlet ConvertFrom-Json para convertir la cadena con formato JSON en un objeto PSCustomObject.

Ejemplo 2: Obtención de cadenas JSON de un servicio web y conversión a objetos de PowerShell

Este comando usa el cmdlet Invoke-WebRequest para obtener cadenas JSON de un servicio web y, a continuación, usa el cmdlet ConvertFrom-Json para convertir contenido JSON en objetos que se pueden administrar en 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

También puede usar el cmdlet Invoke-RestMethod, que convierte automáticamente el contenido JSON en objetos.

Ejemplo 3: Conversión de una cadena JSON en un objeto personalizado

En este ejemplo se muestra cómo usar el cmdlet ConvertFrom-Json para convertir un archivo JSON en un objeto personalizado de PowerShell.

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

El comando usa Get-Content cmdlet para obtener las cadenas en un archivo JSON. El parámetro Raw devuelve todo el archivo como un único objeto JSON. A continuación, usa el operador de canalización para enviar la cadena delimitada al cmdlet ConvertFrom-Json, que lo convierte en un objeto personalizado.

Ejemplo 4: Conversión de una cadena JSON en una tabla hash

Este comando muestra un ejemplo en el que el modificador -AsHashtable puede superar las limitaciones del comando.

'{ "key":"value1", "Key":"value2" }' | ConvertFrom-Json -AsHashtable

La cadena JSON contiene dos pares clave-valor con claves que solo difieren en mayúsculas y minúsculas. Sin la opción, el comando habría generado un error.

Ejemplo 5: Ida y vuelta de una sola matriz de elementos

Este comando muestra un ejemplo en el que el modificador -NoEnumerate se usa para realizar un recorrido de ida y vuelta de una matriz JSON de un solo elemento.

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

La cadena JSON contiene una matriz con un solo elemento. Sin el interruptor, la conversión del JSON en un PSObject y luego volver a convertirlo con el comando ConvertTo-Json da como resultado un único entero.

Parámetros

-AsHashtable

Convierte el JSON en un objeto de tabla hash. Este conmutador se introdujo en PowerShell 6.0. A partir de PowerShell 7.3, el objeto es un OrderedHashtable y conserva el orden de las claves del JSON. En versiones anteriores, el objeto es un Hashtable.

Hay varios escenarios en los que puede superar algunas limitaciones del cmdlet ConvertFrom-Json.

  • Sin esta opción, cuando dos o más claves de un objeto JSON son idénticas sin distinguir entre mayúsculas y minúsculas, se tratan como claves idénticas. En ese caso, solo se incluye en el objeto convertido la última de las claves que son idénticas sin distinguir entre mayúsculas y minúsculas.
  • Sin este modificador, el cmdlet produce un error cada vez que el JSON contiene una clave que es una cadena vacía. psCustomObject no puede tener nombres de propiedad que sean cadenas vacías. Por ejemplo, esto puede ocurrir en archivos project.lock.json.
  • Las tablas hash se pueden procesar más rápido para determinadas estructuras de datos.
Tipo:SwitchParameter
Posición:Named
Valor predeterminado:False
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-DateKind

Especifica el método utilizado al analizar valores de fecha y hora en la cadena JSON. Los valores aceptables para este parámetro son:

  • Default
  • Local
  • Utc
  • Offset
  • String

Para obtener información sobre cómo afectan estos valores a la conversión, vea los detalles de NOTES.

Este parámetro se introdujo en PowerShell 7.5.

Tipo:Microsoft.PowerShell.Commands.JsonDateKind
Valores aceptados:Default, Local, Utc, Offset, String
Posición:Named
Valor predeterminado:Default
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-Depth

Obtiene o establece la profundidad máxima permitida para la entrada JSON. El valor predeterminado es 1024.

Este parámetro se introdujo en PowerShell 6.2.

Tipo:Int32
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-InputObject

Especifica las cadenas JSON que se van a convertir en objetos JSON. Escriba una variable que contenga la cadena o escriba un comando o expresión que obtenga la cadena. También puede canalizar una cadena a ConvertFrom-Json.

Se requiere el parámetro InputObject, pero su valor puede ser una cadena vacía. Cuando el objeto de entrada es una cadena vacía, ConvertFrom-Json no genera ninguna salida. El valor de InputObject no puede ser $null.

Tipo:String
Posición:0
Valor predeterminado:None
Requerido:True
Aceptar entrada de canalización:True
Aceptar caracteres comodín:False

-NoEnumerate

Especifica que la salida no está enumerada.

Establecer este parámetro hace que las matrices se envíen como un único objeto en lugar de enviar cada elemento por separado. Esto garantiza que JSON se puede procesar ida y vuelta mediante ConvertTo-Json.

Tipo:SwitchParameter
Posición:Named
Valor predeterminado:False
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

Entradas

String

Puede redirigir una cadena JSON a ConvertFrom-Json.

Salidas

PSCustomObject

OrderedHashtable

Notas

Este cmdlet se implementa mediante Newtonsoft Json.NET.

A partir de PowerShell 6, ConvertTo-Json intenta convertir cadenas con formato de marcas de tiempo a valores de DateTime.

PowerShell 7.5 agregó el parámetro DateKind, que permite controlar cómo se convierte la cadena de marca de tiempo. El parámetro acepta los siguientes valores:

  • Default: convierte la marca de tiempo en una instancia de [datetime] según las reglas siguientes:
    • Si no hay información de zona horaria en la cadena de entrada, el serializador Json.NET convierte el valor como un valor de hora no especificado.
    • Si la información de zona horaria es un Z final, el serializador de Json.NET convierte la marca de tiempo en un valor de UTC.
    • Si la marca de tiempo incluye un desplazamiento UTC como +02:00, el desplazamiento se ajusta a la zona horaria configurada del llamador. El formato de salida predeterminado no indica el desplazamiento de zona horaria original.
  • Local: convierte la marca de tiempo en una instancia de [datetime] en la hora local de en. Si la marca de tiempo incluye una diferencia horaria con UTC, el desplazamiento se convierte a la zona horaria configurada del llamante. El formato de salida predeterminado no indica el desplazamiento de zona horaria original.
  • Utc: convierte el valor en una instancia de [datetime] en hora UTC.
  • Offset: convierte la marca de tiempo a una instancia de [DateTimeOffset] con la diferencia horaria de la cadena original conservada en esa instancia. Si la cadena sin formato no contenía un desplazamiento de zona horaria, el valor de DateTimeOffset se especificará en la zona horaria local.
  • String: conserva el valor de la instancia [string]. Esto garantiza que cualquier lógica de análisis personalizada se pueda aplicar al valor de cadena sin procesar.

El tipo PSObject mantiene el orden de las propiedades tal como se muestra en la cadena JSON. A partir de PowerShell 7.3, el parámetro AsHashtable crea un OrderedHashtable. Los pares clave-valor se agregan en el orden presentado en la cadena JSON. El OrderedHashtable conserva ese orden.