Функции объектов для шаблонов ARM

Статья
02/06/2024

Resource Manager предоставляет ряд функций для работы с объектами в шаблоне Azure Resource Manager (шаблон ARM).

contains
createObject
empty
intersection
items
json
length
NULL
union

Совет

Мы рекомендуем использовать Bicep, так как он предоставляет те же возможности, что и шаблоны ARM, и имеет более простой синтаксис. Дополнительные сведения см. в функциях объектов.

содержит

contains(container, itemToFind)

Проверяет, содержит ли массив значение, содержит ли объект ключ или содержит ли строка подстроку. При сравнении строк учитывается регистр. Тем не менее при проверке объекта на наличие ключа сравнение выполняется без учета регистра.

В Bicep используйте функцию contains.

Параметры

Параметр	Обязательное поле	Type	Описание
контейнер	Да	массив, объект или строка	Значение, содержащее значение, которое необходимо найти.
itemToFind	Да	строка или целое число	Значение, которое необходимо найти.

Возвращаемое значение

True, если элемент найден. В противном случае — False.

Пример

В следующем примере показано, как использовать функцию contains с различными типами:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "stringToTest": {
      "type": "string",
      "defaultValue": "OneTwoThree"
    },
    "objectToTest": {
      "type": "object",
      "defaultValue": {
        "one": "a",
        "two": "b",
        "three": "c"
      }
    },
    "arrayToTest": {
      "type": "array",
      "defaultValue": [ "one", "two", "three" ]
    }
  },
  "resources": [
  ],
  "outputs": {
    "stringTrue": {
      "type": "bool",
      "value": "[contains(parameters('stringToTest'), 'e')]"
    },
    "stringFalse": {
      "type": "bool",
      "value": "[contains(parameters('stringToTest'), 'z')]"
    },
    "objectTrue": {
      "type": "bool",
      "value": "[contains(parameters('objectToTest'), 'one')]"
    },
    "objectFalse": {
      "type": "bool",
      "value": "[contains(parameters('objectToTest'), 'a')]"
    },
    "arrayTrue": {
      "type": "bool",
      "value": "[contains(parameters('arrayToTest'), 'three')]"
    },
    "arrayFalse": {
      "type": "bool",
      "value": "[contains(parameters('arrayToTest'), 'four')]"
    }
  }
}

Выходные данные из предыдущего примера со значениями по умолчанию:

Имя.	Тип	значение
stringTrue	Bool	Истина
stringFalse	Bool	False
objectTrue	Bool	Истина
objectFalse	Bool	False
arrayTrue	Bool	Истина
arrayFalse	Bool	False

createObject

createObject(key1, value1, key2, value2, ...)

Создает объект из ключей и значений.

Функция createObject не поддерживается в Bicep. Создайте объект с помощью {}. См. раздел Объекты.

Параметры

Параметр	Обязательное поле	Type	Описание
key1	Нет	строка	Имя ключа.
value1	No	целочисленное значение, логическое значение, строка, объект или массив	Значение для ключа.
дополнительные ключи	Нет	строка	Дополнительные имена ключей.
дополнительные значения	No	целочисленное значение, логическое значение, строка, объект или массив	Дополнительные значения для ключей.

Функция принимает только четное количество параметров. У каждого ключа должно быть соответствующее значение.

Возвращаемое значение

Объект с каждой парой "ключ — значение".

Пример

В следующем примере создается объект из различных типов значений.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "resources": [
  ],
  "outputs": {
    "newObject": {
      "type": "object",
      "value": "[createObject('intProp', 1, 'stringProp', 'abc', 'boolProp', true(), 'arrayProp', createArray('a', 'b', 'c'), 'objectProp', createObject('key1', 'value1'))]"
    }
  }
}

Выходные данные из предыдущего примера со значениями по умолчанию — объект с именем newObject со следующим значением.

{
  "intProp": 1,
  "stringProp": "abc",
  "boolProp": true,
  "arrayProp": ["a", "b", "c"],
  "objectProp": {"key1": "value1"}
}

empty

empty(itemToTest)

Определяет, являются ли пустыми массив, объект или строка.

В Bicep используйте функцию empty.

Параметры

Параметр	Обязательное поле	Type	Описание
itemToTest	Да	массив, объект или строка	Значение, которое необходимо проверить на наличие содержимого.

Возвращаемое значение

Возвращает результат True, если значение пустое. В противном случае — False.

Пример

В следующем примере проверяется, являются ли пустыми массив, объект и строка.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "testArray": {
      "type": "array",
      "defaultValue": []
    },
    "testObject": {
      "type": "object",
      "defaultValue": {}
    },
    "testString": {
      "type": "string",
      "defaultValue": ""
    }
  },
  "resources": [
  ],
  "outputs": {
    "arrayEmpty": {
      "type": "bool",
      "value": "[empty(parameters('testArray'))]"
    },
    "objectEmpty": {
      "type": "bool",
      "value": "[empty(parameters('testObject'))]"
    },
    "stringEmpty": {
      "type": "bool",
      "value": "[empty(parameters('testString'))]"
    }
  }
}

Выходные данные из предыдущего примера со значениями по умолчанию:

Имя.	Тип	значение
arrayEmpty	Bool	Истина
objectEmpty	Bool	Истина
stringEmpty	Bool	Истина

intersection

intersection(arg1, arg2, arg3, ...)

Возвращает из параметров один массив или объект с общими элементами.

В Bicep используйте функцию intersection.

Параметры

Параметр	Обязательное поле	Type	Описание
arg1	Да	массив или объект	Первое значение для поиска общих элементов.
arg2	Да	массив или объект	Второе значение для поиска общих элементов.
дополнительные аргументы	No	массив или объект	Дополнительные значения для поиска общих элементов.

Возвращаемое значение

Массив или объект с общими элементами.

Пример

В следующем примере показано, как использовать функцию объединения по пересечению с массивами и объектами.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "firstObject": {
      "type": "object",
      "defaultValue": {
        "one": "a",
        "two": "b",
        "three": "c"
      }
    },
    "secondObject": {
      "type": "object",
      "defaultValue": {
        "one": "a",
        "two": "z",
        "three": "c"
      }
    },
    "firstArray": {
      "type": "array",
      "defaultValue": [ "one", "two", "three" ]
    },
    "secondArray": {
      "type": "array",
      "defaultValue": [ "two", "three" ]
    }
  },
  "resources": [
  ],
  "outputs": {
    "objectOutput": {
      "type": "object",
      "value": "[intersection(parameters('firstObject'), parameters('secondObject'))]"
    },
    "arrayOutput": {
      "type": "array",
      "value": "[intersection(parameters('firstArray'), parameters('secondArray'))]"
    }
  }
}

Выходные данные из предыдущего примера со значениями по умолчанию:

Имя.	Тип	значение
objectOutput	Object	{"one": "a", "three": "c"}
arrayOutput	Массив	["two", "three"]

items

items(object)

Преобразует объект словаря в массив. Сведения о преобразовании массива в объект см . в toObject .

В Bicep используйте функцию items.

Параметры

Параметр	Обязательное поле	Type	Описание
объект	Да	объект	Объект словаря, который нужно преобразовать в массив.

Возвращаемое значение

Массив объектов преобразованного словаря. У каждого объекта в массиве есть свойство key, которое содержит значение ключа для словаря. У каждого объекта также есть свойство value, которое содержит свойства объекта.

Пример

В следующем примере показано преобразование объекта словаря в массив. Для каждого объекта в массиве создается объект с измененными значениями.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "variables": {
    "copy": [
      {
        "name": "modifiedListOfEntities",
        "count": "[length(items(variables('entities')))]",
        "input": {
          "key": "[items(variables('entities'))[copyIndex('modifiedListOfEntities')].key]",
          "fullName": "[items(variables('entities'))[copyIndex('modifiedListOfEntities')].value.displayName]",
          "itemEnabled": "[items(variables('entities'))[copyIndex('modifiedListOfEntities')].value.enabled]"
        }
      }
    ],
    "entities": {
      "item002": {
        "enabled": false,
        "displayName": "Example item 2",
        "number": 200
      },
      "item001": {
        "enabled": true,
        "displayName": "Example item 1",
        "number": 300
      }
    }
  },
  "resources": [],
  "outputs": {
    "modifiedResult": {
      "type": "array",
      "value": "[variables('modifiedListOfEntities')]"
    }
  }
}

В предыдущем примере возвращаются следующие значения:

"modifiedResult": {
  "type": "Array",
  "value": [
    {
      "fullName": "Example item 1",
      "itemEnabled": true,
      "key": "item001"
    },
    {
      "fullName": "Example item 2",
      "itemEnabled": false,
      "key": "item002"
    }
  ]
}

В следующем примере показан массив, возвращаемый функцией для работы с элементами.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "variables": {
    "entities": {
      "item002": {
        "enabled": false,
        "displayName": "Example item 2",
        "number": 200
      },
      "item001": {
        "enabled": true,
        "displayName": "Example item 1",
        "number": 300
      }
    },
    "entitiesArray": "[items(variables('entities'))]"
  },
  "resources": [],
  "outputs": {
    "itemsResult": {
      "type": "array",
      "value": "[variables('entitiesArray')]"
    }
  }
}

В примере возвращаются следующие значения:

"itemsResult": {
  "type": "Array",
  "value": [
    {
      "key": "item001",
      "value": {
        "displayName": "Example item 1",
        "enabled": true,
        "number": 300
      }
    },
    {
      "key": "item002",
      "value": {
        "displayName": "Example item 2",
        "enabled": false,
        "number": 200
      }
    }
  ]
}

В JSON объект представляет собой неупорядоченную коллекцию из нуля или более пар "ключ-значение". Упорядочение может быть разным в зависимости от реализации. Например функция Bicep items() сортирует объекты в алфавитном порядке. В других местах можно сохранить исходное упорядочение. Из-за этого недетерминированного, избегайте принятия каких-либо предположений о упорядочении ключей объектов при написании кода, который взаимодействует с параметрами развертывания и выходными данными.

json

json(arg1)

Преобразовывает допустимую строку JSON в тип данных JSON.

В Bicep используйте функцию json.

Параметры

Параметр	Обязательное поле	Type	Описание
arg1	Да	строка	Значение, которое необходимо преобразовать в формат JSON. Строка должна быть правильно отформатированной строкой JSON.

Возвращаемое значение

Тип данных JSON из указанной строки или пустое значение, если указано значение null.

Замечания

Если необходимо включить значение параметра или переменную в объект JSON, используйте функцию форматирования , чтобы создать строку, передаваемую в функцию.

Для получения значения NULL можно также использовать null().

Пример

Ниже представлен пример использования функции json. Обратите внимание, что для пустого объекта можно передать значение null.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "jsonEmptyObject": {
      "type": "string",
      "defaultValue": "null"
    },
    "jsonObject": {
      "type": "string",
      "defaultValue": "{\"a\": \"b\"}"
    },
    "jsonString": {
      "type": "string",
      "defaultValue": "\"test\""
    },
    "jsonBoolean": {
      "type": "string",
      "defaultValue": "true"
    },
    "jsonInt": {
      "type": "string",
      "defaultValue": "3"
    },
    "jsonArray": {
      "type": "string",
      "defaultValue": "[[1,2,3 ]"
    },
    "concatValue": {
      "type": "string",
      "defaultValue": "demo value"
    }
  },
  "resources": [
  ],
  "outputs": {
    "emptyObjectOutput": {
      "type": "bool",
      "value": "[empty(json(parameters('jsonEmptyObject')))]"
    },
    "objectOutput": {
      "type": "object",
      "value": "[json(parameters('jsonObject'))]"
    },
    "stringOutput": {
      "type": "string",
      "value": "[json(parameters('jsonString'))]"
    },
    "booleanOutput": {
      "type": "bool",
      "value": "[json(parameters('jsonBoolean'))]"
    },
    "intOutput": {
      "type": "int",
      "value": "[json(parameters('jsonInt'))]"
    },
    "arrayOutput": {
      "type": "array",
      "value": "[json(parameters('jsonArray'))]"
    },
    "concatObjectOutput": {
      "type": "object",
      "value": "[json(concat('{\"a\": \"', parameters('concatValue'), '\"}'))]"
    }
  }
}

Выходные данные из предыдущего примера со значениями по умолчанию:

Имя.	Тип	значение
emptyObjectOutput	Логический	Истина
objectOutput	Object	{"a": "b"}
stringOutput	Строка	test
booleanOutput	Логический	Истина
intOutput	Целое	3
arrayOutput	Массив	[ 1, 2, 3 ]
concatObjectOutput	Object	{ "a": "demo value" }

length

length(arg1)

Возвращает количество элементов в массиве, символов в строке или свойств корневого уровня в объекте.

В Bicep используйте функцию length.

Параметры

Параметр	Обязательное поле	Type	Описание
arg1	Да	массив, строка или объект	Массив, используемый для получения числа элементов, строка, используемая для получения числа символов, или объект, используемый для получения числа свойств корневого уровня.

Возвращаемое значение

Целое число.

Пример

В следующем примере показано, как использовать функцию length с массивом и строкой:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "arrayToTest": {
      "type": "array",
      "defaultValue": [
        "one",
        "two",
        "three"
      ]
    },
    "stringToTest": {
      "type": "string",
      "defaultValue": "One Two Three"
    },
    "objectToTest": {
      "type": "object",
      "defaultValue": {
        "propA": "one",
        "propB": "two",
        "propC": "three",
        "propD": {
          "propD-1": "sub",
          "propD-2": "sub"
        }
      }
    }
  },
  "resources": [],
  "outputs": {
    "arrayLength": {
      "type": "int",
      "value": "[length(parameters('arrayToTest'))]"
    },
    "stringLength": {
      "type": "int",
      "value": "[length(parameters('stringToTest'))]"
    },
    "objectLength": {
      "type": "int",
      "value": "[length(parameters('objectToTest'))]"
    }
  }
}

Выходные данные из предыдущего примера со значениями по умолчанию:

Имя.	Тип	значение
arrayLength	Int	3
stringLength	Int	13
objectLength	Int	4

null

null()

Возвращает значение NULL.

Функция null недоступна в Bicep. Вместо этого используйте ключевое слово null.

Параметры

Функция null не принимает никакие параметры.

Возвращаемое значение

Значение всегда NULL.

Пример

Следующий пример иллюстрирует использование функции null.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "resources": [],
  "outputs": {
    "emptyOutput": {
      "type": "bool",
      "value": "[empty(null())]"
    }
  }
}

Выходные данные из предыдущего примера:

Имя.	Тип	значение
emptyOutput	Bool	Истина

union

union(arg1, arg2, arg3, ...)

Возвращает из параметров один массив или объект со всеми элементами. Для массивов повторяющиеся значения включаются только один раз. Для объектов повторяющиеся имена свойств включаются только один раз.

В Bicep используйте функцию union.

Параметры

Параметр	Обязательное поле	Type	Описание
arg1	Да	массив или объект	Первое значение для объединения элементов.
arg2	Да	массив или объект	Второе значение для объединения элементов.
дополнительные аргументы	No	массив или объект	Дополнительные значения для объединения элементов.

Возвращаемое значение

Массив или объект.

Замечания

Функция объединения использует последовательность параметров, чтобы определить порядок и значения в результате.

Для массивов эта функция итеративно просматривает каждый элемент в первом параметре и добавляет в результат те из них, которые в нем еще не присутствуют. Затем она повторяет этот процесс для второго параметра и так далее. Если значение уже включено в результат, сохраняется его прежнее расположение в массиве.

При просмотре объектов к результату добавляются имена и значения свойств из первого параметра. Для последующих параметров к результату добавляются новые имена свойств, если они есть. Если в последующем параметре есть свойство с именем, которое уже встречалось ранее, его значение перезаписывается поверх прежнего. Порядок свойств не гарантируется.

Функция объединения объединяет не только элементы верхнего уровня, но и рекурсивно объединение всех вложенных массивов и объектов в них. См. второй пример в следующем разделе.

Пример

В следующем примере показано, как использовать функцию union с массивами и объектами:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "firstObject": {
      "type": "object",
      "defaultValue": {
        "one": "a",
        "two": "b",
        "three": "c1"
      }
    },
    "secondObject": {
      "type": "object",
      "defaultValue": {
        "three": "c2",
        "four": "d",
        "five": "e"
      }
    },
    "firstArray": {
      "type": "array",
      "defaultValue": [ "one", "two", "three" ]
    },
    "secondArray": {
      "type": "array",
      "defaultValue": [ "three", "four" ]
    }
  },
  "resources": [
  ],
  "outputs": {
    "objectOutput": {
      "type": "object",
      "value": "[union(parameters('firstObject'), parameters('secondObject'))]"
    },
    "arrayOutput": {
      "type": "array",
      "value": "[union(parameters('firstArray'), parameters('secondArray'))]"
    }
  }
}

Выходные данные из предыдущего примера со значениями по умолчанию:

Имя.	Тип	значение
objectOutput	Object	{"one": "a", "two": "b", "three": "c2", "four": "d", "five": "e"}
arrayOutput	Массив	["one", "two", "three", "four"]

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

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "variables": {
    "firstObject": {
      "property": {
        "one": "a",
        "two": "b",
        "three": "c1"
      },
      "nestedArray": [
        1,
        2
      ]
    },
    "secondObject": {
      "property": {
        "three": "c2",
        "four": "d",
        "five": "e"
      },
      "nestedArray": [
        3,
        4
      ]
    },
    "firstArray": [
      [
        "one",
        "two"
      ],
      [
        "three"
      ]
    ],
    "secondArray": [
      [
        "three"
      ],
      [
        "four",
        "two"
      ]
    ]
  },
  "resources": [],
  "outputs": {
    "objectOutput": {
      "type": "Object",
      "value": "[union(variables('firstObject'), variables('secondObject'))]"
    },
    "arrayOutput": {
      "type": "Array",
      "value": "[union(variables('firstArray'), variables('secondArray'))]"
    }
  }
}

Выходные данные из предыдущего примера:

Имя.	Тип	значение
objectOutput	Object	{"property":{"one":"a","two":"b","three":"c2","four":"d","пять":"e"},"nestedArray":[3,4]}
arrayOutput	Массив	[["один","два"],["три"],["четыре","два"]]

Если вложенные массивы были объединены, значение objectOutput.nestedArray будет равно [1, 2, 3, 4], а значение arrayOutput будет [["один", "два", "три"], ["три", "четыре", "два"]].

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

Описание разделов в шаблоне ARM приведено в статье Общие сведения о структуре и синтаксисе шаблонов ARM.

Функции объектов для шаблонов ARM

содержит

Параметры

Возвращаемое значение

Пример

createObject

Параметры

Возвращаемое значение

Пример

empty

Параметры

Возвращаемое значение

Пример

intersection

Параметры

Возвращаемое значение

Пример

items

Параметры

Возвращаемое значение

Пример

json

Параметры

Возвращаемое значение

Замечания

Пример

length

Параметры

Возвращаемое значение

Пример

null

Параметры

Возвращаемое значение

Пример

union

Параметры

Возвращаемое значение

Замечания

Пример

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

Дополнительные ресурсы