Sintassi ed espressioni nei modelli di Resource Manager
La sintassi di base del modello di Azure Resource Manager (modello ARM) è JavaScript Object Notation (JSON). È tuttavia possibile usare espressioni per estendere i valori JSON disponibili all'interno del modello. Le espressioni iniziano e terminano con parentesi quadre: [
e ]
rispettivamente. Il valore dell'espressione viene valutato quando viene distribuito il modello. Un'espressione può restituire una stringa, un intero, un valore booleano, una matrice o un oggetto.
Un'espressione modello non può superare i 24.576 caratteri.
Usare le funzioni
Azure Resource Manager fornisce funzioni che è possibile usare in un modello. Nell'esempio seguente viene illustrata un'espressione che usa una funzione nel valore predefinito di un parametro:
"parameters": {
"location": {
"type": "string",
"defaultValue": "[resourceGroup().location]"
}
},
All'interno dell'espressione, la sintassi resourceGroup()
chiama una delle funzioni che Resource Manager fornisce per l'uso all'interno di un modello. In questo caso, è la funzione resourceGroup . Proprio come in JavaScript, le chiamate di funzione sono formattate come functionName(arg1,arg2,arg3)
. La sintassi .location
recupera una proprietà dall'oggetto restituito da tale funzione.
Le funzioni del modello e i relativi parametri non hanno la distinzione tra maiuscole e minuscole. Ad esempio, Resource Manager risolve variables('var1')
e VARIABLES('VAR1')
come lo stesso. Se valutata, a meno che la funzione non modifichi esplicitamente il caso (ad esempio toUpper
o toLower
), la funzione mantiene il caso. Alcuni tipi di risorse possono avere requisiti di caso separati dal modo in cui vengono valutate le funzioni.
Per passare un valore stringa come parametro a una funzione, usare virgolette singole.
"name": "[concat('storage', uniqueString(resourceGroup().id))]"
La maggior parte delle funzioni funziona esattamente se vengono distribuite in un gruppo di risorse, una sottoscrizione, un gruppo di gestione o un tenant. Le funzioni seguenti hanno restrizioni in base all'ambito:
- resourceGroup : può essere usato solo nelle distribuzioni in un gruppo di risorse.
- resourceId : può essere usato in qualsiasi ambito, ma i parametri validi cambiano a seconda dell'ambito.
- sottoscrizione : può essere usata solo nelle distribuzioni in un gruppo di risorse o in una sottoscrizione.
Caratteri di escape
Per avere una stringa letterale iniziare con una parentesi quadre sinistra e terminare con una parentesi quadre [
destra, ma non è stata interpretata come espressione, aggiungere una parentesi quadre aggiuntiva per avviare la stringa con [[
.]
Ad esempio, la variabile:
"demoVar1": "[[test value]"
Risolve in [test value]
.
Tuttavia, se la stringa letterale non termina con una parentesi quadre, non uscire dalla prima parentesi quadre. Ad esempio, la variabile:
"demoVar2": "[test] value"
Risolve in [test] value
.
Per eseguire l'escape delle virgolette doppie in un'espressione, ad esempio l'aggiunta di un oggetto JSON nel modello, usare la barra rovesciata.
"tags": {
"CostCenter": "{\"Dept\":\"Finance\",\"Environment\":\"Production\"}"
},
Per eseguire l'escape di virgolette singole in un output dell'espressione ARM, raddoppiare le virgolette singole. L'output del modello seguente restituisce il valore {"abc":"'quoted'"}
JSON .
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {},
"resources": [],
"outputs": {
"foo": {
"type": "object",
"value": "[createObject('abc', '''quoted''')]"
}
}
}
Nella definizione della risorsa, i valori di double-escape all'interno di un'espressione. Il scriptOutput
modello seguente è de'f
.
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"forceUpdateTag": {
"type": "string",
"defaultValue": "[newGuid()]"
}
},
"variables": {
"deploymentScriptSharedProperties": {
"forceUpdateTag": "[parameters('forceUpdateTag')]",
"azPowerShellVersion": "10.1",
"retentionInterval": "P1D"
}
},
"resources": [
{
"type": "Microsoft.Resources/deploymentScripts",
"apiVersion": "2020-10-01",
"name": "escapingTest",
"location": "[resourceGroup().location]",
"kind": "AzurePowerShell",
"properties": "[union(variables('deploymentScriptSharedProperties'), createObject('scriptContent', '$DeploymentScriptOutputs = @{}; $DeploymentScriptOutputs.escaped = \"de''''f\";'))]"
}
],
"outputs": {
"scriptOutput": {
"type": "string",
"value": "[reference('escapingTest').outputs.escaped]"
}
}
}
Con languageVersion 2.0, l'escape doppio è più necessario. L'esempio precedente può essere scritto come JSON seguente per ottenere lo stesso risultato, de'f
.
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"languageVersion": "2.0",
"contentVersion": "1.0.0.0",
"parameters": {
"forceUpdateTag": {
"type": "string",
"defaultValue": "[newGuid()]"
}
},
"variables": {
"deploymentScriptSharedProperties": {
"forceUpdateTag": "[parameters('forceUpdateTag')]",
"azPowerShellVersion": "10.1",
"retentionInterval": "P1D"
}
},
"resources": {
"escapingTest": {
"type": "Microsoft.Resources/deploymentScripts",
"apiVersion": "2020-10-01",
"name": "escapingTest",
"location": "[resourceGroup().location]",
"kind": "AzurePowerShell",
"properties": "[union(variables('deploymentScriptSharedProperties'), createObject('scriptContent', '$DeploymentScriptOutputs = @{}; $DeploymentScriptOutputs.escaped = \"de''f\";'))]"
}
},
"outputs": {
"scriptOutput": {
"type": "string",
"value": "[reference('escapingTest').outputs.escaped]"
}
}
}
Quando si passano i valori dei parametri, l'uso dei caratteri di escape dipende dalla posizione in cui viene specificato il valore del parametro. Se si imposta un valore predefinito nel modello, è necessaria la parentesi sinistra aggiuntiva.
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"demoParam1": {
"type": "string",
"defaultValue": "[[test value]"
}
},
"resources": [],
"outputs": {
"exampleOutput": {
"type": "string",
"value": "[parameters('demoParam1')]"
}
}
}
Se si usa il valore predefinito, il modello restituisce [test value]
.
Tuttavia, se si passa un valore di parametro tramite la riga di comando, i caratteri vengono interpretati letteralmente. Distribuzione del modello precedente con:
New-AzResourceGroupDeployment -ResourceGroupName demoGroup -TemplateFile azuredeploy.json -demoParam1 "[[test value]"
Restituisce [[test value]
. In alternativa:
New-AzResourceGroupDeployment -ResourceGroupName demoGroup -TemplateFile azuredeploy.json -demoParam1 "[test value]"
La stessa formattazione si applica quando si passano valori da un file di parametri. I caratteri vengono interpretati letteralmente. Se usato con il modello precedente, il file di parametri seguente restituisce [test value]
:
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"demoParam1": {
"value": "[test value]"
}
}
}
Valori Null
Per impostare una proprietà su Null, è possibile usare null
o [json('null')]
. La funzione json restituisce un oggetto vuoto quando si specifica null
come parametro. In entrambi i casi, Resource Manager modelli lo considerano come se la proprietà non sia presente.
"stringValue": null,
"objectValue": "[json('null')]"
Per rimuovere completamente un elemento, è possibile usare la funzione filter(). Ad esempio:
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"deployCaboodle": {
"type": "bool",
"defaultValue": false
}
},
"variables": {
"op": [
{
"name": "ODB"
},
{
"name": "ODBRPT"
},
{
"name": "Caboodle"
}
]
},
"resources": [],
"outputs": {
"backendAddressPools": {
"type": "array",
"value": "[if(parameters('deployCaboodle'), variables('op'), filter(variables('op'), lambda('on', not(equals(lambdaVariables('on').name, 'Caboodle')))))]"
}
}
}
Passaggi successivi
- Per l'elenco completo delle funzioni modello, vedere Funzioni modello di Resource Manager.
- Per altre informazioni sui file di modello, vedere Comprendere la struttura e la sintassi dei modelli di Resource Manager.