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

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

• содержит
• createObject
• пустой
• перекрёсток
• элементы
• json
• длина
• нулевой
• союз

содержит

contains(container, itemToFind)

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

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

Параметры

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

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')]"
    }
  }
}

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

createObject

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

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

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

Параметры

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

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

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

Пример

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

{
  "$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(itemToTest)

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

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

Параметры

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

Возвращает результат 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'))]"
    }
  }
}

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

пересечение

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

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

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

Параметры

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

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

Пример

В следующем примере показано, как использовать 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'))]"
    }
  }
}

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

предметы

items(object)

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

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

Параметры

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

Массив объектов преобразованного словаря. У каждого объекта в массиве есть свойство 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"
    }
  ]
}

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

{
  "$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 (формат обмена данными JavaScript)

json(arg1)

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

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

Параметры

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

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

Замечания

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

Можно также использовать 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'), '\"}'))]"
    }
  }
}

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

длина

length(arg1)

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

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

Параметры

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

Целое число.

Пример

В следующем примере показано, как использовать 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'))]"
    }
  }
}

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

ноль

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())]"
    }
  }
}

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

objectKeys

objectKeys(object)

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

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

Параметры

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

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

Пример

В следующем примере показано, как использовать 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'))]"
    }
  }
}

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

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

shallowMerge

shallowMerge(inputArray)

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

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

Параметры

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

Объект.

Пример

В следующем примере показано, как использовать 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 показывает свойства из объединенных объектов в новый объект. Если имеются конфликтующие свойства (т. е. свойства с тем же именем), то свойство из последнего объекта, объединяемого, обычно имеет приоритет.

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

tryGet

tryGet(itemToTest, keyOrIndex)

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

В Bicep используйте оператор безопасной расшифровки .

Параметры

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

Возвращает значение по ключу или индексу, если оно существует. Возвращает значение NULL, если ключ или индекс отсутствуют или отсутствуют границы.

Пример

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

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",
  "variables": {
    "users": {
      "name": "John Doe",
      "age": 30
    },
    "colors": [
      "red",
      "green"
    ]
  },
  "resources": [],
  "outputs": {
    "region": {
      "type": "string",
      "nullable": true,
      "value": "[tryGet(variables('users'), 'region')]"
    },
    "name": {
      "type": "string",
      "nullable": true,
      "value": "[tryGet(variables('users'), 'name')]"
    },
    "firstColor": {
      "type": "string",
      "nullable": true,
      "value": "[tryGet(variables('colors'), 0)]"
    }
  }
}

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

союз

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

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

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

Параметры

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

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

Замечания

Функция union использует последовательность параметров для определения порядка и значений результата.

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

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

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

Пример

В следующем примере показано, как использовать 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'))]"
    }
  }
}

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

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

{
  "$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.nestedArray будет равно [1, 2, 3, 4], а значение arrayOutput будет [["один", "два", "три"], ["три", "четыре", "два"]].

Дальнейшие шаги

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