Compartir vía

ConvertFrom-Json

Módulo:
Microsoft.PowerShell.Utility Module

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

Sintaxis

Default (Es el valor predeterminado). 

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

Description

El cmdlet ConvertFrom-Json convierte una cadena en formato JSON (JavaScript Object Notation) en un PSObject personalizado o en un objeto Hashtable con una propiedad para cada campo en 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, que 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. Los comentarios JSON no se capturan en la salida de los objetos por el cmdlet. 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 el conmutador, el comando habría producido 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 switch, la conversión del JSON a un PSObject y luego convertirlo de nuevo con el comando ConvertTo-Json resulta en un único número entero.

Parámetros

-AsHashtable

Convierte el JSON en un objeto de tabla hash. Este interruptor 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.

Propiedades del parámetro

Tipo:SwitchParameter
Valor predeterminado:False
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes: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.

Propiedades del parámetro

Tipo:Microsoft.PowerShell.Commands.JsonDateKind
Valor predeterminado:Default
Valores aceptados:Default, Local, Utc, Offset, String
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes: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.

Propiedades del parámetro

Tipo:Int32
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes: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.

Propiedades del parámetro

Tipo:String
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:0
Mandatory:True
Valor de la canalización:True
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes: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.

Propiedades del parámetro

Tipo:SwitchParameter
Valor predeterminado:False
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

CommonParameters

Este cmdlet admite los parámetros comunes: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction y -WarningVariable. Para obtener más información, vea about_CommonParameters.

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.