Creación de directivas para propiedades de matriz en recursos de AzureAuthor policies for array properties on Azure resources

Las propiedades de Azure Resource Manager se suelen definir como cadenas y valores booleanos.Azure Resource Manager properties are commonly defined as strings and booleans. En cambio, cuando existe una relación uno a varios, las propiedades complejas se definen como matrices.When a one-to-many relationship exists, complex properties are instead defined as arrays. En Azure Policy, las matrices se usan de varias maneras diferentes:In Azure Policy, arrays are used in several different ways:

  • Tipo de un parámetro de definición, para proporcionar varias opcionesThe type of a definition parameter, to provide multiple options
  • Parte de una regla de directiva con las condiciones in o notInPart of a policy rule using the conditions in or notIn
  • Parte de una regla de directiva que evalúa el alias [*] para evaluar:Part of a policy rule that evaluates the [*] alias to evaluate:
    • Escenarios como Ninguno, Cualquiera o TodoScenarios such as None, Any, or All
    • Escenarios complejos con countComplex scenarios with count
  • En el efecto append, para reemplazar o agregar a una matriz existenteIn the append effect to replace or add to an existing array

En este artículo se explica cada uso por parte de Azure Policy y proporciona varias definiciones de ejemplo.This article covers each use by Azure Policy and provides several example definitions.

Matrices de parámetrosParameter arrays

Definir una matriz de parámetrosDefine a parameter array

Definir un parámetro como una matriz, permite la flexibilidad de la directiva cuando se necesita más de un valor.Defining a parameter as an array allows the policy flexibility when more than one value is needed. Esta definición de directiva permite cualquier ubicación única para el parámetro allowedLocations y el valor predeterminado es 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"
    }
}

Como type es string, solo se puede establecer un único valor al asignar la directiva.As type was string, only one value can be set when assigning the policy. Si se asigna esta directiva, los recursos del ámbito solo se permiten en una única región de Azure.If this policy is assigned, resources in scope are only allowed within a single Azure region. La mayoría de las definiciones de directivas deben permitir una lista de opciones aprobadas, como permitir eastus2, eastus y westus2.Most policies definitions need to allow for a list of approved options, such as allowing eastus2, eastus, and westus2.

Para crear la definición de directiva a fin de permitir varias opciones, utilice el elemento type array.To create the policy definition to allow multiple options, use the array type. La misma directiva se puede reescribir del siguiente modo: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"
        ]

    }
}

Nota

Una vez que se guarda una definición de directiva, no se puede cambiar la propiedad type en un parámetro.Once a policy definition is saved, the type property on a parameter can't be changed.

Esta nueva definición de parámetro toma más de un valor durante la asignación de directiva.This new parameter definition takes more than one value during policy assignment. Con la propiedad de matriz allowedValues definida, los valores disponibles durante la asignación se limitan más a la lista predefinida de opciones.With the array property allowedValues defined, the values available during assignment are further limited to the predefined list of choices. El uso de allowedValues es opcional.Use of allowedValues is optional.

Pasar valores a una matriz de parámetros durante la asignaciónPass values to a parameter array during assignment

Al asignar la directiva a través de Azure Portal, un parámetro de type array se muestra como un único cuadro de texto.When assigning the policy through the Azure portal, a parameter of type array is displayed as a single textbox. La sugerencia indica "Use ; para separar los valoresThe hint says "Use ; to separate values. (por ejemplo, Londres;Nueva York)".(e.g. London;New York)". Para pasar los valores de ubicación permitidos eastus2, eastus y westus2 al parámetro, use la siguiente cadena:To pass the allowed location values of eastus2, eastus, and westus2 to the parameter, use the following string:

eastus2;eastus;westus2

El formato para el valor del parámetro es distinto cuando se usa la CLI de Azure, Azure PowerShell o la API de REST.The format for the parameter value is different when using Azure CLI, Azure PowerShell, or the REST API. Los valores se pasan a través de una cadena JSON que también incluye el nombre del parámetro.The values are passed through a JSON string that also includes the name of the parameter.

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

Para usar esta cadena con cada SDK, use los siguientes comandos:To use this string with each SDK, use the following commands:

  • CLI de Azure: Comando az policy assignment create con el parámetro paramsAzure CLI: Command az policy assignment create with parameter params
  • Azure PowerShell: Cmdlet New AzPolicyAssignment con el parámetro PolicyParameterAzure PowerShell: Cmdlet New-AzPolicyAssignment with parameter PolicyParameter
  • API REST: en la operación PUT create como parte del cuerpo de la solicitud, como el valor de la propiedad properties.parametersREST API: In the PUT create operation as part of the Request Body as the value of the properties.parameters property

Matrices y reglas de directivaPolicy rules and arrays

Condiciones de matrizArray conditions

Las condiciones de la regla de directiva con la que puede usarse array type del parámetro están limitadas a in y notIn.The policy rule conditions that an array type of parameter may be used with is limited to in and notIn. Tome la siguiente definición de directiva con la condición equals como ejemplo: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"
      }
    }
  }
}

Al intentar crear esta definición de directiva a través de Azure Portal genera un error, como este mensaje de error:Attempting to create this policy definition through the Azure portal leads to an error such as this error message:

  • "No se pudo parametrizar la directiva '{GUID}' por errores de validación."The policy '{GUID}' could not be parameterized because of validation errors. Compruebe si los parámetros de la directiva están definidos correctamente.Please check if policy parameters are properly defined. La excepción interna 'El resultado de la evaluación de la expresión de lenguaje '[parameters('allowedLocations')]' es de tipo 'Matriz'. El tipo esperado es 'String'".The inner exception 'Evaluation result of language expression '[parameters('allowedLocations')]' is type 'Array', expected type is 'String'.'."

El elemento type esperado de la condición equals es string.The expected type of condition equals is string. Puesto que allowedLocations se define como type array, el motor de directiva evalúa la expresión de lenguaje y genera el error.Since allowedLocations is defined as type array, the policy engine evaluates the language expression and throws the error. Con la condición in y notIn, el motor de directiva espera el elemento type array en la expresión de lenguaje.With the in and notIn condition, the policy engine expects the type array in the language expression. Para resolver este mensaje de error, cambie equals a in o notIn.To resolve this error message, change equals to either in or notIn.

Evaluación del alias [*]Evaluating the [*] alias

Los alias que tienen [*] adjuntado a sus nombres indican que type es una matriz.Aliases that have [*] attached to their name indicate the type is an array. En lugar de evaluar el valor de toda la matriz, [*] permite evaluar los elementos de la matriz individualmente, con el operador lógico AND entre ellos.Instead of evaluating the value of the entire array, [*] makes it possible to evaluate each element of the array individually, with logical AND between them. Hay tres escenarios estándar en que la evaluación por elemento es útil: la coincidencia de ninguno, alguno o todos los elementos.There are three standard scenarios this per item evaluation is useful in: None, Any, or All elements match. Para escenarios complejos, use count.For complex scenarios, use count.

El motor de directiva desencadena effect en then solo cuando la regla if se evalúa como true.The policy engine triggers the effect in then only when the if rule evaluates as true. Este hecho es importante para comprender en contexto la manera en que [*] evalúa cada elemento individual de la matriz.This fact is important to understand in context of the way [*] evaluates each individual element of the array.

La regla de directiva siguiente es un ejemplo para la tabla de escenario: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')]"
    }
}

La matriz ipRules es como sigue para la tabla de escenario: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"
    }
]

Para cada ejemplo de condición siguiente, reemplace <field> por "field": "Microsoft.Storage/storageAccounts/networkAcls.ipRules[*].value".For each condition example below, replace <field> with "field": "Microsoft.Storage/storageAccounts/networkAcls.ipRules[*].value".

Los siguientes resultados se derivan de la combinación de la condición y la regla de directiva de ejemplo y la matriz de valores existentes anteriores:The following outcomes are the result of the combination of the condition and the example policy rule and array of existing values above:

CondiciónCondition ResultadoOutcome EscenarioScenario ExplicaciónExplanation
{<field>,"notEquals":"127.0.0.1"} NadaNothing Ninguna coincidenciaNone match Un elemento de matriz se evalúa como false (127.0.0.1 != 127.0.0.1) y otro como true (127.0.0.1 != 192.168.1.1), por lo que la condición notEquals es false y el efecto no se desencadena.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"} Efecto de la directivaPolicy effect Ninguna coincidenciaNone match Ambos elementos de matriz se evalúan como true (10.0.4.1 != 127.0.0.1 and 10.0.4.1 != 192.168.1.1), por lo que la condición notEquals es true y el efecto se desencadena.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>,"notEquals":"127.0.0.1" } Efecto de la directivaPolicy effect Una o más coincidenciasOne or more match Un elemento de matriz se evalúa como false (127.0.0.1 != 127.0.0.1) y otro como true (127.0.0.1 != 192.168.1.1), por lo que la condición notEquals es 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. El operador lógico se evalúa como true (not false), por lo que se desencadena el efecto.The logical operator evaluates as true (not false), so the effect is triggered.
"not":{<field>,"notEquals":"10.0.4.1"} NadaNothing Una o más coincidenciasOne or more match Ambos elementos de matriz se evalúan como true (10.0.4.1 != 127.0.0.1 y 10.0.4.1 != 192.168.1.1), por lo que la condición notEquals es 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. El operador lógico se evalúa como false (not true), por lo que no se desencadena el efecto.The logical operator evaluates as false (not true), so the effect isn't triggered.
"not":{<field>,"Equals":"127.0.0.1"} Efecto de la directivaPolicy effect Coincidencia parcialNot all match Un elemento de matriz se evalúa como true (127.0.0.1 == 127.0.0.1) y otro como false (127.0.0.1 == 192.168.1.1), por lo que la condición Equals es 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. El operador lógico se evalúa como true (not false), por lo que se desencadena el efecto.The logical operator evaluates as true (not false), so the effect is triggered.
"not":{<field>,"Equals":"10.0.4.1"} Efecto de la directivaPolicy effect Coincidencia parcialNot all match Ambos elementos de matriz se evalúan como false (10.0.4.1 == 127.0.0.1 y 10.0.4.1 == 192.168.1.1), por lo que la condición Equals es 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. El operador lógico se evalúa como true (not false), por lo que se desencadena el efecto.The logical operator evaluates as true (not false), so the effect is triggered.
{<field>,"Equals":"127.0.0.1"} NadaNothing Coincidencia totalAll match Un elemento de matriz se evalúa como true (127.0.0.1 == 127.0.0.1) y otro como false (127.0.0.1 == 192.168.1.1), por lo que la condición Equals es false y el efecto no se desencadena.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"} NadaNothing Coincidencia totalAll match Ambos elementos de matriz se evalúan como false (10.0.4.1 == 127.0.0.1 y 10.0.4.1 == 192.168.1.1), por lo que la condición Equals es false y el efecto no se desencadena.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.

El efecto de anexar y matricesThe append effect and arrays

El efecto append se comporta de manera diferente en función de si details.field es un alias [*] o no.The append effect behaves differently depending on if the details.field is a [*] alias or not.

  • Cuando no es un alias [*] , append reemplaza toda la matriz por la propiedad value.When not a [*] alias, append replaces the entire array with the value property
  • Cuando se trata de un alias [*] , append agrega la propiedad value a la matriz existente o crea una nueva matriz.When a [*] alias, append adds the value property to the existing array or creates the new array

Para obtener más información, consulte Ejemplos de append.For more information, see the append examples.

Pasos siguientesNext steps