JSON is a way of structuring data that makes it easy for software to consume. When working with PowerShell, Microsoft has provided some helpful tools to work with JSON called the ConvertTo-Json and ConvertFrom-Json commands.
As the world continually becomes "eaten by software" more and more services are being replaced by software. IT pros have most likely seen this in the form of software-defined everything. One of the premier components of this focus on software and with the continuing adoption of DevOps is application programming interfaces (APIs). All of these services needs to talk together and must provide a way for programs and users to interact with them. This is where APIs come in handy. But, what does this have to do with PowerShell and JSON, you ask?
APIs, more specifically REST APIs, return data when queried. This data is typically in the JSON format. JSON is a way of structuring data that makes it easy for software to consume. When working with PowerShell, Microsoft has provided some helpful tools to work with JSON called the ConvertTo-Json and ConvertFrom-Json commands. These commands allow you to quickly work with REST APIs or any other service that returns or accepts JSON as an input.
How these two commands can be used to work with JSON.
Let's first start out with a simple piece of JSON to work with. We'll pretend that this might have been returned from a REST API or some other service.
{"employees":[
{"firstName":"John", "lastName":"Doe"},
{"firstName":"Anna", "lastName":"Smith"},
{"firstName":"Peter", "lastName":"Jones"}
]}
This example shows an employees object with an array of three employees inside. Let's now assign this to a string variable in PowerShell.
$employees = '{"employees":[
{"firstName":"John", "lastName":"Doe"},
{"firstName":"Anna", "lastName":"Smith"},
{"firstName":"Peter", "lastName":"Jones"}
]}'
If just reading this as a string there's not much we can do with it.
There's no way to pull out specific employees without doing a lot of string manipulation which can get ugly quick. Instead, we need to get this piece of JSON data into a structured object. After all, objects are what make PowerShell great. To do that, we can use the ConvertFrom-Json command and pass $employees to it.
Now you can see that this is an object that can more easily be parsed. At this point, we perform tasks on each employee like checking for an Active Directory perhaps.
$employeesObj.employees | foreach { $emp = $_; Get-AdUser -Filter "(givenName -eq '$($emp.firstName)') -and (surName -eq '$($emp.lastName)')" }
ConvertFrom-Json
The ConvertFrom-Json command is an excellent way to convert any piece of JSON directly into a manageable PowerShell object. But we can also go the other way as well. What if you have an object that you'd like to send to a REST API or some other service that requires the data be in JSON. We can use the ConvertTo-Json command.
To use the ConvertTo-Json command. This does the exact opposite of ConvertFrom-Json. This command takes an object and converts it back into that JSON string we started with. Although, in this form, it's not possible to work with it in PowerShell, but that's not really the point. This command is typically used when the JSON is done being manipulated and is ready to be sent in pure JSON.
Below you can see that by piping our object to the ConvertTo-Json command, that it reads the object and returns the exact same JSON string that was provided in the first place.
The ConvertTo-Json and ConvertFrom-Json commands will probably be the only commands necessary to work with JSON on PowerShell. There are some more advanced scenarios that you might find in but, in that case, begin exploring each commands various parameters as we just used a single parameter in our examples above called InputObject.