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 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