TL/DR: The Azure CLI can be used to query data from Azure. For more information on how to use the Azure CLI query functionality, see the Azure CLI Query documentation.
The Azure CLI can be used to not only create, configure, and delete resources from Azure but to also query data from Azure. To do so, the Azure CLI uses the --query argument to run a JMESPath query against your Azure subscriptions. Querying Azure for resource properties can be quite helpful when writing scripts using the Azure CLI. For instance, you may want to get the IP address of an Azure Virtual Machine or Container Instance in order to perform some action on that resource.
This article includes a quick exercise that demonstrates several concepts with a final goal being to query a single resource property and storing the value of that property in a variable. This is demonstrated using Azure Container Instances (ACI). You do not need to have experience with ACI to complete the steps in this article, the concepts transfer to any Azure resource.
For quick access to the Azure CLI consider using the Azure Cloud Shell.
Create three Container Instances
Before digging into query syntax and operations, create a resource group using the az group create command and three container instances using the az container create command. The following bash script can be used to complete this.
# Create Resource Group
az group create --name myResourceGroup --location eastus
# Create three container instances
for ((i=0; i<3; ++i)); do az container create --resource-group myResourceGroup --name mycontainer$i --image microsoft/aci-helloworld --ip-address public; done
Before talking about the query command, lets discuss output format. By default, when any command is run using the Azure CLI, the output is returned JSON formatted. For example, run the az container list command. You should see that a JSON document is returned with the details of all container instances in your subscription.
$ az container list
While the JSON output is verbose, which is great, we may want to format the output a little more elegantly. We can do so by changing the output format. This article will focus on table and tsv format. For a complete list of Azure CLI output formats and a explanation of each, see Output format for Azure CLI commands.
Change the output type using the --output argument. In the following example the output type of table is used. You can see that while the output is not quite as verbose, it is easier to parse.
$ az container list --output table
Name ResourceGroup Status Image IP:ports Network CPU/Memory OsType Location
------------ --------------- --------- ------------------------ ----------------- --------- --------------- -------- ----------
mycontainer0 myResourceGroup Succeeded microsoft/aci-helloworld 20.42.27.240:80 Public 1.0 core/1.5 gb Linux eastus
mycontainer1 myResourceGroup Succeeded microsoft/aci-helloworld 104.45.170.149:80 Public 1.0 core/1.5 gb Linux eastus
mycontainer2 myResourceGroup Succeeded microsoft/aci-helloworld 52.188.216.148:80 Public 1.0 core/1.5 gb Linux eastus
You can change the default output format for the CLI with the az configure command.
Azure CLI query
To start, lets return a single property of a single container instance using the az container show command. In the following example notice that the --query argument is called and that the name property is specified.
$ az container show -n mycontainer0 -g myResourceGroup --query name --output table
Result
------------
mycontainer0
This works great when returning a single result. If however we want to pull the names of all container instances using the az container list command, we need to use the JAMESPath flatten operator [ ]. In this example note that the az container list command is using [].name for the query value, which returns the names of all container instances.
$ az container list --query [].name --output table
Result
------------
mycontainer0
mycontainer1
mycontainer2
If you wanted to return multiple properties, each of these can be comma delimited in square brackets.
$ az container list --query [].[name,location] --output table
Column1 Column2
------------ ---------
mycontainer0 eastus
mycontainer1 eastus
mycontainer2 eastus
To customize the column name we need to return a dictionary vs. an array using a JAMESPath multiSelect hash operator{ }. Returning a dictionary allows the property key to be set as the column label.
To achieve this, wrap the property selection in curly braces and name each property such as KeyValue:PropertyName. In the following example the key values are Name and Location.
$ az container list --query "[].{Name:name,Location:location}" --output table
Name Location
------------ ----------
mycontainer0 eastus
mycontainer1 eastus
mycontainer2 eastus
Return value by index
Now let's say that you want to grab a specific object from an array by its index in that array. This can be done by specifying the index number in the square brackets. This can be helpful when looping through an array and performing an action on specific objects in that array. In the following example, the object at index 2 is returned.
$ az container list --query [2].name --output table
Result
------------
mycontainer2
You can also return a slice of indexes. In this example object 0 until 2 are returned. In this case 0 and 1 are returned.
$ az container list --query [0:2].name --output table
Result
------------
mycontainer0
mycontainer1
Filter results on a value
In many cases we want to filter an array based on a value. This can be done using a JMESPath filter expression. In the following example only the container instances with a name containing mycontainer2 is returned.
$ az container list --query "[?contains(name, 'mycontainer2')]" --output table
Name Location ProvisioningState RestartPolicy OsType ResourceGroup
------------ ---------- ------------------- --------------- -------- ---------------
mycontainer2 eastus Succeeded Always Linux myResourceGroup
Store single property in a variable
Now let's put some of these concepts in play and find a specific container instances IP address and place that IP address into a variable.
We will start by returning the IP address of a container instance with the name mycontainer2.
$ az container list --query "[?contains(name, 'mycontainer2')].[ipAddress.ip]" --output table
Column1
--------------
52.188.216.148
However we only want the IP address and do not need the table formatting nor header. Instead of using table output, use tabbed separated values, or tsv. This returns only the IP address.
$ az container list --query "[?contains(name, 'mycontainer2')].[ipAddress.ip]" --output tsv
52.188.216.148
Now update the command to place the results into a variable. The following example works in bash.
$ ip=$(az container list --query "[?contains(name, 'mycontainer2')].[ipAddress.ip]" --output tsv)
If using PowerShell, the command would look similar to this.
PS $ip = $(az container list --query "[?contains(name, 'mycontainer2')].[ipAddress.ip]" --output tsv)
At this point, if we were writing a script to say perform some action against the container instance, we could reference this variable when needing the IP address of the container instance.
