Condividi tramite

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.

L'espressione di un modello non può superare i 24.576 caratteri.

Vincoli in fase di compilazione

Le espressioni modello vengono valutate in fase di esecuzione, ma alcune proprietà nei modelli arm devono essere note in fase di compilazione e pertanto non possono usare espressioni. Queste proprietà devono essere specificate come stringhe letterali, in modo che il motore di distribuzione e il compilatore possano convalidare gli schemi delle risorse, le dipendenze e le proprietà supportate prima della valutazione di qualsiasi espressione.

Le proprietà che devono essere valori letterali in fase di compilazione includono:

  • Il type e il apiVersion di una risorsa.
  • Oggetto name delle variabili, dei parametri e degli output.
  • Riferimenti alle estensioni software.

Il modello ARM seguente non è riuscito perché la proprietà type della risorsa utilizza un'espressione.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storageAccountName": {
      "type": "string",
      "defaultValue": "[format('storage{0}', uniqueString(resourceGroup().id))]"
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    },
    "resourceProvider": {
      "type": "string",
      "defaultValue": "Microsoft.Storage"
    },
    "resourceType": {
      "type": "string",
      "defaultValue": "storageAccounts"
    }
  },
  "resources": [
    {
      "type": "[format('{0}/{1}', parameters('resourceProvider'), parameters('resourceType'))]",
      "apiVersion": "2025-06-01",
      "name": "[parameters('storageAccountName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "StorageV2"
    }
  ]
}

Usare le funzioni

Azure Resource Manager offre funzioni che è possibile usare in un modello. L'esempio seguente mostra 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 fornite da Resource Manager per l'uso all'interno di un modello. In questo caso, si tratta della 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 dalla funzione.

Le funzioni del modello e i relativi parametri non hanno la distinzione tra maiuscole e minuscole. Resource Manager, ad esempio, risolve variables('var1') e VARIABLES('VAR1') come se fossero la stessa cosa. Durante la valutazione, la funzione mantiene invariato l'uso delle maiuscole/minuscole, a meno che queste non vengano modificate espressamente dalla funzione (ad esempio toUpper o toLower). Alcuni tipi di risorse possono avere requisiti per i casi separati dalla modalità di valutazione delle funzioni.

Usare virgolette singole per passare un valore stringa come parametro a una funzione.

"name": "[concat('storage', uniqueString(resourceGroup().id))]"

La maggior parte delle funzioni funziona allo stesso modo se vengono distribuite in un gruppo di risorse, una sottoscrizione, un gruppo di gestione o un tenant. Le funzioni seguenti presentano 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 una sottoscrizione.

Caratteri di escape

Per avere una stringa letterale iniziare con una parentesi quadra sinistra [ e terminare con una parentesi quadra destra ], ma non è stata interpretata come un'espressione, aggiungere una parentesi quadra aggiuntiva per iniziare la stringa con [[. Ad esempio, la variabile:

"demoVar1": "[[test value]"

Risoluzione [test value].

Tuttavia, se la stringa letterale non termina con una parentesi, non eseguire l'escape della prima parentesi. Ad esempio, la variabile:

"demoVar2": "[test] value"

Risoluzione [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 delle virgolette singole in un output dell'espressione ARM, raddoppiare le virgolette singole. L'output del modello seguente restituisce il valore JSON {"abc":"'quoted'"}.

{
  "$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 escape doppio all'interno di un'espressione. Il scriptOutput dal seguente modello è 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": "2023-08-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 non è 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": "2023-08-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 da dove è specificato il valore del parametro. Se si imposta un valore predefinito nel modello, è necessaria la parentesi quadra 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 riporta [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]. Usare invece:

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 riporta [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, i modelli di Resource Manager lo considerano come se la proprietà non fosse 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

  • Last updated on