Fonctions d’objet pour les modèles ARM

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

• Contient
• createObject
• vide
• carrefour
• Éléments
• json
• longueur
• zéro
• union

contient

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

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 :

createObject

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

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

La createObject fonction n’est pas prise en charge par Bicep. Construisez un objet à l’aide {}de . Voir Objets.

Paramètres

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

Valeur retournée

Objet avec chaque paire 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"}
}

vide

empty(itemToTest)

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

Dans Bicep, utilisez la fonction empty.

Paramètres

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 :

carrefour

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

Valeur retournée

Tableau ou objet avec les éléments communs.

Exemple :

L’exemple suivant montre comment utiliser intersection avec des tableaux et des 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 :

éléments

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

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

Valeur retournée

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

Remarques

Si vous devez inclure une valeur de paramètre ou une variable dans l’objet JSON, utilisez la fonction de format pour créer la chaîne que vous passez à 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 passer 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 :

longueur

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

Valeur retournée

Un entier.

Exemple :

L’exemple suivant montre comment utiliser length 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 :

zéro

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 retournée

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

objectKeys

objectKeys(object)

Retourne les clés d’un objet, où un objet est une collection de paires clé-valeur.

Dans Bicep, utilisez la fonction objectKeys .

Paramètres

Valeur retournée

Tableau.

Exemple :

L’exemple suivant montre comment utiliser objectKeys avec un objet :

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "variables": {
    "obj": {
      "a": 1,
      "b": 2
    }
  },
  "resources": [],
  "outputs": {
    "keyArray": {
      "type": "array",
      "value": "[objectKeys(variables('obj'))]"
    }
  }
}

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

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.

shallowMerge

shallowMerge(inputArray)

Combine un tableau d’objets, où seuls les objets de niveau supérieur sont fusionnés. Cela signifie que si les objets fusionnés contiennent des objets imbriqués, ces objets imbriqués ne sont pas profondément fusionnés ; Au lieu de cela, ils sont entièrement remplacés par la propriété correspondante de l’objet de fusion.

Dans Bicep, utilisez la fonction peu profondeMerge .

Paramètres

Valeur retournée

Objet.

Exemple :

L'exemple suivant montre comment utiliser shallowMerge :

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "variables": {
    "firstArray": [
      {
        "one": "a"
      },
      {
        "two": "b"
      },
      {
        "two": "c"
      }
    ],
    "secondArray": [
      {
        "one": "a",
        "nested": {
          "a": 1,
          "nested": {
            "c": 3
          }
        }
      },
      {
        "two": "b",
        "nested": {
          "b": 2
        }
      }
    ]
  },
  "resources": [],
  "outputs": {
    "firstOutput": {
      "type": "object",
      "value": "[shallowMerge(variables('firstArray'))]"
    },
    "secondOutput": {
      "type": "object",
      "value": "[shallowMerge(variables('secondArray'))]"
    }
  }
}

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

firstOutput montre que les propriétés des objets de fusion sont combinées en un nouvel objet. S’il existe des propriétés en conflit (c’est-à-dire des propriétés portant le même nom), la propriété du dernier objet fusionné est généralement prioritaire.

secondOutput montre que la fusion superficielle ne fusionne pas de manière récursive ces objets imbriqués. Au lieu de cela, l’objet imbriqué entier est remplacé par la propriété correspondante de l’objet de fusion.

tryGet

tryGet(itemToTest, keyOrIndex)

tryGet vous permet d’éviter les échecs de déploiement lors de la tentative d’accès à une propriété ou à un index inexistant dans un objet ou un tableau. Si la clé ou l’index spécifié n’existe pas, tryGet retourne null au lieu de lever une erreur.

Dans Bicep, utilisez l’opérateur safe-dereference .

Paramètres

Valeur retournée

Retourne la valeur à la clé/index s’il existe. Retourne la valeur Null si la clé/l’index est manquant ou hors limites.

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#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",
  "variables": {
    "users": {
      "name": "John Doe",
      "age": 30
    },
    "colors": [
      "red",
      "green"
    ]
  },
  "resources": [],
  "outputs": {
    "region": {
      "type": "string",
      "nullable": true,
      "value": "[tryGet(variables('users'), 'region')]"
    },
    "name": {
      "type": "string",
      "nullable": true,
      "value": "[tryGet(variables('users'), 'name')]"
    },
    "firstColor": {
      "type": "string",
      "nullable": true,
      "value": "[tryGet(variables('colors'), 0)]"
    }
  }
}

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

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

Valeur retournée

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 tous les paramètres supplémentaires. 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 façon récursive, en fusionnant de manière récursive les tableaux et les objets imbriqués dans ceux-ci. Consultez le deuxième exemple dans la section suivante.

Exemple :

L’exemple suivant montre comment utiliser union 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 :

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 :

Si les tableaux imbriqués étaient fusionnés, alors la valeur objectOutput.nestedArray serait [1, 2, 3, 4] et la valeur 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.