Criar políticas para propriedades de matriz em recursos do Azure

As propriedades do Azure Resource Manager são normalmente definidas como cadeias de caracteres e booleanos. Quando existe uma relação um-para-muitos, as propriedades complexas são definidas como matrizes. Na Política do Azure, as matrizes são usadas de várias maneiras diferentes:

• O tipo de um parâmetro de definição, para fornecer várias opções.
• Parte de uma regra de política usando as condições in ou notIn.
• Parte de uma regra de política que conta quantos membros da matriz satisfazem uma condição.
• No acréscimo e modificar efeitos para atualizar uma matriz existente

Este artigo aborda cada uso pelo Azure Policy e fornece várias definições de exemplo.

Matrizes de parâmetros

Definir uma matriz de parâmetros

Definir um parâmetro como uma matriz permite a flexibilidade da política quando mais de um valor é necessário. Esta definição de política permite qualquer local único para o parâmetro allowedLocations e o padrão é eastus2:

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

Como type foi string, apenas um valor pode ser definido ao atribuir a política. Se essa política for atribuída, os recursos no escopo só serão permitidos em uma única região do Azure. A maioria das definições de políticas precisa permitir uma lista de opções aprovadas, como permitir eastus2, eastus e westus2.

Para criar a definição de política para permitir várias opções, use a matriz type. A mesma política pode ser reescrita da seguinte forma:

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

Essa nova definição de parâmetro usa mais de um valor durante a atribuição de política. Com a propriedade allowedValues array definida, os valores disponíveis durante a atribuição são ainda mais limitados à lista predefinida de opções. O uso de allowedValues é opcional.

Passar valores para uma matriz de parâmetros durante a atribuição

Quando você atribui a política por meio do portal do Azure, um parâmetro de matriz é exibido como uma única caixa de type texto. A dica diz Use ; to separate values. (e.g. London;New York). Para passar os valores de localização permitidos de eastus2, eastus e westus2 para o parâmetro, use a seguinte cadeia de caracteres:

eastus2;eastus;westus2

O formato do valor do parâmetro é diferente ao usar a CLI do Azure, o Azure PowerShell ou a API REST. Os valores são passados através de uma cadeia de caracteres JSON que também inclui o nome do parâmetro.

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

Para usar essa cadeia de caracteres com cada SDK, use os seguintes comandos:

• CLI do Azure: Command az policy assignment create with parameter params.
• Azure PowerShell: cmdlet New-AzPolicyAssignment com parâmetro PolicyParameter.
• API REST: Na operação PUT create como parte do Corpo da Solicitação como o valor da properties.parameters propriedade.

Usando matrizes em condições

Em e nãoEm

As in condições e notIn só funcionam com valores de matriz. Eles verificam a existência de um valor em uma matriz. A matriz pode ser uma matriz JSON literal ou uma referência a um parâmetro de matriz. Por exemplo:

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

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

Contagem de valores

A expressão de contagem de valores conta quantos membros da matriz atendem a uma condição. Ele fornece uma maneira de avaliar a mesma condição várias vezes, usando valores diferentes em cada iteração. Por exemplo, a condição a seguir verifica se o nome do recurso corresponde a qualquer padrão de uma matriz de padrões:

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

Para avaliar a expressão, o Azure Policy avalia a where condição três vezes, uma para cada membro do [ "test*", "dev*", "prod*" ], contando quantas vezes ela foi avaliada para true. Em cada iteração, o valor do membro da matriz atual é emparelhado com o nome do pattern índice definido por count.name. Esse valor pode então ser referenciado dentro da where condição chamando uma função de modelo especial: current('pattern').

A condição só é verdadeira se a contagem resultante for maior que 0.

Para tornar a condição anterior mais genérica, use uma parameters referência em vez de uma matriz literal:

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

Quando a value count expressão não está sob nenhuma outra count expressão, count.name é opcional e a current() função pode ser usada sem argumentos:

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

O value count também suporta matrizes de objetos complexos, permitindo condições mais complexas. Por exemplo, a condição a seguir define um valor de tag desejado para cada padrão de nome e verifica se o nome do recurso corresponde ao padrão, mas não tem o valor de tag necessário:

{
  "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
}

Para obter exemplos úteis, consulte exemplos de contagem de valores.

Fazendo referência às propriedades do recurso da matriz

Muitos casos de uso exigem trabalhar com propriedades de matriz no recurso avaliado. Alguns cenários exigem a referência a uma matriz inteira (por exemplo, verificar seu comprimento). Outros exigem a aplicação de uma condição a cada membro individual da matriz (por exemplo, certifique-se de que todas as regras de firewall bloqueiem o acesso da Internet). Compreender as diferentes maneiras como a Política do Azure pode fazer referência a propriedades de recursos e como essas referências se comportam quando se referem a propriedades de matriz é a chave para escrever condições que abrangem esses cenários.

Fazendo referência às propriedades do recurso

As propriedades do recurso podem ser referenciadas pela Política do Azure usando aliases Há duas maneiras de fazer referência aos valores de uma propriedade de recurso na Política do Azure:

• Use a condição de campo para verificar se todas as propriedades de recurso selecionadas atendem a uma condição. Exemplo:

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

• Use field() a função para acessar o valor de uma propriedade. Exemplo:

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

A condição de campo tem um comportamento implícito allOf . Se o alias representar uma coleção de valores, ele verificará se todos os valores individuais atendem à condição. A field() função retorna os valores representados pelo alias como está, que podem ser manipulados por outras funções de modelo.

Referenciando campos de matriz

As propriedades do recurso de matriz são representadas por dois tipos diferentes de aliases. Um alias normal e aliases de matriz que foram [*] anexados a ele:

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

Fazendo referência à matriz

O primeiro alias representa um único valor, o valor da propriedade do conteúdo da stringArray solicitação. Como o valor dessa propriedade é uma matriz, ela não é útil em condições de política. Por exemplo:

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

Essa condição compara a matriz inteira stringArray a um único valor de cadeia de caracteres. A maioria das condições, incluindo equals, só aceita valores de cadeia de caracteres, portanto, não há muito uso em comparar uma matriz com uma cadeia de caracteres. O cenário principal em que a referência à propriedade array é útil é ao verificar se ela existe:

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

Com a field() função, o valor retornado é a matriz do conteúdo da solicitação, que pode ser usada com qualquer uma das funções de modelo suportadas que aceitam argumentos de matriz. Por exemplo, a condição a seguir verifica se o comprimento de stringArray é maior que 0:

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

Fazendo referência à coleção de membros da matriz

Os aliases que usam a [*] sintaxe representam uma coleção de valores de propriedade selecionados de uma propriedade de matriz, que é diferente de selecionar a própria propriedade de matriz. Por exemplo, Microsoft.Test/resourceType/stringArray[*] retorna uma coleção que tem todos os membros stringArraydo . Como mencionado anteriormente, uma field condição verifica se todas as propriedades de recurso selecionadas atendem à condição, portanto, a condição a seguir é verdadeira somente se todos os membros de stringArray forem iguais a "value".

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

Se a matriz estiver vazia, a condição será avaliada como true porque nenhum membro da matriz está em violação. Nesse cenário, a recomendação é usar a expressão count em vez disso. Se a matriz contiver objetos, um [*] alias pode ser usado para selecionar o valor de uma propriedade específica de cada membro da matriz. Exemplo:

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

Esta condição é verdadeira se os valores de todas as property propriedades em objectArray forem iguais a "value". Para obter mais exemplos, consulte Mais exemplos de alias.

Ao usar a field() função para fazer referência a um alias de matriz, o valor retornado é uma matriz de todos os valores selecionados. Esse comportamento significa que o caso de uso comum da função, a capacidade de aplicar funções de modelo a valores de propriedade de field() recurso, é limitado. As únicas funções de modelo que podem ser usadas neste caso são aquelas que aceitam argumentos de matriz. Por exemplo, é possível obter o comprimento da matriz com [length(field('Microsoft.Test/resourceType/objectArray[*].property'))]. No entanto, cenários mais complexos, como aplicar a função de modelo a cada membro da matriz e compará-la com um valor desejado, só são possíveis ao usar a count expressão. Para obter mais informações, consulte Expressão de contagem de campos.

Para resumir, consulte o seguinte exemplo de conteúdo de recurso e os valores selecionados retornados por vários aliases:

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

Quando você usa a condição de campo no conteúdo do recurso de exemplo, os resultados são os seguintes:

Quando você usa a field() função no conteúdo do recurso de exemplo, os resultados são os seguintes:

Expressões de contagem de campos

As expressões de contagem de campos contam quantos membros da matriz atendem a uma condição e comparam a contagem com um valor de destino. Count é mais intuitivo e versátil para avaliar matrizes em comparação com field as condições. A sintaxe é:

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

Quando usado sem uma where condição, count simplesmente retorna o comprimento de uma matriz. Com o conteúdo do recurso de exemplo da seção anterior, a expressão a seguir count é avaliada para true desde que stringArray tem três membros:

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

Esse comportamento também funciona com matrizes aninhadas. Por exemplo, a expressão a seguir count é avaliada como true uma vez que há quatro membros de nestedArray matriz nas matrizes:

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

O poder de count está na where condição. Quando count é especificado, o Azure Policy enumera os membros da matriz e avalia cada um em relação à condição, contando quantos membros da matriz avaliaram para true. Especificamente, em cada iteração da avaliação de condição, a where Política do Azure seleciona um único membro i da matriz e avalia o conteúdo do recurso em relação à where condição como se i fosse o único membro da matriz. Ter apenas um membro de array disponível em cada iteração fornece uma maneira de aplicar condições complexas em cada membro individual da matriz.

Exemplo:

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

Para avaliar a expressão, o count Azure Policy avalia a where condição três vezes, uma para cada membro do stringArray, contando quantas vezes ela foi avaliada para true. Quando a where condição se refere aos Microsoft.Test/resourceType/stringArray[*] membros da matriz, em vez de selecionar todos os membros do , ela seleciona apenas um único membro da stringArraymatriz toda vez:

Os count retornos 1.

Aqui está uma expressão mais complexa:

{
  "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
}

Os count retornos 1.

O fato de a where expressão ser avaliada em relação a todo o conteúdo da solicitação (com alterações apenas no membro da matriz que está sendo enumerado no momento) significa que a where condição também pode se referir a campos fora da matriz:

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

As expressões de contagem aninhada podem ser usadas para aplicar condições a campos de matriz aninhados. Por exemplo, a condição a seguir verifica se a objectArray[*] matriz tem exatamente dois membros com nestedArray[*] um ou mais membros:

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

Como ambos os membros têm uma matriz nestedArray[*] filho objectArray[*] com dois membros, a expressão de contagem externa retorna 2.

Exemplo mais complexo: verifique se a objectArray[*] matriz tem exatamente dois membros com nestedArray[*] membros iguais ou 2 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
}

Como ambos os membros do objectArray[*] têm uma matriz nestedArray[*] filho que contém ou 32 , a expressão de contagem externa retorna 2.

Acessando o membro da matriz atual com funções de modelo

Ao usar funções de modelo, use a current() função para acessar o valor do membro da matriz atual ou os valores de qualquer uma de suas propriedades. Para acessar o valor do membro da matriz atual, passe o alias definido ou count.field qualquer um de seus aliases filho como um argumento para a current() função. Por exemplo:

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

A função de campo dentro de onde as condições

A field() função também pode ser usada para acessar o valor do membro da matriz atual, desde que a expressão count não esteja dentro de uma condição de existência (field() função sempre se refere ao recurso avaliado na condição if ). O comportamento de field() quando se refere à matriz avaliada baseia-se nos seguintes conceitos:

• Os aliases de matriz são resolvidos em uma coleção de valores selecionados de todos os membros da matriz.
• field() As funções que fazem referência a aliases de matriz retornam uma matriz com os valores selecionados.
• A referência ao alias da matriz contada dentro da where condição retorna uma coleção com um único valor selecionado do membro da matriz que é avaliado na iteração atual.

Esse comportamento significa que, ao se referir ao membro da matriz contada com uma field() função dentro da where condição, ele retorna uma matriz com um único membro. Embora esse comportamento possa não ser intuitivo, é consistente com a ideia de que os aliases de matriz sempre retornam uma coleção de propriedades selecionadas. Eis um exemplo:

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

Portanto, quando há a necessidade de acessar o valor do alias de matriz contada com uma field() função, a maneira de fazer isso é envolvê-lo com uma first() função de modelo:

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

Para obter exemplos úteis, consulte Exemplos de contagem de campos.

Modificando matrizes

O acréscimo e a modificação alteram propriedades em um recurso durante a criação ou atualização. Quando você trabalha com propriedades de matriz, o comportamento desses efeitos depende se a operação está tentando modificar o [*] alias ou não:

Para obter mais informações, consulte os exemplos de acréscimo.

Mais exemplos de alias

A recomendação é usar as expressões de contagem de campos para verificar se allOfou anyOf os membros de uma matriz no conteúdo da solicitação atendem a uma condição. Para algumas condições simples, é possível obter o mesmo resultado usando um acessador de campo com um alias de matriz, conforme descrito em Referenciando a coleção de membros da matriz. Esse padrão pode ser útil em regras de política que excedem o limite de expressões permitidas count . Aqui estão exemplos de casos de uso comuns:

A regra de política de exemplo para a tabela de cenários a seguir:

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

A ipRules matriz é a seguinte para a tabela de cenários a seguir:

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

Para cada um dos exemplos de condição a seguir, substitua <field> por "field": "Microsoft.Storage/storageAccounts/networkAcls.ipRules[*].value".

Os resultados a seguir são o resultado da combinação da condição e da regra de política de exemplo e da matriz de valores existentes anteriores:

Próximos passos

• Analise exemplos em Exemplos de Política do Azure.
• Reveja a estrutura de definição do Azure Policy.
• Veja Compreender os efeitos do Policy.
• Entenda como criar políticas de forma programática.
• Saiba como corrigir recursos não compatíveis.
• Analise o que é um grupo de gerenciamento com Organize seus recursos com grupos de gerenciamento do Azure.