Fonctions d’objet pour les modèles ARM

Article
01/11/2024

Resource Manager fournit plusieurs fonctions pour vous permettre d’utiliser des objets dans votre modèle Azure Resource Manager (ARM) :

contains
createObject
empty
intersection
items
json
length
null
union

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 les fonctions d’objet.

contains

contains(container, itemToFind)

Vérifie si un tableau contient une valeur, un objet contient une clé ou une chaîne contient une sous-chaîne. La comparaison de chaînes est sensible à la casse. Cependant, quand vous testez si un objet contient une clé, la comparaison n’est pas sensible à la casse.

Dans Bicep, utilisez la fonction contains.

Paramètres

Paramètre	Obligatoire	Type	Description
conteneur	Oui	tableau, objet ou chaîne	La valeur qui contient la valeur à rechercher.
itemToFind	Oui	chaîne ou entier	La valeur à trouver.

Valeur retournée

True si l’élément est trouvé ; sinon, False.

Exemple

L’exemple suivant montre comment utiliser contains avec différents types :

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "stringToTest": {
      "type": "string",
      "defaultValue": "OneTwoThree"
    },
    "objectToTest": {
      "type": "object",
      "defaultValue": {
        "one": "a",
        "two": "b",
        "three": "c"
      }
    },
    "arrayToTest": {
      "type": "array",
      "defaultValue": [ "one", "two", "three" ]
    }
  },
  "resources": [
  ],
  "outputs": {
    "stringTrue": {
      "type": "bool",
      "value": "[contains(parameters('stringToTest'), 'e')]"
    },
    "stringFalse": {
      "type": "bool",
      "value": "[contains(parameters('stringToTest'), 'z')]"
    },
    "objectTrue": {
      "type": "bool",
      "value": "[contains(parameters('objectToTest'), 'one')]"
    },
    "objectFalse": {
      "type": "bool",
      "value": "[contains(parameters('objectToTest'), 'a')]"
    },
    "arrayTrue": {
      "type": "bool",
      "value": "[contains(parameters('arrayToTest'), 'three')]"
    },
    "arrayFalse": {
      "type": "bool",
      "value": "[contains(parameters('arrayToTest'), 'four')]"
    }
  }
}

La sortie de l’exemple précédent avec les valeurs par défaut se présente comme suit :

Nom	Type	Valeur
stringTrue	Bool	True
stringFalse	Bool	False
objectTrue	Bool	True
objectFalse	Bool	False
arrayTrue	Bool	True
arrayFalse	Bool	False

createObject

createObject(key1, value1, key2, value2, ...)

Crée un objet à partir des clés et des valeurs.

La fonction createObject n’est pas prise en charge par Bicep. Créez un objet en utilisant {}. Consultez Objets.

Paramètres

Paramètre	Obligatoire	Type	Description
key1	Non	string	Nom de la clé.
valeur1	Non	int, boolean, string, object ou array	Valeur pour la clé.
clés supplémentaires	Non	string	Noms supplémentaires des clés.
valeurs supplémentaires	Non	int, boolean, string, object ou array	Valeurs supplémentaires pour les clés.

La fonction attend uniquement un nombre pair de paramètres. Chaque clé doit avoir une valeur correspondante.

Valeur de retour

Objet avec chaque paire de clé et valeur.

Exemple

L’exemple suivant crée un objet à partir de différents types de valeurs.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "resources": [
  ],
  "outputs": {
    "newObject": {
      "type": "object",
      "value": "[createObject('intProp', 1, 'stringProp', 'abc', 'boolProp', true(), 'arrayProp', createArray('a', 'b', 'c'), 'objectProp', createObject('key1', 'value1'))]"
    }
  }
}

La sortie de l’exemple précédent avec les valeurs par défaut est un objet nommé newObject avec la valeur suivante :

{
  "intProp": 1,
  "stringProp": "abc",
  "boolProp": true,
  "arrayProp": ["a", "b", "c"],
  "objectProp": {"key1": "value1"}
}

empty

empty(itemToTest)

Détermine si un tableau, un objet ou une chaîne est vide.

Dans Bicep, utilisez la fonction empty.

Paramètres

Paramètre	Obligatoire	Type	Description
itemToTest	Oui	tableau, objet ou chaîne	Valeur à vérifier pour voir si elle est vide.

Valeur retournée

Retourne True si la valeur est vide ; sinon, False.

Exemple

L’exemple suivant vérifie si un tableau, un objet et une chaîne sont vides.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "testArray": {
      "type": "array",
      "defaultValue": []
    },
    "testObject": {
      "type": "object",
      "defaultValue": {}
    },
    "testString": {
      "type": "string",
      "defaultValue": ""
    }
  },
  "resources": [
  ],
  "outputs": {
    "arrayEmpty": {
      "type": "bool",
      "value": "[empty(parameters('testArray'))]"
    },
    "objectEmpty": {
      "type": "bool",
      "value": "[empty(parameters('testObject'))]"
    },
    "stringEmpty": {
      "type": "bool",
      "value": "[empty(parameters('testString'))]"
    }
  }
}

La sortie de l’exemple précédent avec les valeurs par défaut se présente comme suit :

Nom	Type	Valeur
arrayEmpty	Bool	True
objectEmpty	Bool	True
stringEmpty	Bool	True

intersection

intersection(arg1, arg2, arg3, ...)

Retourne un tableau ou un objet unique avec les éléments communs à partir des paramètres.

Dans Bicep, utilisez la fonction intersection.

Paramètres

Paramètre	Obligatoire	Type	Description
arg1	Oui	objet ou tableau	La première valeur à utiliser pour rechercher des éléments communs.
arg2	Oui	objet ou tableau	La seconde valeur à utiliser pour rechercher des éléments communs.
arguments supplémentaires	Non	objet ou tableau	Valeurs supplémentaires à utiliser pour rechercher des éléments communs.

Valeur de retour

Tableau ou objet avec les éléments communs.

Exemple

L’exemple suivant indique comment utiliser l’intersection avec les tableaux et les objets.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "firstObject": {
      "type": "object",
      "defaultValue": {
        "one": "a",
        "two": "b",
        "three": "c"
      }
    },
    "secondObject": {
      "type": "object",
      "defaultValue": {
        "one": "a",
        "two": "z",
        "three": "c"
      }
    },
    "firstArray": {
      "type": "array",
      "defaultValue": [ "one", "two", "three" ]
    },
    "secondArray": {
      "type": "array",
      "defaultValue": [ "two", "three" ]
    }
  },
  "resources": [
  ],
  "outputs": {
    "objectOutput": {
      "type": "object",
      "value": "[intersection(parameters('firstObject'), parameters('secondObject'))]"
    },
    "arrayOutput": {
      "type": "array",
      "value": "[intersection(parameters('firstArray'), parameters('secondArray'))]"
    }
  }
}

La sortie de l’exemple précédent avec les valeurs par défaut se présente comme suit :

Nom	Type	Valeur
objectOutput	Object	{"one": "a", "three": "c"}
arrayOutput	Array	["two", "three"]

items

items(object)

Convertit un objet dictionnaire en un tableau. Consultez toObject sur la conversion d’un tableau en objet.

Dans Bicep, utilisez les éléments.

Paramètres

Paramètre	Obligatoire	Type	Description
object	Oui	object	Objet dictionnaire à convertir en tableau.

Valeur retournée

Tableau d’objets pour le dictionnaire converti. Chaque objet du tableau a une propriété key qui contient la valeur de clé du dictionnaire. Chaque objet possède également une propriété value qui contient les propriétés de l’objet.

Exemple

L’exemple suivant convertit un objet dictionnaire en tableau. Pour chaque objet du tableau, il crée un objet avec les valeurs modifiées.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "variables": {
    "copy": [
      {
        "name": "modifiedListOfEntities",
        "count": "[length(items(variables('entities')))]",
        "input": {
          "key": "[items(variables('entities'))[copyIndex('modifiedListOfEntities')].key]",
          "fullName": "[items(variables('entities'))[copyIndex('modifiedListOfEntities')].value.displayName]",
          "itemEnabled": "[items(variables('entities'))[copyIndex('modifiedListOfEntities')].value.enabled]"
        }
      }
    ],
    "entities": {
      "item002": {
        "enabled": false,
        "displayName": "Example item 2",
        "number": 200
      },
      "item001": {
        "enabled": true,
        "displayName": "Example item 1",
        "number": 300
      }
    }
  },
  "resources": [],
  "outputs": {
    "modifiedResult": {
      "type": "array",
      "value": "[variables('modifiedListOfEntities')]"
    }
  }
}

L’exemple précédent renvoie :

"modifiedResult": {
  "type": "Array",
  "value": [
    {
      "fullName": "Example item 1",
      "itemEnabled": true,
      "key": "item001"
    },
    {
      "fullName": "Example item 2",
      "itemEnabled": false,
      "key": "item002"
    }
  ]
}

L’exemple suivant montre le tableau renvoyé par la fonction items.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "variables": {
    "entities": {
      "item002": {
        "enabled": false,
        "displayName": "Example item 2",
        "number": 200
      },
      "item001": {
        "enabled": true,
        "displayName": "Example item 1",
        "number": 300
      }
    },
    "entitiesArray": "[items(variables('entities'))]"
  },
  "resources": [],
  "outputs": {
    "itemsResult": {
      "type": "array",
      "value": "[variables('entitiesArray')]"
    }
  }
}

L’exemple renvoie :

"itemsResult": {
  "type": "Array",
  "value": [
    {
      "key": "item001",
      "value": {
        "displayName": "Example item 1",
        "enabled": true,
        "number": 300
      }
    },
    {
      "key": "item002",
      "value": {
        "displayName": "Example item 2",
        "enabled": false,
        "number": 200
      }
    }
  ]
}

Dans JSON, un objet est une collection non ordonnée de zéro ou plus paires clé/valeur. L’ordre peut être différent selon les implémentations. Par exemple, la fonction Bicep items() trie les objets par ordre alphabétique. Dans d’autres endroits, l’ordre d’origine peut être conservé. En raison de ce non-déterminisme, évitez de faire des hypothèses sur l’ordre des clés des objets lors de l’écriture du code, ce qui interagit avec les paramètres et les sorties des déploiements.

json

json(arg1)

Convertit une chaîne JSON valide en un type de données JSON.

Dans Bicep, utilisez la fonction json.

Paramètres

Paramètre	Obligatoire	Type	Description
arg1	Oui	string	Valeur à convertir en JSON. La chaîne doit être une chaîne JSON correctement mise en forme.

Valeur de retour

Le type de données JSON de la chaîne spécifiée ou une valeur vide lorsque null est spécifié.

Notes

Si vous devez inclure une valeur de paramètre ou une variable dans l'objet JSON, utilisez la fonction format pour créer la chaîne que vous transmettez à la fonction.

Vous pouvez également utiliser null() pour obtenir une valeur null.

Exemple

L’exemple suivant explique comment utiliser la fonction json. Notez que vous pouvez transmettre null pour un objet vide.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "jsonEmptyObject": {
      "type": "string",
      "defaultValue": "null"
    },
    "jsonObject": {
      "type": "string",
      "defaultValue": "{\"a\": \"b\"}"
    },
    "jsonString": {
      "type": "string",
      "defaultValue": "\"test\""
    },
    "jsonBoolean": {
      "type": "string",
      "defaultValue": "true"
    },
    "jsonInt": {
      "type": "string",
      "defaultValue": "3"
    },
    "jsonArray": {
      "type": "string",
      "defaultValue": "[[1,2,3 ]"
    },
    "concatValue": {
      "type": "string",
      "defaultValue": "demo value"
    }
  },
  "resources": [
  ],
  "outputs": {
    "emptyObjectOutput": {
      "type": "bool",
      "value": "[empty(json(parameters('jsonEmptyObject')))]"
    },
    "objectOutput": {
      "type": "object",
      "value": "[json(parameters('jsonObject'))]"
    },
    "stringOutput": {
      "type": "string",
      "value": "[json(parameters('jsonString'))]"
    },
    "booleanOutput": {
      "type": "bool",
      "value": "[json(parameters('jsonBoolean'))]"
    },
    "intOutput": {
      "type": "int",
      "value": "[json(parameters('jsonInt'))]"
    },
    "arrayOutput": {
      "type": "array",
      "value": "[json(parameters('jsonArray'))]"
    },
    "concatObjectOutput": {
      "type": "object",
      "value": "[json(concat('{\"a\": \"', parameters('concatValue'), '\"}'))]"
    }
  }
}

La sortie de l’exemple précédent avec les valeurs par défaut se présente comme suit :

Nom	Type	Valeur
emptyObjectOutput	Boolean	True
objectOutput	Object	{"a": "b"}
stringOutput	String	test
booleanOutput	Boolean	True
intOutput	Integer	3
arrayOutput	Array	[ 1, 2, 3 ]
concatObjectOutput	Object	{"a": "valeur de démonstration"}

length

length(arg1)

Retourne le nombre d’éléments d’un tableau, les caractères d’une chaîne ou les propriétés au niveau de la racine d’un objet.

Dans Bicep, utilisez la fonction length.

Paramètres

Paramètre	Obligatoire	Type	Description
arg1	Oui	tableau, chaîne ou objet	Tableau à utiliser pour l’obtention du nombre d’éléments, ou chaîne à utiliser pour l’obtention du nombre de caractères, ou l’objet à utiliser pour l’obtention du nombre de propriétés au niveau de la racine.

Valeur retournée

Un entier.

Exemple

L’exemple suivant montre comment utiliser la longueur avec un tableau et une chaîne :

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "arrayToTest": {
      "type": "array",
      "defaultValue": [
        "one",
        "two",
        "three"
      ]
    },
    "stringToTest": {
      "type": "string",
      "defaultValue": "One Two Three"
    },
    "objectToTest": {
      "type": "object",
      "defaultValue": {
        "propA": "one",
        "propB": "two",
        "propC": "three",
        "propD": {
          "propD-1": "sub",
          "propD-2": "sub"
        }
      }
    }
  },
  "resources": [],
  "outputs": {
    "arrayLength": {
      "type": "int",
      "value": "[length(parameters('arrayToTest'))]"
    },
    "stringLength": {
      "type": "int",
      "value": "[length(parameters('stringToTest'))]"
    },
    "objectLength": {
      "type": "int",
      "value": "[length(parameters('objectToTest'))]"
    }
  }
}

La sortie de l’exemple précédent avec les valeurs par défaut se présente comme suit :

Nom	Type	Valeur
arrayLength	Int	3
stringLength	Int	13
objectLength	Int	4

null

null()

Retourne la valeur NULL.

La fonction null n’est pas disponible dans Bicep. Utilisez plutôt le mot clé null.

Paramètres

La fonction null n’accepte aucun paramètre.

Valeur de retour

Valeur qui correspond toujours à null.

Exemple

L’exemple suivant utilise la fonction null.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "resources": [],
  "outputs": {
    "emptyOutput": {
      "type": "bool",
      "value": "[empty(null())]"
    }
  }
}

La sortie de l’exemple précédent est :

Nom	Type	Valeur
emptyOutput	Bool	True

union

union(arg1, arg2, arg3, ...)

Retourne un tableau ou un objet unique avec tous les éléments communs à partir des paramètres. Pour les tableaux, les valeurs en doublon ne sont incluses qu’une seule fois. Pour les objets, les noms de propriété en double ne sont inclus qu’une seule fois.

Dans Bicep, utilisez la fonction union.

Paramètres

Paramètre	Obligatoire	Type	Description
arg1	Oui	objet ou tableau	La première valeur à utiliser pour joindre des éléments.
arg2	Oui	objet ou tableau	La seconde valeur à utiliser pour joindre des éléments.
arguments supplémentaires	Non	objet ou tableau	Valeurs supplémentaires à utiliser pour joindre des éléments.

Valeur de retour

Objet ou tableau.

Remarques

La fonction union utilise la séquence des paramètres pour déterminer l’ordre et les valeurs du résultat.

Pour les tableaux, la fonction itère dans chaque élément du premier paramètre et l’ajouter au résultat s’il n’est pas déjà présent. Ensuite, il répète le processus pour le deuxième paramètre et pour tous les autres paramètres. Si une valeur est déjà présente, sa position antérieure dans le tableau est conservée.

Pour les objets, les noms et les valeurs des propriétés du premier paramètre sont ajoutés au résultat. Pour les paramètres suivants, tous les nouveaux noms sont ajoutés au résultat. Si un paramètre suivant a une propriété du même nom, cette valeur remplace la valeur existante. L’ordre des propriétés n’est pas garanti.

La fonction union fusionne non seulement les éléments de niveau supérieur, mais aussi, de manière récursive, tous les tableaux et objets imbriqués à l'intérieur de ceux-ci. Consultez le deuxième exemple dans la section suivante.

Exemple

L’exemple suivant indique comment utiliser l’intersection avec les tableaux et les objets :

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "firstObject": {
      "type": "object",
      "defaultValue": {
        "one": "a",
        "two": "b",
        "three": "c1"
      }
    },
    "secondObject": {
      "type": "object",
      "defaultValue": {
        "three": "c2",
        "four": "d",
        "five": "e"
      }
    },
    "firstArray": {
      "type": "array",
      "defaultValue": [ "one", "two", "three" ]
    },
    "secondArray": {
      "type": "array",
      "defaultValue": [ "three", "four" ]
    }
  },
  "resources": [
  ],
  "outputs": {
    "objectOutput": {
      "type": "object",
      "value": "[union(parameters('firstObject'), parameters('secondObject'))]"
    },
    "arrayOutput": {
      "type": "array",
      "value": "[union(parameters('firstArray'), parameters('secondArray'))]"
    }
  }
}

La sortie de l’exemple précédent avec les valeurs par défaut se présente comme suit :

Nom	Type	Valeur
objectOutput	Object	{"one": "a", "two": "b", "three": "c2", "four": "d", "five": "e"}
arrayOutput	Array	["one", "two", "three", "four"]

L'exemple suivant montre la fonctionnalité de fusion approfondie :

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "variables": {
    "firstObject": {
      "property": {
        "one": "a",
        "two": "b",
        "three": "c1"
      },
      "nestedArray": [
        1,
        2
      ]
    },
    "secondObject": {
      "property": {
        "three": "c2",
        "four": "d",
        "five": "e"
      },
      "nestedArray": [
        3,
        4
      ]
    },
    "firstArray": [
      [
        "one",
        "two"
      ],
      [
        "three"
      ]
    ],
    "secondArray": [
      [
        "three"
      ],
      [
        "four",
        "two"
      ]
    ]
  },
  "resources": [],
  "outputs": {
    "objectOutput": {
      "type": "Object",
      "value": "[union(variables('firstObject'), variables('secondObject'))]"
    },
    "arrayOutput": {
      "type": "Array",
      "value": "[union(variables('firstArray'), variables('secondArray'))]"
    }
  }
}

La sortie de l’exemple précédent est :

Nom	Type	Valeur
objectOutput	Object	{"property":{"one":"a","two":"b","three":"c2","four":"d","five":"e"},"nestedArray":[3,4]}
arrayOutput	Tableau	[["one","two"],["three"],["four","two"]]

Si les tableaux imbriqués étaient fusionnés, alors la valeur d'objectOutput.nestedArray serait [1, 2, 3, 4] et la valeur d'arrayOutput serait [["one", "two", "three"], ["three", "four", "two"]].

Étapes suivantes

Pour obtenir une description des sections d’un modèle ARM, consultez Comprendre la structure et la syntaxe des modèles ARM.

Fonctions d’objet pour les modèles ARM

contains

Paramètres

Valeur retournée

Exemple

createObject

Paramètres

Valeur de retour

Exemple

empty

Paramètres

Valeur retournée

Exemple

intersection

Paramètres

Valeur de retour

Exemple

items

Paramètres

Valeur retournée

Exemple

json

Paramètres

Valeur de retour

Notes

Exemple

length

Paramètres

Valeur retournée

Exemple

null

Paramètres

Valeur de retour

Exemple

union

Paramètres

Valeur de retour

Remarques

Exemple

Étapes suivantes

Ressources supplémentaires