ConvertFrom-Json

Module:
Microsoft.PowerShell.Utility Module

Convertit une chaîne au format JSON en objet personnalisé ou une table de hachage.

Syntaxe

Default (Par défaut) 

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

Description

L’applet ConvertFrom-Json de commande convertit une chaîne au format JSON (JavaScript Object Notation) en objet PSObject ou Hashtable personnalisé qui a une propriété pour chaque champ de la chaîne JSON. JSON est couramment utilisé par les sites web pour fournir une représentation textuelle des objets. L’applet de commande ajoute les propriétés au nouvel objet, car elle traite chaque ligne de la chaîne JSON.

La norme JSON autorise les noms de clés en double, qui sont interdits dans les types PSObject et Hashtable . Par exemple, si la chaîne JSON contient des clés en double, seule la dernière clé est utilisée par cette applet de commande. Consultez d’autres exemples ci-dessous.

Pour générer une chaîne JSON à partir d’un objet, utilisez l’applet ConvertTo-Json de commande.

Cette applet de commande a été introduite dans PowerShell 3.0.

Note

Dans Windows PowerShell 5.1, ConvertFrom-Json a retourné une erreur lorsqu’il a rencontré un commentaire JSON. Dans PowerShell 6 et versions ultérieures, l’applet de commande prend en charge JSON avec des commentaires. Les commentaires JSON ne sont pas capturés dans les objets générés par l’applet de commande. Pour plus d’informations, consultez la section commentaires JSON de l’article about_Comments .

Exemples

Exemple 1 : Convertir un objet DateTime en objet JSON

Cette commande utilise les applets de commande et ConvertFrom-Json les ConvertTo-Json applets de commande pour convertir un objet DateTime de l’applet Get-Date de commande en objet JSON, puis en 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

L’exemple utilise l’applet Select-Object de commande pour obtenir toutes les propriétés de l’objet DateTime . Il utilise l’applet ConvertTo-Json de commande pour convertir l’objet DateTime en chaîne mise en forme en tant qu’objet JSON et l’applet ConvertFrom-Json de commande pour convertir la chaîne au format JSON en objet PSCustomObject .

Exemple 2 : Obtenir des chaînes JSON à partir d’un service web et les convertir en objets PowerShell

Cette commande utilise l’applet Invoke-WebRequest de commande pour obtenir des chaînes JSON à partir d’un service web, puis elle utilise l’applet de commande pour convertir du ConvertFrom-Json contenu JSON en objets pouvant être gérés dans 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

Vous pouvez également utiliser l’applet Invoke-RestMethod de commande, qui convertit automatiquement le contenu JSON en objets.

Exemple 3 : Convertir une chaîne JSON en objet personnalisé

Cet exemple montre comment utiliser l’applet ConvertFrom-Json de commande pour convertir un fichier JSON en objet personnalisé PowerShell.

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

La commande utilise Get-Content applet de commande pour obtenir les chaînes dans un fichier JSON. Le paramètre Raw retourne le fichier entier sous la forme d’un seul objet JSON. Ensuite, il utilise l’opérateur de pipeline pour envoyer la chaîne délimitée à l’applet ConvertFrom-Json de commande, qui la convertit en objet personnalisé.

Exemple 4 : Convertir une chaîne JSON en table de hachage

Cette commande montre un exemple dans lequel le -AsHashtable commutateur peut surmonter les limitations de la commande.

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

La chaîne JSON contient deux paires de valeurs de clé avec des clés qui diffèrent uniquement en casing. Sans le commutateur, la commande aurait levée une erreur.

Exemple 5 : Aller-retour sur un tableau d’éléments unique

Cette commande montre un exemple où le -NoEnumerate commutateur est utilisé pour aller-retour sur un tableau JSON d’un seul élément.

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 chaîne JSON contient un tableau avec un seul élément. Sans le commutateur, la conversion du JSON en objet PSObject, puis sa conversion avec la ConvertTo-Json commande entraîne un entier unique.

Paramètres

-AsHashtable

Convertit le JSON en objet de table de hachage. Ce commutateur a été introduit dans PowerShell 6.0. À compter de PowerShell 7.3, l’objet est un OrderHashtable et conserve l’ordre des clés à partir du JSON. Dans les versions antérieures, l’objet est une table de hachage.

Il existe plusieurs scénarios où il peut surmonter certaines limitations de l’applet ConvertFrom-Json de commande.

  • Sans ce commutateur, quand deux clés ou plus d’un objet JSON ne respectent pas la casse, elles sont traitées comme des clés identiques. Dans ce cas, seul le dernier de ces clés identiques à la casse est inclus dans l’objet converti.
  • Sans ce commutateur, l’applet de commande génère une erreur chaque fois que le json contient une clé qui est une chaîne vide. PSCustomObject ne peut pas avoir de noms de propriété qui sont des chaînes vides. Par exemple, cela peut se produire dans des project.lock.json fichiers.
  • Les tables de hachage peuvent être traitées plus rapidement pour certaines structures de données.

Propriétés du paramètre

Type:SwitchParameter
Valeur par défaut:False
Prend en charge les caractères génériques:False
DontShow:False

Jeux de paramètres

(All)
Position:Named
Obligatoire:False
Valeur du pipeline:False
Valeur du pipeline par nom de propriété:False
Valeur des arguments restants:False

-DateKind

Spécifie la méthode utilisée lors de l’analyse des valeurs d’heure de date dans la chaîne JSON. Les valeurs acceptables pour ce paramètre sont les suivantes :

  • Default
  • Local
  • Utc
  • Offset
  • String

Pour plus d’informations sur la façon dont ces valeurs affectent la conversion, consultez les détails dans les notes.

Ce paramètre a été introduit dans PowerShell 7.5.

Propriétés du paramètre

Type:JsonDateKind
Valeur par défaut:Default
Valeurs acceptées:Default, Local, Utc, Offset, String
Prend en charge les caractères génériques:False
DontShow:False

Jeux de paramètres

(All)
Position:Named
Obligatoire:False
Valeur du pipeline:False
Valeur du pipeline par nom de propriété:False
Valeur des arguments restants:False

-Depth

Obtient ou définit la profondeur maximale que l’entrée JSON est autorisée. La valeur par défaut est 1024.

Ce paramètre a été introduit dans PowerShell 6.2.

Propriétés du paramètre

Type:Int32
Valeur par défaut:None
Prend en charge les caractères génériques:False
DontShow:False

Jeux de paramètres

(All)
Position:Named
Obligatoire:False
Valeur du pipeline:False
Valeur du pipeline par nom de propriété:False
Valeur des arguments restants:False

-InputObject

Spécifie les chaînes JSON à convertir en objets JSON. Entrez une variable qui contient la chaîne, ou tapez une commande ou une expression qui obtient la chaîne. Vous pouvez également diriger une chaîne vers ConvertFrom-Json.

Le paramètre InputObject est obligatoire, mais sa valeur peut être une chaîne vide. Lorsque l’objet d’entrée est une chaîne vide, ConvertFrom-Json ne génère aucune sortie. La valeur InputObject ne peut pas être $null.

Propriétés du paramètre

Type:String
Valeur par défaut:None
Prend en charge les caractères génériques:False
DontShow:False

Jeux de paramètres

(All)
Position:0
Obligatoire:True
Valeur du pipeline:True
Valeur du pipeline par nom de propriété:False
Valeur des arguments restants:False

-NoEnumerate

Spécifie que la sortie n’est pas énumérée.

La définition de ce paramètre entraîne l’envoi de tableaux en tant qu’objet unique au lieu d’envoyer chaque élément séparément. Cela garantit que JSON peut être aller-retour via ConvertTo-Json.

Propriétés du paramètre

Type:SwitchParameter
Valeur par défaut:False
Prend en charge les caractères génériques:False
DontShow:False

Jeux de paramètres

(All)
Position:Named
Obligatoire:False
Valeur du pipeline:False
Valeur du pipeline par nom de propriété:False
Valeur des arguments restants:False

CommonParameters

Cette applet de commande prend en charge les paramètres courants : -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction et -WarningVariable. Pour plus d’informations, consultez about_CommonParameters.

Entrées

String

Vous pouvez diriger une chaîne JSON vers ConvertFrom-Json.

Sorties

PSCustomObject

OrderedHashtable

Notes

Cette applet de commande est implémentée à l’aide de Newtonsoft Json.NET.

À compter de PowerShell 6, ConvertTo-Json tente de convertir des chaînes mises en forme comme horodatages en valeurs DateTime .

PowerShell 7.5 a ajouté le paramètre DateKind , ce qui vous permet de contrôler la conversion de la chaîne d’horodatage. Le paramètre accepte les valeurs suivantes :

  • Default - Convertit l’horodatage en une [datetime] instance en fonction des règles suivantes :
    • S’il n’existe aucune information de fuseau horaire dans la chaîne d’entrée, le sérialiseur Json.NET convertit la valeur en tant que valeur de temps non spécifiée.
    • Si les informations de fuseau horaire sont un Z fin, le sérialiseur Json.NET convertit l’horodatage en valeur UTC.
    • Si l’horodatage inclut un décalage UTC tel que +02:00, le décalage est converti en fuseau horaire configuré de l’appelant. La mise en forme de sortie par défaut n’indique pas le décalage de fuseau horaire d’origine.
  • Local - Convertit l’horodatage en instance [datetime] dans l’heure locale . Si l’horodatage inclut un décalage UTC, le décalage est converti en fuseau horaire configuré de l’appelant. La mise en forme de sortie par défaut n’indique pas le décalage de fuseau horaire d’origine.
  • Utc - Convertit la valeur en instance [datetime] en heure UTC.
  • Offset - Convertit l’horodatage en une [DateTimeOffset] instance avec le décalage de fuseau horaire de la chaîne d’origine conservée dans cette instance. Si la chaîne brute ne contenait pas de décalage de fuseau horaire, la valeur DateTimeOffset sera spécifiée dans le fuseau horaire local.
  • String - Conserve la valeur de l’instance [string] . Cela garantit que toute logique d’analyse personnalisée peut être appliquée à la valeur de chaîne brute.

Le type PSObject conserve l’ordre des propriétés comme indiqué dans la chaîne JSON. À compter de PowerShell 7.3, le paramètre AsHashtable crée une table OrderedHashtable. Les paires clé-valeur sont ajoutées dans l’ordre présenté dans la chaîne JSON. OrderHashtable conserve cet ordre.