Syntaxe et expressions dans les modèles ARM

  • Article

La syntaxe de base du modèle Azure Resource Manager (modèle ARM) respecte le format JavaScript Object Notation (JSON). Toutefois, vous pouvez utiliser des expressions et fonctions pour étendre les valeurs JSON disponibles dans le modèle. Les expressions commencent et se terminent avec des crochets : [ et ], respectivement. La valeur de l’expression est évaluée lorsque le modèle est déployé. Une expression peut retourner une chaîne, un entier, un booléen, un tableau ou un objet.

Une expression de modèle ne peut pas dépasser 24 576 caractères.

Utiliser les fonctions

Azure Resource Manager fournit des fonctions que vous pouvez utiliser dans un modèle. L’exemple suivant montre une expression qui utilise une fonction dans la valeur par défaut d’un paramètre :

"parameters": {
  "location": {
    "type": "string",
    "defaultValue": "[resourceGroup().location]"
  }
},

Dans l’expression, la syntaxe resourceGroup() appelle une des fonctions fournies par Resource Manager pour une utilisation dans un modèle. Dans ce cas, il s’agit de la fonction resourceGroup. Comme en JavaScript, les appels de fonction sont formatés comme suit : functionName(arg1,arg2,arg3). La syntaxe .location récupère une propriété de l’objet retourné par cette fonction.

Les fonctions des modèles et leurs paramètres ne respectent pas la casse. Par exemple, Azure Resource Manager résout variables('var1') et VARIABLES('VAR1') comme étant identiques. Lors de l’évaluation, la fonction préserve la casse sauf si elle la modifie expressément (toUpper ou toLower, par exemple). Certains types de ressources peuvent avoir des exigences de casse indépendantes de la façon dont les fonctions sont évaluées.

Pour passer une valeur de chaîne en tant que paramètre à une fonction, utilisez des guillemets simples.

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

La plupart des fonctions opèrent de la même façon, qu’elles soient déployées sur un groupe de ressources, un abonnement, un groupe d’administration ou un locataire. Les fonctions suivantes présentent des restrictions en fonction de l’étendue :

  • resourceGroup - peut être utilisée uniquement dans les déploiements sur un groupe de ressources.
  • resourceId - peut être utilisée dans n’importe quelle étendue, mais les paramètres valides changent en fonction de l’étendue.
  • subscription - peut être utilisée uniquement dans les déploiements sur un groupe de ressources ou un abonnement.

Caractères d'échappement

Pour avoir une chaîne littérale qui commence par un crochet gauche [ et se termine par un crochet droit ], sans qu’elle soit interprétée comme une expression, ajoutez un crochet supplémentaire. La chaîne commence alors par [[. Par exemple, la variable :

"demoVar1": "[[test value]"

Est résolu en [test value].

Toutefois, si la chaîne littérale ne se termine par un crochet, n’utilisez pas le caractère d’échappement pour le premier crochet. Par exemple, la variable :

"demoVar2": "[test] value"

Est résolu en [test] value.

Pour échapper les guillemets doubles dans une expression, comme l’ajout d’un objet JSON dans le modèle, utilisez la barre oblique inverse.

"tags": {
    "CostCenter": "{\"Dept\":\"Finance\",\"Environment\":\"Production\"}"
},

Pour placer en échappement des guillemets simples dans la sortie d’une expression ARM, doublez les guillemets simples. La sortie du modèle suivant produit une valeur 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''')]"
    }
  }
}

Dans la définition de la ressource, des valeurs à double échappement au sein d’une expression. Le scriptOutput à partir du modèle suivant est 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]"
    }
  }
}

Avec languageVersion 2.0, le double échappement n’est plus nécessaire. L’exemple précédent peut être écrit comme le json suivant afin d’obtenir le même résultat 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]"
    }
  }
}

Quand il s’agit de transmettre des valeurs de paramètres, l’utilisation de caractères d’échappement dépend de l’endroit où sont spécifiées ces valeurs. Si vous définissez une valeur par défaut dans le modèle, vous avez besoin du crochet gauche supplémentaire.

{
  "$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')]"
    }
  }
}

Si vous utilisez la valeur par défaut, le modèle retourne [test value].

Cependant, si vous transmettez une valeur de paramètre via la ligne de commande, les caractères sont interprétés littéralement. Le fait de déployer le modèle précédent avec :

New-AzResourceGroupDeployment -ResourceGroupName demoGroup -TemplateFile azuredeploy.json -demoParam1 "[[test value]"

Retourne [[test value]. Utilisez à la place :

New-AzResourceGroupDeployment -ResourceGroupName demoGroup -TemplateFile azuredeploy.json -demoParam1 "[test value]"

La même mise en forme s’applique quand il s’agit de transmettre des valeurs à partir d’un fichier de paramètres. Les caractères sont interprétés littéralement. Quand il est utilisé avec le modèle précédent, le fichier de paramètres suivant retourne [test value] :

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "demoParam1": {
      "value": "[test value]"
    }
  }
}

Valeurs Null

Pour affecter la valeur Null à une propriété, vous pouvez utiliser null ou [json('null')]. La fonction json retourne un objet vide quand vous fournissez null comme paramètre. Dans les deux cas, les modèles Resource Manager font comme si la propriété n’était pas présente.

"stringValue": null,
"objectValue": "[json('null')]"

Pour supprimer totalement un élément, vous pouvez utiliser la fonction filter(). Par exemple :

{
  "$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')))))]"
    }
  }
}

Étapes suivantes