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

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

Совет

Мы рекомендуем использовать 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 массив или объект Дополнительные значения для поиска общих элементов.

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

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

Пример

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

{
  "$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 Истина

objectKeys

objectKeys(object)

Возвращает ключи из объекта, где объект является коллекцией пар "ключ-значение".

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

Параметры

Параметр Обязательное поле Type Описание
объект Да объект Объект, являющийся коллекцией пар "ключ-значение".

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

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

Пример

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

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "variables": {
    "obj": {
      "a": 1,
      "b": 2
    }
  },
  "resources": [],
  "outputs": {
    "keyArray": {
      "type": "array",
      "value": "[objectKeys(variables('obj'))]"
    }
  }
}

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

Имя. Тип значение
keyArray Массив [ "a", "b" ]

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

shallowMerge

shallowMerge(inputArray)

Объединяет массив объектов, где объединяются только объекты верхнего уровня. Это означает, что если объединенные объекты содержат вложенные объекты, эти вложенные объекты не объединяются глубоко; Вместо этого они полностью заменяются соответствующим свойством из объекта слияния.

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

Параметры

Параметр Обязательное поле Type Описание
inputArray Да array Массив объектов .

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

Объект.

Пример

В следующем примере показано использование shallowMerge.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "variables": {
    "firstArray": [
      {
        "one": "a"
      },
      {
        "two": "b"
      },
      {
        "two": "c"
      }
    ],
    "secondArray": [
      {
        "one": "a",
        "nested": {
          "a": 1,
          "nested": {
            "c": 3
          }
        }
      },
      {
        "two": "b",
        "nested": {
          "b": 2
        }
      }
    ]
  },
  "resources": [],
  "outputs": {
    "firstOutput": {
      "type": "object",
      "value": "[shallowMerge(variables('firstArray'))]"
    },
    "secondOutput": {
      "type": "object",
      "value": "[shallowMerge(variables('secondArray'))]"
    }
  }
}

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

Имя. Тип значение
firstOutput объект {"one":"a","two":"c"}
secondOutput объект {"one":"a","nested":{"b":2},"two":"b"b"}

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

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

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 будет [["один", "два", "три"], ["три", "четыре", "два"]].

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