Créer des stratégies pour les propriétés de tableau sur des ressources Azure

Les propriétés Azure Resource Manager sont généralement définies comme des chaînes et des valeurs booléennes. Lorsqu’il existe une relation un-à-plusieurs, des propriétés complexes sont plutôt définies comme des tableaux. Dans Azure Policy, les tableaux sont utilisés de différentes manières :

• Le type d’un paramètre de définition, pour fournir plusieurs options.
• Une partie d’une règle de stratégie utilisant les conditions in ou notIn.
• Une partie d’une règle de stratégie qui compte le nombre de membres d’un tableau qui remplissent une condition.
• Dans les effets append et modify pour mettre à jour un tableau existant

Cet article traite chaque utilisation par Azure Policy et fournit plusieurs exemples de définitions.

Tableaux de paramètres

Définir un tableau de paramètres

La définition d’un paramètre sous forme de tableau permet une flexibilité de la stratégie lorsque plusieurs valeurs sont nécessaires. Cette définition de stratégie permet de définir n’importe quel localisation unique pour le paramètre allowedLocations, et sa valeur par défaut est eastus2 :

"parameters": {
  "allowedLocations": {
    "type": "string",
    "metadata": {
      "description": "The list of allowed locations for resources.",
      "displayName": "Allowed locations",
      "strongType": "location"
    },
    "defaultValue": "eastus2"
  }
}

Comme type était string, une seule valeur peut être définie lors de l’affectation de la stratégie. Si cette stratégie est affectée, les ressources dans l’étendue sont autorisées uniquement dans une seule région Azure. La plupart des définitions de stratégies doivent autoriser une liste des options approuvées, par exemple pour autoriser eastus2, eastus, et westus2.

Pour créer la définition de stratégie de façon à autoriser plusieurs options, utilisez le type array. La même stratégie peut être réécrite comme suit :

"parameters": {
  "allowedLocations": {
    "type": "array",
    "metadata": {
      "description": "The list of allowed locations for resources.",
      "displayName": "Allowed locations",
      "strongType": "location"
    },
    "defaultValue": [
      "eastus2"
    ],
    "allowedValues": [
      "eastus2",
      "eastus",
      "westus2"
    ]
  }
}

Cette nouvelle définition de paramètre accepte plusieurs valeurs lors de l’affectation de stratégie. Avec la propriété de tableau allowedValues définie, les valeurs disponibles lors de l’affectation sont limitées à la liste prédéfinie de choix. L’utilisation de allowedValues est facultative.

Passer des valeurs à un tableau de paramètres lors de l’attribution

Lorsque vous affectez la stratégie via le portail Azure, un paramètre de type array s’affiche sous la forme d’une zone de texte unique. L’indicateur mentionne Use ; to separate values. (e.g. London;New York). Pour passer les valeurs d’emplacement autorisées de eastus2, eastus et westus2 au paramètre, utilisez la chaîne suivante :

eastus2;eastus;westus2

Le format de la valeur du paramètre est différent lorsque vous utilisez Azure CLI, Azure PowerShell ou l’API REST. Les valeurs sont transmises via une chaîne JSON qui inclut également le nom du paramètre.

{
  "allowedLocations": {
    "value": [
      "eastus2",
      "eastus",
      "westus2"
    ]
  }
}

Pour utiliser cette chaîne avec chaque kit SDK, utilisez les commandes suivantes :

• Azure CLI : Commande az policy assignment create avec le paramètre params.
• Azure PowerShell : Applet de commande New-AzPolicyAssignment avec le paramètre PolicyParameter.
• API REST : Dans l’opération PUT create, dans le corps de la requête comme valeur de la propriété properties.parameters.

Utilisation de tableaux dans des conditions

In et notIn

Les conditions in et notIn ne fonctionnent qu’avec des valeurs de tableau. Elles vérifient l’existence d’une valeur dans un tableau. Le tableau peut être un tableau JSON littéral ou une référence à un paramètre de tableau. Par exemple :

{
  "field": "tags.environment",
  "in": [
    "dev",
    "test"
  ]
}

{
  "field": "location",
  "notIn": "[parameters('allowedLocations')]"
}

value count

L’expression value count compte le nombre d’expressions qui remplissent une condition. Elle offre un moyen d’évaluer plusieurs fois la même condition, en utilisant des valeurs différentes pour chaque itération. Par exemple, la condition suivante vérifie si le nom de la ressource correspond à un modèle dans un tableau de modèles :

{
  "count": {
    "value": [
      "test*",
      "dev*",
      "prod*"
    ],
    "name": "pattern",
    "where": {
      "field": "name",
      "like": "[current('pattern')]"
    }
  },
  "greater": 0
}

Pour évaluer l’expression, Azure Policy évalue la condition where trois fois, une fois pour chaque membre de [ "test*", "dev*", "prod*" ], en comptant le nombre de fois où elle a été jugée true. À chaque itération, la valeur du membre du tableau actuel est associée au nom d’index pattern défini par count.name. Cette valeur peut ensuite être référencée à l’intérieur de la condition where en appelant une fonction de modèle spéciale : current('pattern').

La condition est vraie uniquement si le nombre obtenu est supérieur à 0.

Pour rendre la condition précédente plus générique, utilisez une référence parameters au lieu d’un tableau de littéraux :

{
  "count": {
    "value": "[parameters('patterns')]",
    "name": "pattern",
    "where": {
      "field": "name",
      "like": "[current('pattern')]"
    }
  },
  "greater": 0
}

Lorsque l’expression value count ne figure pas sous une autre expression count, count.name est facultatif et la fonction current() peut être utilisée sans argument :

{
  "count": {
    "value": "[parameters('patterns')]",
    "where": {
      "field": "name",
      "like": "[current()]"
    }
  },
  "greater": 0
}

value count prend également en charge les tableaux d’objets complexes, ce qui permet des conditions plus complexes. Par exemple, la condition suivante définit une valeur de balise souhaitée pour chaque modèle de nom, et vérifie si le nom de la ressource correspond au modèle, mais n’a pas la valeur de balise requise :

{
  "count": {
    "value": [
      {
        "pattern": "test*",
        "envTag": "dev"
      },
      {
        "pattern": "dev*",
        "envTag": "dev"
      },
      {
        "pattern": "prod*",
        "envTag": "prod"
      },
    ],
    "name": "namePatternRequiredTag",
    "where": {
      "allOf": [
        {
          "field": "name",
          "like": "[current('namePatternRequiredTag').pattern]"
        },
        {
          "field": "tags.env",
          "notEquals": "[current('namePatternRequiredTag').envTag]"
        }
      ]
    }
  },
  "greater": 0
}

Pour obtenir des exemples utiles, consultez Exemples value count.

Référencement des propriétés de ressource de tableau

De nombreux cas d’usage requièrent l’utilisation de propriétés de tableau dans la ressource évaluée. Certains scénarios requièrent le référencement d’un tableau entier (par exemple, la vérification de sa longueur). D’autres requièrent l’application d’une condition à chaque membre du tableau (par exemple, s’assurer que toutes les règles de pare-feu bloquent l’accès à partir d’Internet). Comprendre les différentes façons dont Azure Policy peut faire référence aux propriétés de ressources et comment ces références se comportent lorsqu’elles font référence à des propriétés de tableau est la clé pour écrire les conditions qui couvrent ces scénarios.

Référencement des propriétés de ressource

Les propriétés de ressource peuvent être référencées par Azure Policy à l’aide d’alias. Il existe deux façons de référencer les valeurs d’une propriété de ressource dans Azure Policy :

• Utilisez la condition field pour vérifier si toutes les propriétés de ressources sélectionnées remplissent une condition. Exemple :

  {
    "field": "Microsoft.Test/resourceType/property",
    "equals": "value"
  }
  

• Utilisez la fonction field() pour accéder à la valeur d’une propriété. Exemple :

  {
    "value": "[take(field('Microsoft.Test/resourceType/property'), 7)]",
    "equals": "prefix_"
  }
  

La condition field a un comportement implicite allOf. Si l’alias représente une collection de valeurs, il vérifie si toutes les valeurs individuelles remplissent la condition. La fonction field() retourne les valeurs représentées par l’alias telles quelles, qui peuvent ensuite être manipulées par d’autres fonctions de modèle.

Référencement des champs de tableau

Les propriétés de ressource de tableau sont représentées par deux types d’alias différents. Un alias normal et des alias de tableau auxquels [*] est attaché :

• Microsoft.Test/resourceType/stringArray
• Microsoft.Test/resourceType/stringArray[*]

Référencement du tableau

Le premier alias représente une valeur unique, la valeur de la propriété stringArray provenant du contenu de la demande. Étant donné que la valeur de cette propriété est un tableau, elle n’est pas utile dans les conditions de stratégie. Par exemple :

{
  "field": "Microsoft.Test/resourceType/stringArray",
  "equals": "..."
}

Cette condition compare l’intégralité du tableau stringArray à une valeur de chaîne unique. La plupart des conditions, notamment equals, acceptent uniquement des valeurs de chaîne. Il n’est donc pas très utile de comparer un tableau à une chaîne. Le principal scénario où il est utile de référencer la propriété du tableau est lorsqu’il s’agit de vérifier si cette propriété existe :

{
  "field": "Microsoft.Test/resourceType/stringArray",
  "exists": "true"
}

Avec la fonction field(), la valeur renvoyée est le tableau du contenu de la demande, qui peut ensuite être utilisé avec l’une des fonctions de modèle prises en charge qui acceptent des arguments de tableau. Par exemple, la condition suivante vérifie si la longueur de stringArray est supérieure à 0 :

{
  "value": "[length(field('Microsoft.Test/resourceType/stringArray'))]",
  "greater": 0
}

Référencement de la collection des membres du tableau

Les alias qui utilisent la syntaxe [*] représentent une collection de valeurs de propriétés sélectionnées à partir d’une propriété de tableau, ce qui est différent de la sélection de la propriété de tableau proprement dite. Par exemple, Microsoft.Test/resourceType/stringArray[*] retourne une collection qui contient tous les membres de stringArray. Comme mentionné précédemment, une condition field vérifie que toutes les propriétés de ressources sélectionnées remplissent la condition. Par conséquent, la condition suivante est vraie uniquement si tous les membres de stringArray sont égaux à "value".

{
  "field": "Microsoft.Test/resourceType/stringArray[*]",
  "equals": "value"
}

Si le tableau est vide, la condition prend la valeur true, car aucun membre du tableau ne présente de violation. Dans ce scénario, nous vous recommandons d’utiliser plutôt l’expression count. Si le tableau contient des objets, un alias [*] peut être utilisé pour sélectionner la valeur d’une propriété spécifique de chaque membre du tableau. Exemple :

{
  "field": "Microsoft.Test/resourceType/objectArray[*].property",
  "equals": "value"
}

Cette condition est vraie si les valeurs de toutes les propriétés property dans objectArray sont égales à "value". Pour obtenir plus d’exemples, consultez Autres exemples d’alias.

Lors de l’utilisation de la fonction field() pour référencer un alias de tableau, la valeur renvoyée est un tableau de toutes les valeurs sélectionnées. Ce comportement signifie que le cas d’usage courant de la fonction field(), c’est-à-dire la possibilité d’appliquer des fonctions de modèle à des valeurs de propriété de ressource, est limité. Les seules fonctions de modèle qui peuvent être utilisées dans ce cas sont celles qui acceptent des arguments de tableau. Par exemple, il est possible d’obtenir la longueur du tableau avec [length(field('Microsoft.Test/resourceType/objectArray[*].property'))]. Toutefois, des scénarios plus complexes, tels que l’application d’une fonction de modèle à chaque membre du tableau et sa comparaison à une valeur souhaitée, sont possibles uniquement en utilisant l’expression count. Pour plus d’informations, consultez Expression field count.

Pour résumer, consultez l’exemple de contenu de ressource suivant et les valeurs sélectionnées renvoyées par différents alias :

{
  "tags": {
    "env": "prod"
  },
  "properties": {
    "stringArray": [
      "a",
      "b",
      "c"
    ],
    "objectArray": [
      {
        "property": "value1",
        "nestedArray": [
          1,
          2
        ]
      },
      {
        "property": "value2",
        "nestedArray": [
          3,
          4
        ]
      }
    ]
  }
}

Lorsque vous utilisez la condition field sur l’exemple de contenu de ressource, les résultats sont les suivants :

Lorsque vous utilisez la fonction field() sur l’exemple de contenu de ressource, les résultats sont les suivants :

Expressions field count

Les expressions field count comptent le nombre de membres de tableau qui remplissent une condition et le comparent à une valeur cible. L’expression Count est plus intuitive et polyvalente pour l’évaluation des tableaux par rapport aux conditions field. La syntaxe est :

{
  "count": {
    "field": <[*
    ] alias>,
    "where": <optional policy condition expression>
  },
  "equals|greater|less|any other operator": <target value>
}

En cas d’utilisation sans condition where, count retourne simplement la longueur d’un tableau. Avec l’exemple de contenu de ressource de la section précédente, l’évaluation de l’expression count suivante est true puisque stringArray a trois membres :

{
  "count": {
    "field": "Microsoft.Test/resourceType/stringArray[*]"
  },
  "equals": 3
}

Ce comportement fonctionne également avec les tableaux imbriqués. Par exemple, l’expression count suivante est évaluée comme true dans la mesure où il y a quatre membres de tableau dans les tableaux nestedArray :

{
  "count": {
    "field": "Microsoft.Test/resourceType/objectArray[*].nestedArray[*]"
  },
  "greaterOrEquals": 4
}

La puissance de count tient à la condition where. Quand count est spécifié, Azure Policy énumère les membres du tableau et évalue chacun d’entre eux par rapport à la condition, en comptant le nombre de membres du tableau évalués comme true. Plus précisément, dans chaque itération de l’évaluation de la condition where, Azure Policy sélectionne un membre de tableau unique i et évalue le contenu de la ressource par rapport à la condition where comme si i était le seul membre du tableau. Le fait d’avoir un seul membre de tableau disponible dans chaque itération permet d’appliquer des conditions complexes sur chaque membre du tableau.

Exemple :

{
  "count": {
    "field": "Microsoft.Test/resourceType/stringArray[*]",
    "where": {
      "field": "Microsoft.Test/resourceType/stringArray[*]",
      "equals": "a"
    }
  },
  "equals": 1
}

Pour évaluer l’expression count, Azure Policy évalue la condition where trois fois, une fois pour chaque membre de stringArray, en comptant le nombre de fois où elle a été jugée true. Lorsque la condition where fait référence aux membres du tableau Microsoft.Test/resourceType/stringArray[*], au lieu de sélectionner tous les membres de stringArray, elle ne sélectionne qu’un seul membre de tableau à chaque fois :

count retourne 1.

Voici une expression plus complexe :

{
  "count": {
    "field": "Microsoft.Test/resourceType/objectArray[*]",
    "where": {
      "allOf": [
        {
          "field": "Microsoft.Test/resourceType/objectArray[*].property",
          "equals": "value2"
        },
        {
          "field": "Microsoft.Test/resourceType/objectArray[*].nestedArray[*]",
          "greater": 2
        }
      ]
    }
  },
  "equals": 1
}

count retourne 1.

Le fait que l’expression where soit évaluée par rapport à la totalité du contenu de la requête (avec des modifications apportées uniquement au membre du tableau en cours d’énumération) signifie que la condition where peut également faire référence à des champs en dehors du tableau :

{
  "count": {
    "field": "Microsoft.Test/resourceType/objectArray[*]",
    "where": {
      "field": "tags.env",
      "equals": "prod"
    }
  },
  "equals": 0
}

Des expressions count imbriquées peuvent être utilisées pour appliquer des conditions aux champs de tableau imbriqués. Par exemple, la condition suivante vérifie que le tableau objectArray[*] a exactement deux membres avec nestedArray[*] qui contient un ou plusieurs membres :

{
  "count": {
    "field": "Microsoft.Test/resourceType/objectArray[*]",
    "where": {
      "count": {
        "field": "Microsoft.Test/resourceType/objectArray[*].nestedArray[*]"
      },
      "greaterOrEquals": 1
    }
  },
  "equals": 2
}

Étant donné que les deux membres de objectArray[*] ont un tableau enfant nestedArray[*] avec deux membres, l’expression outer count retourne 2.

Exemple plus complexe : vérifiez que le tableau objectArray[*] a exactement deux membres avec nestedArray[*] avec tous les membres égaux à 2 ou 3 :

{
  "count": {
    "field": "Microsoft.Test/resourceType/objectArray[*]",
    "where": {
      "count": {
        "field": "Microsoft.Test/resourceType/objectArray[*].nestedArray[*]",
        "where": {
          "field": "Microsoft.Test/resourceType/objectArray[*].nestedArray[*]",
          "in": [
            2,
            3
          ]
        }
      },
      "greaterOrEquals": 1
    }
  },
  "equals": 2
}

Étant donné que les deux membres de objectArray[*] ont un tableau enfant nestedArray[*] qui contient 2 ou 3, l’expression outer count retourne 2.

Accès au membre du tableau actuel avec des fonctions de modèle

Quand vous utilisez des fonctions de modèle, utilisez la fonction current() pour accéder à la valeur du membre du tableau actuel ou aux valeurs de l’une de ses propriétés. Pour accéder à la valeur du membre du tableau actuel, passez l’alias défini dans count.field ou l’un de ses alias enfants comme argument à la fonction current() . Par exemple :

{
  "count": {
    "field": "Microsoft.Test/resourceType/objectArray[*]",
    "where": {
      "value": "[current('Microsoft.Test/resourceType/objectArray[*].property')]",
      "like": "value*"
    }
  },
  "equals": 2
}

La fonction field dans des conditions where

La fonction field() peut également être utilisée pour accéder à la valeur du membre du tableau actuel tant que l’expression count ne figure pas à l’intérieur d’une condition d’existence (la fonctionfield() fait toujours référence à la ressource évaluée dans la condition if). Le comportement de field() lorsque vous faites référence au tableau évalué repose sur les concepts suivants :

• Les alias de tableau sont résolus en une collection de valeurs sélectionnées parmi tous les membres du tableau.
• Les fonctions field() qui référencent des alias de tableau retournent un tableau avec les valeurs sélectionnées.
• Le référencement de l’alias de tableau compté à l’intérieur de la condition where retourne une collection avec une seule valeur sélectionnée dans le membre du tableau évalué dans l’itération actuelle.

Ce comportement signifie que, lorsque vous faites référence au membre de tableau compté avec une fonction field() à l’intérieur de la condition where, un tableau avec un seul membre est renvoyé. Bien que ce comportement ne soit pas intuitif, il est cohérent avec l’idée que les alias de tableau retournent toujours une collection de propriétés sélectionnées. Voici un exemple :

{
  "count": {
    "field": "Microsoft.Test/resourceType/stringArray[*]",
    "where": {
      "field": "Microsoft.Test/resourceType/stringArray[*]",
      "equals": "[field('Microsoft.Test/resourceType/stringArray[*]')]"
    }
  },
  "equals": 0
}

Par conséquent, lorsqu’il est nécessaire d’accéder à la valeur de l’alias de tableau compté avec une fonction field(), la façon de le faire consiste à l’inclure dans un wrapper avec une fonction de modèle first() :

{
  "count": {
    "field": "Microsoft.Test/resourceType/stringArray[*]",
    "where": {
      "field": "Microsoft.Test/resourceType/stringArray[*]",
      "equals": "[first(field('Microsoft.Test/resourceType/stringArray[*]'))]"
    }
  }
}

Pour obtenir des exemples utiles, consultez Exemples field count.

Modification de tableaux

Les effets append et modify modifient les propriétés d’une ressource lors de sa création ou de sa mise à jour. Lorsque vous utilisez des propriétés de tableau, le comportement de ces effets varie selon que l’opération tente de modifier ou non l’alias [*] :

Pour plus d’informations, consultez ces exemples Append.

Autres exemples d’alias

Nous vous recommandons d’utiliser les expressions field count pour vérifier si allOf ou anyOf des membres d’un tableau dans le contenu de la requête remplissent une condition. Dans certaines conditions simples, il est possible d’obtenir le même résultat en utilisant un accesseur de champ avec un alias de tableau, comme décrit dans Référencement de la collection des membres du tableau. Ce modèle peut être utile dans les règles de stratégie qui dépassent la limite du nombre d’expressions count. Voici des exemples de cas d’utilisation courants :

Voici un exemple de règle de stratégie pour le tableau de scénario suivant :

"policyRule": {
  "if": {
    "allOf": [
      {
        "field": "Microsoft.Storage/storageAccounts/networkAcls.ipRules",
        "exists": "true"
      },
            <-- Condition (see table below) -->
    ]
  },
  "then": {
    "effect": "[parameters('effectType')]"
  }
}

Pour le tableau de scénario suivant, le tableau ipRules se présente comme suit :

"ipRules": [
  {
    "value": "127.0.0.1",
    "action": "Allow"
  },
  {
    "value": "192.168.1.1",
    "action": "Allow"
  }
]

Pour chacun des exemples de condition suivants, remplacez <field> par "field": "Microsoft.Storage/storageAccounts/networkAcls.ipRules[*].value".

Les résultats suivants viennent de la combinaison de la condition et de l’exemple de règle de stratégie et du tableau des valeurs existantes précédent :

Étapes suivantes

• Consultez des exemples à la page Exemples Azure Policy.
• Consultez la Structure de définition Azure Policy.
• Consultez la page Compréhension des effets de Policy.
• Découvrez comment créer des stratégies par programmation.
• Découvrez comment corriger des ressources non conformes.
• Pour en savoir plus sur les groupes d’administration, consultez Organiser vos ressources avec des groupes d’administration Azure.