Paramètres dans les modèles ARM

  • Article

Cet article explique comment définir et utiliser des paramètres dans un modèle Azure Resource Manager (ARM). En fournissant des valeurs différentes pour les paramètres, vous pouvez réutiliser un modèle pour différents environnements.

Resource Manager résout les valeurs des paramètres avant de démarrer les opérations de déploiement. Chaque fois que le paramètre est utilisé dans le modèle, Resource Manager le remplace par la valeur résolue.

Chaque paramètre doit être défini sur l’un des types de données.

Outre minValue, maxValue, minLength, maxLength et allowedValues, languageVersion 2.0 introduit certaines contraintes de validation de type d’agrégation à utiliser dans les définitions, les paramètres et les définitions de sorties . Ces contraintes sont les suivantes :

Notes

La version actuelle de l’extension Azure Resource Manager Tools pour Visual Studio Code ne reconnaît pas les améliorations apportées à languageVersion 2.0.

Conseil

Nous recommandons Bicep parce qu’il offre les mêmes fonctionnalités que les modèles ARM et que la syntaxe est plus facile d’utilisation. Pour en savoir plus, consultez Paramètres.

Vous êtes limité à 256 paramètres dans un modèle. Pour plus d’informations, consultez Limites du modèle.

Pour connaître les meilleures pratiques relatives aux paramètres, consultez Paramètres.

Déclaration minimale

Au minimum, chaque paramètre a besoin d’un nom et d’un type.

Lorsque vous déployez un modèle via le portail Azure, les noms de paramètres en casse mixte sont convertis en noms séparés par des espaces. Par exemple, demoString dans l’exemple suivant est représenté sous la forme Demo String. Pour plus d’informations, consultez Utiliser un bouton de déploiement pour déployer des modèles à partir du référentiel GitHub et Déployer des ressources avec des modèles ARM et le portail Azure.

"parameters": {
  "demoString": {
    "type": "string"
  },
  "demoInt": {
    "type": "int"
  },
  "demoBool": {
    "type": "bool"
  },
  "demoObject": {
    "type": "object"
  },
  "demoArray": {
    "type": "array"
  }
}

Paramètres sécurisés

Vous pouvez marquer les paramètres de chaîne ou d’objet comme sécurisés. La valeur d’un paramètre sécurisé n’est pas enregistrée dans l’historique de déploiement et n’est pas journalisée.

"parameters": {
  "demoPassword": {
    "type": "secureString"
  },
  "demoSecretObject": {
    "type": "secureObject"
  }
}

Valeurs autorisées

Vous pouvez définir des valeurs autorisées pour un paramètre. Vous fournissez les valeurs autorisées dans un tableau. Le déploiement échoue pendant la validation si une valeur transmise pour le paramètre n’est pas l’une des valeurs autorisées.

"parameters": {
  "demoEnum": {
    "type": "string",
    "allowedValues": [
      "one",
      "two"
    ]
  }
}

Valeur par défaut

Vous pouvez spécifier une valeur par défaut pour un paramètre. La valeur par défaut est utilisée quand aucune valeur n’est fournie pendant le déploiement.

"parameters": {
  "demoParam": {
    "type": "string",
    "defaultValue": "Contoso"
  }
}

Pour spécifier une valeur par défaut ainsi que d’autres propriétés pour le paramètre, utilisez la syntaxe suivante.

"parameters": {
  "demoParam": {
    "type": "string",
    "defaultValue": "Contoso",
    "allowedValues": [
      "Contoso",
      "Fabrikam"
    ]
  }
}

Vous pouvez utiliser des expressions avec la valeur par défaut. Vous ne pouvez pas utiliser la fonction reference ni aucune des fonctions list dans la section parameters. Ces fonctions obtiennent l’état d’exécution d’une ressource et ne peuvent pas être exécutées avant le déploiement quand des paramètres sont résolus.

Les expressions ne sont pas autorisées avec d’autres propriétés de paramètre.

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

Vous pouvez utiliser une autre valeur de paramètre pour générer une valeur par défaut. Le modèle suivant construit un nom de plan d’hôte à partir du nom de site.

"parameters": {
  "siteName": {
    "type": "string",
    "defaultValue": "[concat('site', uniqueString(resourceGroup().id))]"
  },
  "hostingPlanName": {
    "type": "string",
    "defaultValue": "[concat(parameters('siteName'),'-plan')]"
  }
}

Contraintes de longueur

Vous pouvez spécifier des longueurs minimale et maximale pour les paramètres de chaîne et de tableau. Vous pouvez définir une contrainte ou les deux. Pour les chaînes, la longueur indique le nombre de caractères. Pour les tableaux, la longueur indique le nombre d’éléments dans le tableau.

L’exemple suivant déclare deux paramètres. Un paramètre est destiné à un nom de compte de stockage qui doit compter entre 3 et 24 caractères. L’autre paramètre est un tableau qui doit compter entre 1 et 5.

"parameters": {
  "storageAccountName": {
    "type": "string",
    "minLength": 3,
    "maxLength": 24
  },
  "appNames": {
    "type": "array",
    "minLength": 1,
    "maxLength": 5
  }
}

Contraintes d’entier

Vous pouvez définir des valeurs minimales et maximales pour les paramètres de type entier. Vous pouvez définir une contrainte ou les deux.

"parameters": {
  "month": {
    "type": "int",
    "minValue": 1,
    "maxValue": 12
  }
}

Contraintes d’objet

Les contraintes d’objet sont uniquement autorisées sur les objets et ne peuvent être utilisées qu’avec languageVersion 2.0.

Propriétés

La valeur de properties est une carte de la propriété name =>type definition.

L’exemple suivant accepte {"foo": "string", "bar": 1}, mais rejette {"foo": "string", "bar": -1}, {"foo": "", "bar": 1}ou tout objet sans foo propriété ou bar .

"parameters": {
  "objectParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3
      },
      "bar": {
        "type": "int",
        "minValue": 0
      }
    }
  }
}

Toutes les propriétés sont requises, sauf si la définition de type de la propriété a la contrainte « nullable » : true . Pour rendre les deux propriétés de l’exemple précédent facultatives, il se présente comme suit :

"parameters": {
  "objectParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3,
        "nullable": true
      },
      "bar": {
        "type": "int",
        "minValue": 0,
        "nullable": true
      }
    }
  }
}

additionalProperties

La valeur de est une additionalPropertiesdéfinition de type ou une valeur booléenne. Si aucune contrainte n’est additionalProperties définie, la valeur par défaut est true.

Si value est une définition de type, la valeur décrit le schéma appliqué à toutes les propriétés non mentionnées dans la properties contrainte. L’exemple suivant accepte {"fizz": "buzz", "foo": "bar"} mais rejette {"property": 1}.

"parameters": {
  "dictionaryParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3,
        "nullable": true
      },
      "bar": {
        "type": "int",
        "minValue": 0,
        "nullable": true
      }
    },
    "additionalProperties": {
      "type": "string"
    }
  }
}

Si la valeur est false, aucune propriété au-delà de celles définies dans la properties contrainte ne peut être fournie. L’exemple suivant accepte {"foo": "string", "bar": 1} mais rejette {"foo": "string", "bar": 1, "fizz": "buzz"}.

"parameters": {
  "dictionaryParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3
      },
      "bar": {
        "type": "int",
        "minValue": 0
      }
    },
    "additionalProperties": false
  }
}

Si la valeur est true, toute propriété non définie dans la contrainteproperties accepte n'importe quelle valeur. L’exemple suivant accepte {"foo": "string", "bar": 1, "fizz": "buzz"}.

"parameters": {
  "dictionaryParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3
      },
      "bar": {
        "type": "int",
        "minValue": 0
      }
    },
    "additionalProperties": true
  }
}

discriminator

La valeur discriminator définit le schéma à appliquer en fonction d’une propriété de discriminateur. L’exemple suivant accepte {"type": "ints", "foo": 1, "bar": 2}ou {"type": "strings", "fizz": "buzz", "pop": "goes", "the": "weasel"}, mais rejette {"type": "ints", "fizz": "buzz"}.

"parameters": {
  "taggedUnionParameter": {
    "type": "object",
    "discriminator": {
      "propertyName": "type",
      "mapping": {
        "ints": {
          "type": "object",
          "additionalProperties": {"type": "int"}
        },
        "strings": {
          "type": "object",
          "additionalProperties": {"type": "string"}
          }
      }
    }
  }
}

Contraintes de tableau

Les contraintes de tableau sont uniquement autorisées sur les tableaux et ne peuvent être utilisées qu’avec languageVersion 2.0.

prefixItems

La valeur de prefixItems est un tableau de définitions de type. Chaque définition de type dans la valeur est le schéma à utiliser pour valider l’élément d’un tableau au même index. L’exemple suivant accepte [1, true] mais rejette [1, "string"] ou [1]:

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  }
}

items

La valeur de itemsest une définition de type ou une valeur booléenne. Si aucune contrainte items n’est définie, la valeur par défaut est true.

Si value est une définition de type, la valeur décrit le schéma appliqué à tous les éléments du tableau dont l’index est supérieur à l’index le plus grand de la contrainteprefixItems. L’exemple suivant accepte [1, true, 1] ou [1, true, 1, 1] rejette [1, true, "foo"]:

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      { "type": "int" },
      { "type": "bool" }
    ],
    "items": { "type": "int" },
    "defaultValue": [1, true, "foo"]
  }
}

Vous pouvez utiliser items sans utiliser prefixItems. L’exemple suivant accepte [1, 2] ou [1] mais rejette ["foo"]:

"parameters": {
  "intArrayParameter": {
    "type": "array",
    "items": {"type": "int"}
  }
}

Si la valeur est false, le tableau validé doit avoir exactement la même longueur que la prefixItems contrainte. L’exemple suivant accepte [1, true] mais rejette [1, true, 1] et [1, true, false, "foo", "bar"]:

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ],
    "items": false
  }
}

Si la valeur est true, les éléments du tableau dont l’index est supérieur au plus grand index de la prefixItems contrainte acceptent n’importe quelle valeur. Les exemples suivants acceptent [1, true], [1, true, 1] et [1, true, false, "foo", "bar"].

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  }
}

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  },
  "items": true
}

Contrainte nullable

La contrainte nullable ne peut être utilisée qu’avec languageVersion 2.0. Elle indique que la valeur peut être null ou omise. Pour obtenir un exemple, consultez Propriétés .

Description

Vous pouvez ajouter une description à un paramètre pour aider les utilisateurs de votre modèle à comprendre la valeur à fournir. Lorsque vous déployez le modèle par le biais du portail, le texte que vous fournissez dans la description est automatiquement utilisé comme une info-bulle pour ce paramètre. Ajoutez une description uniquement quand le texte fournit des informations en plus de celles qui peuvent être déduites du nom du paramètre.

"parameters": {
  "virtualMachineSize": {
    "type": "string",
    "metadata": {
      "description": "Must be at least Standard_A3 to support 2 NICs."
    },
    "defaultValue": "Standard_DS1_v2"
  }
}

Utiliser un paramètre

Pour référencer la valeur d’un paramètre, utilisez la fonction parameters. L’exemple suivant utilise une valeur de paramètre pour un nom de coffre de clés.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "vaultName": {
      "type": "string",
      "defaultValue": "[format('keyVault{0}', uniqueString(resourceGroup().id))]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.KeyVault/vaults",
      "apiVersion": "2021-06-01-preview",
      "name": "[parameters('vaultName')]",
      ...
    }
  ]
}

Objets en tant que paramètres

Vous pouvez organiser des valeurs connexes en les transmettant en tant qu’objet. Cette approche réduit également le nombre de paramètres dans le modèle.

L’exemple suivant illustre un paramètre qui est un objet. La valeur par défaut affiche les propriétés attendues pour l’objet. Ces propriétés sont utilisées lors de la définition de la ressource à déployer.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "vNetSettings": {
      "type": "object",
      "defaultValue": {
        "name": "VNet1",
        "location": "eastus",
        "addressPrefixes": [
          {
            "name": "firstPrefix",
            "addressPrefix": "10.0.0.0/22"
          }
        ],
        "subnets": [
          {
            "name": "firstSubnet",
            "addressPrefix": "10.0.0.0/24"
          },
          {
            "name": "secondSubnet",
            "addressPrefix": "10.0.1.0/24"
          }
        ]
      }
    }
  },
  "resources": [
    {
      "type": "Microsoft.Network/virtualNetworks",
      "apiVersion": "2021-02-01",
      "name": "[parameters('vNetSettings').name]",
      "location": "[parameters('vNetSettings').location]",
      "properties": {
        "addressSpace": {
          "addressPrefixes": [
            "[parameters('vNetSettings').addressPrefixes[0].addressPrefix]"
          ]
        },
        "subnets": [
          {
            "name": "[parameters('vNetSettings').subnets[0].name]",
            "properties": {
              "addressPrefix": "[parameters('vNetSettings').subnets[0].addressPrefix]"
            }
          },
          {
            "name": "[parameters('vNetSettings').subnets[1].name]",
            "properties": {
              "addressPrefix": "[parameters('vNetSettings').subnets[1].addressPrefix]"
            }
          }
        ]
      }
    }
  ]
}

Exemples de modèles

Les exemples suivants illustrent des scénarios d’utilisation de paramètres.

Modèle Description
Paramètres avec fonctions pour les valeurs par défaut Montre comment utiliser les fonctions de modèle durant la définition des valeurs par défaut des paramètres. Le modèle ne déploie aucune ressource. Il crée et retourne des valeurs de paramètres.
Objet de paramètre Montre comment utiliser un objet pour un paramètre. Le modèle ne déploie aucune ressource. Il crée et retourne des valeurs de paramètres.

Étapes suivantes