Définitions de type dans les modèles ARM

Article
09/05/2023

Cet article explique comment créer et utiliser des définitions dans un modèle Azure Resource Manager (ARM). En définissant vos propres types, vous pouvez réutiliser ces types. Les définitions de type ne peuvent être utilisées qu’avec languageVersion 2.0.

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 plus d’informations, consultez Types de données définis par l’utilisateur dans Bicep.

Déclaration minimale

Au minimum, chaque définition de type a besoin d’un nom et d’un type ou d’un $ref.

"definitions": {
  "demoStringType": {
    "type": "string"
  },
  "demoIntType": {
    "type": "int"
  },
  "demoBoolType": {
    "type": "bool"
  },
  "demoObjectType": {
    "type": "object"
  },
  "demoArrayType": {
    "type": "array"
  }
}

Valeurs autorisées

Vous pouvez définir des valeurs autorisées pour une définition de type. Vous fournissez les valeurs autorisées dans un tableau. Le déploiement échoue pendant la validation si une valeur qui n’est pas une des valeurs autorisées est transmise pour la définition de type.

"definitions": {
  "demoEnumType": {
    "type": "string",
    "allowedValues": [
      "one",
      "two"
    ]
  }
}

Contraintes de longueur

Vous pouvez spécifier des longueurs minimale et maximale pour les définitions de type 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 définitions de type. Une définition de type est destinée à un nom de compte de stockage qui doit compter entre 3 et 24 caractères. L’autre définition de type est un tableau qui doit compter entre 1 et 5 éléments.

"definitions": {
  "storageAccountNameType": {
    "type": "string",
    "minLength": 3,
    "maxLength": 24
  },
  "appNameType": {
    "type": "array",
    "minLength": 1,
    "maxLength": 5
  }
}

Contraintes d’entier

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

"definitions": {
  "monthType": {
    "type": "int",
    "minValue": 1,
    "maxValue": 12
  }
}

Contraintes d’objet

Propriétés

La valeur de properties est une carte de nom de propriété =>définition de type.

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

"definitions": {
  "objectDefinition": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3
      },
      "bar": {
        "type": "int",
        "minValue": 0
      }
    }
  }
},
"parameters": {
  "objectParameter": {
    "$ref": "#/definitions/objectDefinition",
  }
}

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

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

additionalProperties

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

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

"definitions": {
  "dictionaryDefinition": {
    "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 contrainte properties ne peut être fournie. L’exemple suivant accepte {"foo": "string", "bar": 1} mais rejette {"foo": "string", "bar": 1, "fizz": "buzz"}.

"definitions": {
  "dictionaryDefinition": {
    "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 contrainte properties accepte n'importe quelle valeur. L’exemple suivant accepte {"foo": "string", "bar": 1, "fizz": "buzz"}.

"definitions": {
  "dictionaryDefinition": {
    "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"}.

"definitions": {
  "taggedUnionDefinition": {
    "type": "object",
    "discriminator": {
      "propertyName": "type",
      "mapping": {
        "ints": {
          "type": "object",
          "additionalProperties": {"type": "int"}
        },
        "strings": {
          "type": "object",
          "additionalProperties": {"type": "string"}
          }
      }
    }
  }
}

Contraintes de tableau

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

"definitions": {
  "tupleDefinition": {
    "type": "array",
    "prefixItems": [
      { "type": "int" },
      { "type": "bool" }
    ]
  }
},
"parameters": {
  "tupleParameter": {
    "$ref": "#/definitions/tupleDefinition"
  }
}

items

La valeur de items est 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 la valeur 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 contrainte prefixItems. L’exemple suivant accepte [1, true, 1] ou [1, true, 1, 1], mais rejette [1, true, "foo"] :

"definitions": {
  "tupleDefinition": {
    "type": "array",
    "prefixItems": [
      { "type": "int" },
      { "type": "bool" }
    ],
    "items": { "type": "int" }
  }
},
"parameters": {
  "tupleParameter": {
    "$ref": "#/definitions/tupleDefinition"
  }
}

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

"definitions": {
  "intArrayDefinition": {
    "type": "array",
    "items": { "type": "int" }
  }
},
"parameters": {
  "intArrayParameter": {
    "$ref": "#/definitions/intArrayDefinition"
  }
}

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

"definitions": {
  "tupleDefinition": {
    "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 contrainte prefixItems acceptent n’importe quelle valeur. Les exemples suivants acceptent [1, true], [1, true, 1] et [1, true, false, "foo", "bar"].

"definitions": {
  "tupleDefinition": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  }
}

"definitions": {
  "tupleDefinition": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  },
  "items": true
}

Contrainte nullable

La contrainte nullable indique que la valeur peut être null ou omise. Pour obtenir un exemple, consultez Propriétés.

Description

Vous pouvez ajouter une description à une définition de type pour aider les utilisateurs de votre modèle à comprendre la valeur à fournir.

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

Utiliser une définition

Pour référencer une définition de type, utilisez la syntaxe suivante :

"$ref": "#/definitions/<definition-name>"

L’exemple suivant montre comment référencer une définition de type à partir de paramètres et de sorties :

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "languageVersion": "2.0",

  "definitions": {
    "naturalNumber": {
      "type": "int",
      "minValue": 1
    }
  },
  "parameters": {
    "numberParam": {
      "$ref": "#/definitions/naturalNumber",
      "defaultValue": 0
    }
  },
  "resources": {},
  "outputs": {
    "output1": {
      "$ref": "#/definitions/naturalNumber",
      "value": "[parameters('numberParam')]"
    }
  }
}

Étapes suivantes

Pour plus d’informations sur les propriétés disponibles pour les définitions de type, consultez Présentation de la structure et de la syntaxe des modèles ARM.