Правила создания политик для свойств массивов ресурсов Azure

Свойства Azure Resource Manager обычно определяются как строки и логические значения. Если существует связь "один ко многим", то сложные свойства определяются как массивы. В Политике Azure массивы используются несколькими различными способами:

• Тип параметра определения, который предоставляет несколько вариантов.
• Часть правила политики, использующего условия in или notIn.
• Часть правила политики, которая подсчитывает количество элементов массива, удовлетворяющих условию.
• в эффектах добавления и изменения для обновления существующего массива.

В этой статье рассматривается каждый вариант использования в Политике Azure и приводится несколько примеров определений.

Массивы параметров

Определение массива параметров

Определение параметра в качестве массива обеспечивает гибкость политики, если требуется более одного значения. Это определение политики позволяет использовать любое отдельное расположение для параметра allowedLocations и по умолчанию — eastus2:

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

Так как type была строкой, при назначении политики можно задать только одно значение. При назначении этой политики ресурсы в области допускаются только в пределах одного региона Azure. Большинство определений политик должно допускать список утвержденных параметров, например eastus2, eastus и westus2.

Для создания определения политики, чтобы разрешить несколько вариантов, используйте массивtype. Эту же политику можно переписать следующим образом:

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

Это новое определение параметра принимает более одного значения во время назначения политики. При определении свойства allowedValues массива значения, доступные во время назначения, также ограничиваются предопределенным списком вариантов. allowedValues Использование является необязательным.

Передача значений в массив параметров во время назначения

При назначении политики через портал Azure параметр массива отображается в виде одного текстового typeполя. Подсказка указывает Use ; to separate values. (e.g. London;New York). Чтобы передать допустимые значения расположения eastus2, eastus и westus2 в параметр, используйте следующую строку:

eastus2;eastus;westus2

Формат значения параметра различается при использовании Azure CLI, Azure PowerShell или REST API. Значения передаются в строке JSON, которая также содержит имя параметра.

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

Чтобы использовать эту строку с каждым пакетом SDK, выполните следующие команды:

• Azure CLI: команда az policy assignment create с параметром params.
• Azure PowerShell: использование командлета New-AzPolicyAssignment с параметром PolicyParameter.
• REST API: в операции PUT создания в составе тела запроса в качестве значения свойства properties.parameters.

Использование массивов в условиях

In и notIn

Условия in и notIn работают только со значениями массива. Они проверяют существование значения в массиве. Массивом может быть литеральный массив JSON или ссылка на параметр массива. Например:

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

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

Число значений

Выражение value count показывает, сколько элементов массива соответствуют условию. Оно позволяет вычислять одно и то же условие несколько раз, используя при каждой итерации разные значения. Например, следующее условие проверяет, соответствует ли имя ресурса какому-либо шаблону из массива шаблонов:

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

Чтобы оценить выражение, политика Azure оценивает условие where три раза, один раз для каждого элемента [ "test*", "dev*", "prod*" ], и подсчитывает, сколько раз результат был равен true. При каждой итерации значение текущего элемента массива сопоставляется с именем индекса pattern, определенным параметром count.name. На это значение можно ссылаться в условии where, вызывая специальную функцию шаблона: current('pattern').

Условие истинно, только если результирующее количество больше 0.

Чтобы сделать предыдущее условие более универсальным, используйте ссылку parameters вместо литерального массива:

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

value count Если выражение не находится под другим count выражением, count.name является необязательным и функция current() может использоваться без каких-либо аргументов:

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

value count также поддерживает массивы сложных объектов, что позволяет создавать более сложные условия. Например, следующее условие определяет желаемое значение тега для каждого шаблона имен и проверяет, соответствует ли имя ресурса шаблону, но не включает требуемое значение тега:

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

Полезные примеры см. в разделе примеры подсчета значений.

Ссылки на свойства ресурсов массива

Во многих вариантах использования требуется работа со свойствами массива в оцениваемом ресурсе. Для некоторых сценариев требуется ссылка на весь массив (например, проверка его длины). Другие требуют применения условия к каждому отдельному элементу массива (например, проверки того, что все правила брандмауэра блокируют доступ из Интернета). Основные сведения о различных способах, с помощью которых Политика Azure может ссылаться на свойства ресурсов, а также о том, как эти ссылки ведут себя, когда ссылаются на свойства массива, являются ключом к написанию условий для подобных сценариев.

Ссылка на свойства ресурсов

Azure Policy может ссылаться на свойства ресурсов, используя псевдонимы. Ссылаться на значения свойства ресурса в Azure Policy можно двумя способами:

• Используйте условие поля , чтобы проверить, соответствуют ли все выбранные свойства ресурса условию. Пример:

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

• Использовать функцию field() для доступа к значению свойства. Пример:

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

Условие поля имеет неявное allOf поведение. Если псевдоним представляет коллекцию значений, он проверяет, соответствуют ли условию все отдельные значения. Функция field() возвращает значения, представляемые псевдонимом, без изменений — после этого ими могут управлять другие функции шаблонов.

Обращение к полям массивов

Свойства ресурсов массива представлены псевдонимами двух типов. Один обычный псевдоним и псевдонимы массива, которые к нему присоединены:

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

Ссылка на массив

Первый псевдоним представляет одно значение — значение свойства stringArray из содержимого запроса. Так как значение этого свойства является массивом, оно не представляет пользы в условиях политики. Например:

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

Это условие сравнивает весь массив stringArray с одним строковым значением. Большинство условий, включая equals, принимают только строковые значения, поэтому от сравнения массива со строкой пользы мало. Ссылка на свойство массива полезна в основном для проверки его существования:

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

При использовании функции field() возвращаемое значение представляет собой массив из содержимого запроса, который затем можно использовать с любыми поддерживаемыми функциями шаблонов, принимающими аргументы массива. Например, следующее условие проверяет, больше ли длина stringArray 0:

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

Ссылка на коллекцию элементов массива

Псевдонимы, использующие синтаксис [*], представляют собой коллекцию значений свойств, выбранных из массива, что отличается от выбора всего массива как свойства. Например, Microsoft.Test/resourceType/stringArray[*] возвращает коллекцию, в которую входят все члены stringArray. Как упоминалось ранее, field условие проверяет, соответствует ли все выбранные свойства ресурса условию, поэтому следующее условие имеет значение true, только если все члены stringArray равны "value".

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

Если массив пуст, условие оценивается как true, так как элемент массива не нарушается. В этом сценарии рекомендуется использовать выражение count вместо этого. Если массив содержит объекты, псевдоним [*] можно использовать для выбора значения определенного свойства из каждого члена массива. Пример:

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

Это условие имеет значение true, если значения всех свойств property в objectArray равны значению параметра "value". Для большего количества примеров см. Дополнительные примеры псевдонимов.

При использовании функции field() для ссылки на псевдоним массива возвращаемое значение является массивом всех выбранных значений. Такое поведение означает, что основной способ использования функции field(), способность применять функции шаблонов к значениям свойств ресурсов, ограничен. В этом случае можно использовать только те функции шаблона, которые принимают аргументы массива. Например, с помощью функции [length(field('Microsoft.Test/resourceType/objectArray[*].property'))] можно получить длину массива. Однако более сложные сценарии, такие как применение функции шаблона к каждому элементу массива и его сравнение с нужным значением, возможны только при использовании выражения count. Дополнительную информацию см. в разделе Field count expression.

Чтобы подвести итог, рассмотрим следующий пример содержимого ресурса и выбранных значений, возвращаемых различными псевдонимами:

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

При использовании условия поля в примере содержимого ресурса результаты приведены следующим образом:

При использовании field() функции в примере содержимого ресурса результаты приведены следующим образом:

Выражения подсчета полей

Выражение field count подсчитывает, сколько элементов массива соответствуют условию, и сравнивает их количество с целевым значением. Выражение Count более интуитивно понятно и универсально для оценки массивов, чем условия field. Синтаксис:

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

При использовании без условия where выражение count просто возвращает длину массива. Учитывая содержимое ресурса из предыдущего раздела, следующее выражение count оценивается как true, так как stringArray содержит три элемента.

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

Это поведение работает и с вложенными массивами. Например, следующее выражение count получает значение true, так как в массиве nestedArray четыре элемента:

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

Сила count заключается в условии where. Когда задан count, политики Azure перечисляют элементы массива и оценивают каждый по условию, подсчитывая количество элементов массива, оцененных в true. В частности, при каждой итерации оценки условия Политика Azure выбирает один член массива и оценивает содержимое ресурса относительно условия , как если бы был единственным членом массива . Наличие только одного элемента массива в каждой итерации позволяет применять сложные условия к каждому отдельному элементу массива.

Пример:

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

Чтобы оценить выражение count, Политика Azure оценивает условие where три раза, по одному для каждого элемента stringArray, и подсчитывает, сколько раз было получено значение true. where Если условие ссылается на Microsoft.Test/resourceType/stringArray[*] элементы массива, вместо выбора всех элементов stringArrayон выбирает только один элемент массива каждый раз:

Выражение count возвращает значение 1.

Возьмем более сложное выражение:

{
  "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 возвращает значение 1.

Тот факт, что выражение where сравнивается со всем содержимым запроса (изменения вносятся только в тот элемент массива, который перечисляется в данный момент), означает, что условие where также может ссылаться на поля за пределами массива:

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

Вложенные выражения подсчета можно использовать для применения условий к вложенным полям массива. Например, следующее условие проверяет, действительно ли массив objectArray[*] содержит ровно два элемента со значением nestedArray[*], содержащим один или несколько элементов:

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

Поскольку оба элемента objectArray[*] имеют дочерний массив nestedArray[*] с двумя элементами, внешнее выражение count возвращает значение 2.

Более сложный пример: убедимся, что массив objectArray[*] содержит ровно два элемента и значение nestedArray[*] любого элемента равно 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
}

Поскольку оба элемента objectArray[*] имеют дочерний массив nestedArray[*], который содержит 2 или 3, внешнее выражение count возвращает значение 2.

Доступ к текущему элементу массива с помощью функций шаблона

При использовании функций шаблона используйте функцию current() для доступа к значению текущего элемента массива или значениям любого из его свойств. Чтобы получить доступ к значению текущего элемента массива, передайте псевдоним, определенный в count.field, или один из его дочерних псевдонимов как аргумент функции current(). Например:

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

Функция field внутри условий where

Функцию field() можно также использовать для доступа к значению текущего элемента массива, если выражение count не находится внутри условия существования (функция field() всегда ссылается на ресурс, вычисляемый в условии if). Поведение функции field() при ссылке на вычисляемый массив основано на следующих понятиях.

• Псевдонимы массивов сводятся к коллекции значений, выбранных из всех элементов массива.
• Функции field(), ссылающиеся на псевдонимы массивов, возвращают массив с выбранными значениями.
• Ссылка на подсчитанный псевдоним массива в условии where возвращает коллекцию с единственным значением, выбранным из элемента массива, который оценивается в текущей итерации.

Это означает, что при ссылке на вычисляемый элемент массива с функцией field() внутри условия whereона возвращает массив с одним элементом. Хотя это поведение может быть не интуитивно понятным, оно согласуется с идеей, что псевдонимы массива всегда возвращают коллекцию выбранных свойств. Приведем пример:

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

Таким образом, при необходимости доступа к значению счётного псевдонима массива с функцией field(), способ решения этой задачи заключается в его обёртывании с помощью функции шаблона first().

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

См. примеры в разделе Field count.

Изменение массивов

Свойства append и modify изменяют свойства ресурса в процессе создания или обновления. При работе со свойствами массива поведение этих эффектов зависит от того, пытается ли операция изменить [*] псевдоним.

Дополнительные сведения см. в примерах добавления.

Дополнительные примеры псевдонимов

Рекомендуется использовать выражения для подсчета количества полей, чтобы проверить, соответствуют ли члены массива в содержимом запроса определенным условиям. Для некоторых простых условий можно добиться того же результата, используя аксессор полей с алиасом массива, как описано в разделе "Ссылка на коллекцию элементов массива". Этот шаблон может быть полезен в правилах политики, превышающих ограничение допустимых count выражений. Ниже приводятся примеры распространенных вариантов использования.

Пример правила политики для следующей таблицы сценариев:

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

Массив ipRules выглядит следующим образом в следующей таблице сценариев:

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

Для каждого из следующих примеров условий замените <field> на "field": "Microsoft.Storage/storageAccounts/networkAcls.ipRules[*].value".

Следующие результаты являются результатом сочетания условия и примера правила политики и массива предыдущих существующих значений:

Следующие шаги

• Изучите примеры на странице примеров Политики Azure.
• Изучите статью о структуре определения Политики Azure.
• Изучите сведения о действии политик.
• Узнайте о программном создании политик.
• Узнайте, как исправлять несоответствующие ресурсы.
• Дополнительные сведения о группе управления см. в статье Упорядочивание ресурсов с помощью групп управления Azure.