Créer des stratégies pour les propriétés de tableau sur des ressources AzureAuthor policies for array properties on Azure resources

Les propriétés Azure Resource Manager sont généralement définies comme des chaînes et des valeurs booléennes.Azure Resource Manager properties are commonly defined as strings and booleans. Lorsqu’il existe une relation un-à-plusieurs, des propriétés complexes sont plutôt définies comme des tableaux.When a one-to-many relationship exists, complex properties are instead defined as arrays. Dans Azure Policy, les tableaux sont utilisés de différentes manières :In Azure Policy, arrays are used in several different ways:

  • Le type d’un paramètre de définition, pour fournir plusieurs optionsThe type of a definition parameter, to provide multiple options
  • Une partie d’une règle de stratégie utilisant les conditions In ou notInPart of a policy rule using the conditions in or notIn
  • Il s’agit d’une partie d’une règle de stratégie qui évalue l’alias [*] pour évaluer ce qui suit :Part of a policy rule that evaluates the [*] alias to evaluate:
    • Scénarios tels que None (Aucun), Any (N’importe lequel) ou All (Tout)Scenarios such as None, Any, or All
    • Scénarios complexes avec countComplex scenarios with count
  • Dans l’effet Append pour remplacer ou ajouter à un tableau existantIn the append effect to replace or add to an existing array

Cet article traite chaque utilisation par Azure Policy et fournit plusieurs exemples de définitions.This article covers each use by Azure Policy and provides several example definitions.

Tableaux de paramètresParameter arrays

Définir un tableau de paramètresDefine a parameter array

La définition d’un paramètre sous forme de tableau permet une flexibilité de la stratégie lorsque plusieurs valeurs sont nécessaires.Defining a parameter as an array allows the policy flexibility when more than one value is needed. Cette définition de stratégie permet de régler n’importe quel emplacement unique pour le paramètre allowedLocations et les valeurs par défaut sur eastus2:This policy definition allows any single location for the parameter allowedLocations and defaults to eastus2:

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

Comme le type était chaîne, une seule valeur peut être définie lors de l’affectation de la stratégie.As type was string, only one value can be set when assigning the policy. Si cette stratégie est affectée, les ressources dans l’étendue sont autorisées uniquement dans une seule région Azure.If this policy is assigned, resources in scope are only allowed within a single Azure region. La plupart des définitions de stratégies doivent autoriser une liste des options approuvées, par exemple pour autoriser eastus2, eastus, et westus2.Most policies definitions need to allow for a list of approved options, such as allowing eastus2, eastus, and westus2.

Pour créer la définition de stratégie visant à autoriser plusieurs options, utilisez le type tableau.To create the policy definition to allow multiple options, use the array type. La même stratégie peut être réécrite comme suit :The same policy can be rewritten as follows:

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

    }
}

Notes

Lorsqu’une définition de stratégie est enregistrée, la propriété type sur un paramètre ne peut pas être modifiée.Once a policy definition is saved, the type property on a parameter can't be changed.

Cette nouvelle définition de paramètre accepte plusieurs valeurs lors de l’affectation de stratégie.This new parameter definition takes more than one value during policy assignment. 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.With the array property allowedValues defined, the values available during assignment are further limited to the predefined list of choices. L’utilisation de allowedValues est facultative.Use of allowedValues is optional.

Passer des valeurs à un tableau de paramètres lors de l’attributionPass values to a parameter array during assignment

Lors de l’affectation de la stratégie via le portail Azure, un paramètre de type tableau s’affiche comme une zone de texte unique.When assigning the policy through the Azure portal, a parameter of type array is displayed as a single textbox. L’indicateur indique « Utiliser ’;’ pour séparer des valeurs.The hint says "Use ; to separate values. (par exemple, Londres;New York) ».(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 :To pass the allowed location values of eastus2, eastus, and westus2 to the parameter, use the following string:

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.The format for the parameter value is different when using Azure CLI, Azure PowerShell, or the REST API. Les valeurs sont transmises via une chaîne JSON qui inclut également le nom du paramètre.The values are passed through a JSON string that also includes the name of the parameter.

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

Pour utiliser cette chaîne avec chaque kit SDK, utilisez les commandes suivantes :To use this string with each SDK, use the following commands:

  • Interface de ligne de commande Azure : Commande az policy assignment create avec le paramètre paramsAzure CLI: Command az policy assignment create with parameter params
  • Azure PowerShell : Applet de commande New-AzPolicyAssignment avec le paramètre PolicyParameterAzure PowerShell: Cmdlet New-AzPolicyAssignment with parameter PolicyParameter
  • API REST : Dans l’opération PUT create en tant que partie intégrante du corps de la demande en tant que valeur d’une propriété properties.parametersREST API: In the PUT create operation as part of the Request Body as the value of the properties.parameters property

Règles de stratégie et tableauxPolicy rules and arrays

Conditions de tableauArray conditions

La règle de stratégie conditions avec laquelle un type tableau du paramètre peut être utilisé est limitée à in et notIn.The policy rule conditions that an array type of parameter may be used with is limited to in and notIn. Prenez la définition de stratégie suivante avec la condition equals comme exemple :Take the following policy definition with condition equals as an example:

{
  "policyRule": {
    "if": {
      "not": {
        "field": "location",
        "equals": "[parameters('allowedLocations')]"
      }
    },
    "then": {
      "effect": "audit"
    }
  },
  "parameters": {
    "allowedLocations": {
      "type": "Array",
      "metadata": {
        "description": "The list of allowed locations for resources.",
        "displayName": "Allowed locations",
        "strongType": "location"
      }
    }
  }
}

Une tentative de création de cette définition de stratégie via le portail Azure entraîne une erreur telle que ce message d’erreur :Attempting to create this policy definition through the Azure portal leads to an error such as this error message:

  • « La stratégie '{GUID}' ne peut pas être paramétrée en raison d’erreurs de validation."The policy '{GUID}' could not be parameterized because of validation errors. Vérifiez si les paramètres de stratégie sont correctement définis.Please check if policy parameters are properly defined. L’exception interne « Résultat d’évaluation de l’expression de langage '[parameters('allowedLocations')]' est de type « Tableau », le type attendu est « String ». »The inner exception 'Evaluation result of language expression '[parameters('allowedLocations')]' is type 'Array', expected type is 'String'.'."

Le type attendu de la condition equals est chaîne.The expected type of condition equals is string. Dans la mesure où allowedLocations est défini de type Tableau, le moteur de stratégie évalue l’expression de langage et génère l’erreur.Since allowedLocations is defined as type array, the policy engine evaluates the language expression and throws the error. Avec les conditions in et notIn, le moteur de stratégie attend le type Tableau dans l’expression de langage.With the in and notIn condition, the policy engine expects the type array in the language expression. Pour résoudre ce message d’erreur, remplacez equals par in ou notIn.To resolve this error message, change equals to either in or notIn.

Évaluation de l’alias [*]Evaluating the [*] alias

Les alias ayant [*] attaché à leur nom indiquent que le type est un tableau.Aliases that have [*] attached to their name indicate the type is an array. Au lieu d’évaluer la valeur de l’intégralité du tableau, [*] permet d’en évaluer chaque élément.Instead of evaluating the value of the entire array, [*] makes it possible to evaluate each element of the array. Il existe trois scénarios standards au sein desquels cette évaluation par élément est utile : « None », « Any », et « All ».There are three standard scenarios this per item evaluation is useful in: None, Any, and All. Pour les scénarios complexes, utilisez count.For complex scenarios, use count.

Le moteur de stratégie déclenche l’effet dans then uniquement lorsque la règle if est évaluée comme True.The policy engine triggers the effect in then only when the if rule evaluates as true. Il est important de comprendre ce point dans le contexte de la façon dont [*] évalue chaque élément individuel du tableau.This fact is important to understand in context of the way [*] evaluates each individual element of the array.

L’exemple de règle de stratégie pour la table de scénario ci-dessous :The example policy rule for the scenario table below:

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

Pour la table de scénario ci-dessous, le tableau des ipRules se présente de la façon suivante :The ipRules array is as follows for the scenario table below:

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

Pour chaque exemple de condition ci-dessous, remplacez <field> par "field": "Microsoft.Storage/storageAccounts/networkAcls.ipRules[*].value".For each condition example below, replace <field> with "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 le tableau des valeurs existantes ci-dessus :The following outcomes are the result of the combination of the condition and the example policy rule and array of existing values above:

ConditionCondition RésultatOutcome ExplicationExplanation
{<field>,"notEquals":"127.0.0.1"} RienNothing Un élément du tableau est évalué comme false (127.0.0.1 ! = 127.0.0.1) et un autre comme true (127.0.0.1 ! = 192.168.1.1), donc la condition notEquals est false et l’effet n’est pas déclenché.One array element evaluates as false (127.0.0.1 != 127.0.0.1) and one as true (127.0.0.1 != 192.168.1.1), so the notEquals condition is false and the effect isn't triggered.
{<field>,"notEquals":"10.0.4.1"} Effet de la stratégiePolicy effect Les éléments du tableau sont évalués comme true (10.0.4.1 != 127.0.0.1 et 10.0.4.1 != 192.168.1.1), donc la condition notEquals est true et l’effet est déclenché.Both array elements evaluate as true (10.0.4.1 != 127.0.0.1 and 10.0.4.1 != 192.168.1.1), so the notEquals condition is true and the effect is triggered.
"not":{<field>,"Equals":"127.0.0.1"} Effet de la stratégiePolicy effect Un élément du tableau est évalué comme true (127.0.0.1 == 127.0.0.1) et un autre comme false (127.0.0.1 == 192.168.1.1), donc la condition Equals est false.One array element evaluates as true (127.0.0.1 == 127.0.0.1) and one as false (127.0.0.1 == 192.168.1.1), so the Equals condition is false. L’opérateur logique est évalué comme true (pas false), de sorte que l’effet est déclenché.The logical operator evaluates as true (not false), so the effect is triggered.
"not":{<field>,"Equals":"10.0.4.1"} Effet de la stratégiePolicy effect Les deux éléments du tableau sont évalués comme false (10.0.4.1 == 127.0.0.1 et 10.0.4.1 == 192.168.1.1), donc la condition Equals est false.Both array elements evaluate as false (10.0.4.1 == 127.0.0.1 and 10.0.4.1 == 192.168.1.1), so the Equals condition is false. L’opérateur logique est évalué comme true (pas false), de sorte que l’effet est déclenché.The logical operator evaluates as true (not false), so the effect is triggered.
"not":{<field>,"notEquals":"127.0.0.1" } Effet de la stratégiePolicy effect Un élément du tableau est évalué comme false (127.0.0.1 != 127.0.0.1) et un autre comme true (127.0.0.1 != 192.168.1.1), donc la condition notEquals est false.One array element evaluates as false (127.0.0.1 != 127.0.0.1) and one as true (127.0.0.1 != 192.168.1.1), so the notEquals condition is false. L’opérateur logique est évalué comme true (pas false), de sorte que l’effet est déclenché.The logical operator evaluates as true (not false), so the effect is triggered.
"not":{<field>,"notEquals":"10.0.4.1"} RienNothing Les deux éléments du tableau sont évalués comme false (10.0.4.1 != 127.0.0.1 et 10.0.4.1 != 192.168.1.1), donc la condition notEquals est true.Both array elements evaluate as true (10.0.4.1 != 127.0.0.1 and 10.0.4.1 != 192.168.1.1), so the notEquals condition is true. L’opérateur logique est évalué comme false (pas true), de sorte que l’effet est déclenché.The logical operator evaluates as false (not true), so the effect isn't triggered.
{<field>,"Equals":"127.0.0.1"} RienNothing Un élément du tableau est évalué comme true (127.0.0.1 == 127.0.0.1) et un autre comme true (127.0.0.1 == 192.168.1.1), donc la condition Equals est false et l’effet n’est pas déclenché.One array element evaluates as true (127.0.0.1 == 127.0.0.1) and one as false (127.0.0.1 == 192.168.1.1), so the Equals condition is false and the effect isn't triggered.
{<field>,"Equals":"10.0.4.1"} RienNothing Les deux éléments du tableau sont évalués comme false (10.0.4.1 == 127.0.0.1 et 10.0.4.1 == 192.168.1.1), donc la condition Equals est false et l’effet n’est pas déclenché.Both array elements evaluate as false (10.0.4.1 == 127.0.0.1 and 10.0.4.1 == 192.168.1.1), so the Equals condition is false and the effect isn't triggered.

L’effet Append et les tableauxThe append effect and arrays

L’effet Append se comporte différemment selon que details.field est un alias [*] ou non.The append effect behaves differently depending on if the details.field is a [*] alias or not.

  • Lorsqu’il ne s’agit pas d’un alias [*] , Append remplace le tableau entier avec la propriété valueWhen not a [*] alias, append replaces the entire array with the value property
  • Lorsqu’il s’agit d’un alias [*] , Append ajoute la propriété value au tableau existant ou crée le nouveau tableauWhen a [*] alias, append adds the value property to the existing array or creates the new array

Pour plus d’informations, consultez ces exemples Append.For more information, see the append examples.

Étapes suivantesNext steps