Sintassi ed espressioni nei modelli di Resource Manager

  • Articolo

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 24.576 caratteri.

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 e toLower. Alcuni tipi di risorse possono avere requisiti per i casi separati dalla modalità di valutazione delle 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 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]"

Risolve in [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"

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 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 del 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ù lungo 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 è 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 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, 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