How to use shorthand syntax with Azure CLI
Many Azure CLI parameters accept JSON values, but because it can be challenging to flatten JSON into a string, the Azure CLI supports shorthand syntax. Shorthand syntax is a simplified representation of a JSON string.
This article provides examples of shorthand syntax, and shows how to pass JSON as a file.
Note
You'll know that a parameter accepts shorthand syntax when the parameter description reads similar to Support shorthand-syntax, JSON-file and YAML-file. Try "??" to show more.
Full value shorthand syntax
Shorthand syntax in Full Value format is JSON surrounded by double quotes. Double quotes cause the JSON value to be passed as a string in both the PowerShell and Bash scripting language. Here's a JSON example:
{
"name": "Bill",
"age": 20,
"paid": true,
"emails": [
"Bill@microsoft.com",
"Bill@outlook.com"
],
"address": {
"country": "USA",
"company": "Microsoft",
"details": {
"line1": "15590 NE 31st St",
"line2": "Redmond, WA"
}
}
}
When you pass JSON in a parameter value, the JSON is flattened and wrapped in double quotes.
az some-command --contact "{name:Bill,age:20,paid:true,emails:[Bill@microsoft.com,Bill@outlook.com],address:{country:USA,company:Microsoft,details:{line1:'15590 NE 31st St',line2:'Redmond, WA'}}}"
Partial value shorthand syntax
Shorthand syntax for partial value is composed of two parts joined by an equal (=) sign between the index key and the value.
Here's an example: key=value.
The value can be a simplified string, full value format, JSON, or a JSON file path. Using the JSON example provided, pass properties for the --contact parameter following these examples:
Use Partial Value for a single key-value pair.
az some-command --contact name=Bill
Use Partial Value for two key-value pairs. Note the space that separates the two pairs.
az some-command --contact age=20 paid=true
Use Partial Value for second element.
az some-command --contact emails[1]="Bill@outlook.com"
Use Partial Value for details property of address.
az some-command --contact address.details="{line1:'15590 NE 31st St',line2:'Redmond, WA'}"
Combine full and partial value shorthand syntax
You can combine full and partial value syntax, but always start with Full Value followed by Partial Value. If you reverse the order, the final data only contains the Full Value without properties defined in Partial Value.
Use Full Value followed by Partial Value:
az some-command --contact "{name:Bill,age:20,paid:true,emails:[Bill@microsoft.com,Bill@outlook.com]}" motto="One man's bug is another man's lesson."
You can also patch a new element of list property in Full Value. For example you can set the second email address by Partial Value:
az some-command --contact "{name:Bill,age:20,paid:true,emails:[Bill@microsoft.com]}" emails[1]="Bill@outlook.com" motto="One man's bug is another man's lesson."
Pass JSON in a file
It's also possible to pass a JSON file as a parameter value. This is the recommended approach when working with complex JSON.
az some-command --contact address.details=./address_details.JSON
Single Quotes String
Single Quotes String is used to pass a string value with special characters: :, ,, {, }, [, ], null, ??, and space.
These characters often have other meanings when parsing shorthand syntax. Single quotes tell the parser to treat everything as a string.
Pass a string value with a space and other special characters
Here's example JSON to pass as a value in the --contact parameter:
{
"name": "Bill RP",
"age": 20,
"paid": true,
"data": "{a: [1, 2]}"
}
Use single quotes in Full Value format:
az some-command --contact "{name:'Bill RP',age:20,paid:true,data:'{a: [1, 2]}'}"
Use single quotes in Partial Value format:
az some-command --contact name="'Bill RP'" data="'{a: [1, 2]}'"
In the next example, it's also possible to remove single quotes for the name key. The parser doesn't distinguish between a Full Value expression, null value, or the ?? flag.
Use Partial Value format:
az some-command --contact name="Bill RP"
Work with apostrophes
The apostrophe character (') needs special escape (/') in Single Quotes String in order to distinguish the end of a Single Quotes String. A forward slash (/) is an escape character only after an apostrophe (') in Single Quotes String. If / isn't in Single Quotes String or / isn't after ', / is a normal character.
Pass Full Value format:
az some-command --contact "{name:'bill'/s',age:20,paid:true}"
Pass Partial Value format:
az some-command --contact name="'bill'/s'"
If value isn't in Single Quotes String, you don't need to add an escape character after '.
Pass Partial Value format:
az some-command --contact name="bill's"
Here's another example using the following JSON:
{
"name": "Bill",
"motto": "One man's bug is another man's lesson.",
"age": 20,
"paid": true,
"emails": [
"Bill@microsoft.com",
"Bill@outlook.com"
]
}
In Full Value format, use a Single Quotes String and replace the ' with '/.
az some-command --contact "{name:Bill,motto:'One man'/s bug is another man'/s lesson.',age:20,paid:true,emails:[Bill@microsoft.com,Bill@outlook.com]}"
In Partial Value format, a value containing an apostrophe can be parsed as string, surrounded by double quotes.
az some-command --contact motto="One man's bug is another man's lesson."
Work with NULL values
Pass the word "null" as a string value
Sometime you need to pass a "null" string value. In order to distinguish with null value, it needs to be a Single Quotes String.
For example if you want to pass "null" string into the name property in the --contact parameter:
JSON:
{
"name": "null",
"age": 20,
"paid": true
}
Use Full Value format:
az some-command --contact "{name:'null',age:20,paid:true}"
Use Partial Value format:
az some-command --contact name="'null'"
Pass a null value
Shorthand syntax support null keyword in both Full Value and Partial Value formats.
For example if you want to pass following object with a null value address property in the --contact parameter:
{
"name": "Bill",
"age": 20,
"paid": true,
"emails": [
"Bill@microsoft.com",
"Bill@outlook.com"
],
"address": null
}
Use Full Value format:
az some-command --contact "{name:Bill,age:20,paid:true,emails:[Bill@microsoft.com,Bill@outlook.com],address:null}"
Use Partial Value format:
az some-command --contact name=Bill address=null
Use a null value in update commands
In update commands, a null value is often used to unset properties of an object, or remove elements of an array or a dictionary.
{
"contact": {
"name": "Bill",
"age": 20,
"paid": true,
"emails": [
"Bill@microsoft.com",
"Bill@outlook.com"
],
"address": {
"country": "USA",
"company": "Microsoft",
"details": {
"line1": "15590 NE 31st St",
"line2": "Redmond, WA"
}
}
},
"other_properties": {}
}
If there already exists a resource with the JSON values shown above, passing a null value in an update command resets the key's value.
az some-update-command --contact address=null
Here's another example that removes the first element of a resource's email:
az some-update-command --emails [0]=null
Use ?? to show help
The use of double question marks ?? is a special keyword to show the available help for a parameter or subproperty. It can also be used within shorthand syntax to get help.
Note
The Bash shell uses ? as a wildcard. Make sure the double question marks ?? are wrapped in the double quotes.
Use ?? to show a parameter's help message
Show help message of --contact parameter:
az some-command --contact "??"
Use ?? in Full Value format
Show help message of --contant parameter when writing Full Value:
az some-command --contact "{??"
az some-command --contact "{name:Bill,??"
Show help message of --contant.address property when writing Full Value:
az some-command --contact "{name:Bill,address:??"
Show help message of --contant.address.country property when writing Full Value:
az some-command --contact "{name:Bill,address:{country:??"
Show help message of --contant.emails property when writing Full Value:
az some-command --contact "{name:Bill,address:{country:USA},emails:??"
Show help message of the element of --contant.emails property when writing Full Value:
az some-command --contact "{name:Bill,address:{country:USA},emails:[??"
Use ?? in Partial Value format
Show help message of --contant.address property when writing Partial Value:
az some-command --contact address="??"
Show help message of --contant.emails property when writing Partial Value:
az some-command --contact emails="??"
Show help message of the element of --contant.emails property when writing Partial Value:
az some-command --contact emails[0]="??"
