Создание политик для свойств массива ресурсов 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 with parameter 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

Выражение 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').

Условие имеет значение true, только если полученное количество больше 0.

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

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

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

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

Полезные примеры см. в разделе Примеры выражений value count.

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

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

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

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

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

  {
    "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() возвращаемое значение представляет собой массив из содержимого запроса, который затем можно использовать с любыми поддерживаемыми функциями шаблонов, принимающими аргументы массива. Например, следующее условие проверяет, больше ли 0 длина значения stringArray:

{
  "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, так как элемент массива не нарушается. В этом сценарии рекомендуется использовать выражение счетчика. Если массив содержит объекты, псевдоним [*] можно использовать для выбора значения определенного свойства из каждого члена массива. Пример:

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

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

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

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

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

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

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

Выражения field count

Выражение 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в . В частности, в каждой where итерации оценки условия Политика Azure выбирает один член i массива и оценивает содержимое ресурса в отношении where условия, как если бы i это единственный член массива. Наличие только одного элемента массива в каждой итерации позволяет применять сложные условия к каждому отдельному элементу массива.

Пример:

{
  "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 изменяют свойства ресурса в процессе создания или обновления. При работе со свойствами массива поведение этих эффектов зависит от того, пытается ли операция изменить [*] псевдоним.

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

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

Рекомендуется использовать выражения счетчика полей, чтобы проверить, соответствуют ли anyOf allOfчлены массива в содержимом запроса. Для некоторых простых условий можно добиться того же результата, используя метод доступа к полям с псевдонимом массива, как описано в разделе "Ссылка на коллекцию элементов массива". Этот шаблон может быть полезен в правилах политики, превышающих ограничение допустимых 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.