通过

ARM 模板的对象函数

资源管理器提供了多个函数，用于处理 Azure 资源管理器模板（ARM 模板）中的对象：

提示

建议使用 Bicep，因为它提供与 ARM 模板相同的功能，并且语法更易于使用。 若要了解详细信息，请参阅对象函数。

contains

contains(container, itemToFind)

检查数组是否包含值、对象是否包含键或字符串是否包含子字符串。 字符串比较区分大小写。 但在测试某个对象是否包含某个键时，该比较不区分大小写。

在 Bicep 中，使用函数 contains 。

参数

参数 必选 类型 说明
容器 是 数组、对象或字符串 包含要查找的值的值。
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 True
stringFalse Bool False
objectTrue Bool True
objectFalse Bool False
arrayTrue Bool True
arrayFalse Bool False

createObject

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

从键和值创建对象。

Bicep 不支持 createObject 函数。 使用 {} 构造对象。 请参阅对象。

参数

参数 必选 类型 说明
key1 否 字符串 键的名称。
value1 否 int、布尔值、字符串、对象或数组 键的值。
更多键 否 字符串 键的其他名称。
更多值 否 int、布尔值、字符串、对象或数组 键的其他值。

该函数只接受偶数个参数。 每个键必须具有匹配的值。

返回值

具有每个键和值对的对象。

示例

以下示例基于不同类型的值创建对象：

{
  "$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 。

参数

参数 必选 类型 说明
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 True
objectEmpty Bool True
stringEmpty Bool True

intersection

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

从参数中返回具有公共元素的单个数组或对象。

在 Bicep 中，使用函数 intersection 。

参数

参数 必选 类型 说明
arg1 是 数组或对象 用于查找通用元素的第一个值。
arg2 是 数组或对象 用于查找通用元素的第二个值。
其他参数 否 数组或对象 用于查找通用元素的其他值。

返回值

包含通用元素的数组或对象。

示例

以下示例演示如何对数组和对象使用 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 对象 {“one”： “a”， “three”： “c”}
arrayOutput Array [“two”， “three”]

items

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

json(arg1)

将有效的 JSON 字符串转换为 JSON 数据类型。

在 Bicep 中，使用函数 json 。

参数

参数 必选 类型 说明
arg1 是 字符串 要转换为 JSON 的值。 字符串必须是格式正确的 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'), '\"}'))]"
    }
  }
}

上述示例中的默认值输出为：

名称 类型 值
emptyObjectOutput 布尔 True
objectOutput 对象 {“a”： “b”}
stringOutput String 测试
booleanOutput 布尔 True
intOutput Integer 3
arrayOutput Array [ 1, 2, 3 ]
concatObjectOutput 对象 { “a”： “demo value” }

length

length(arg1)

返回数组中的元素数、字符串中的字符数或对象中的根级属性数。

在 Bicep 中，使用函数 length 。

参数

参数 必选 类型 说明
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 True

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

前述示例的输出为：

名称 类型 值
keyArray Array [ “a”， “b” ]

在 JSON 中，对象是零个或更多键/值对的无序集合。 排序可能会根据实现而有所不同。 例如，Bicep items() 函数按字母顺序对对象进行排序。 在其他位置，可以保留原始排序。 由于这种非确定性，在编写代码时避免对对象键排序做出任何假设，因为这会与部署参数和输出交互。

shallowMerge

shallowMerge(inputArray)

合并仅合并顶级对象的对象数组。 这意味着如果要合并的对象包含嵌套对象，则不会将这些嵌套对象深度合并，而是将它们完全替换为合并对象中的相应属性。

在 Bicep 中，使用函数 shallowMerge 。

参数

参数 必选 类型 说明
inputArray 是 数组 一个 对象数组。

返回值

一个对象。

示例

下面的示例演示如何使用 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"}

firstOutput 显示合并对象的属性被合并到一个新对象中。 如果存在冲突的属性（即具有相同名称的属性），则通常是最后合并的对象的属性优先。

secondOutput 显示浅合并不会将这些嵌套对象递归合并， 而是将整个嵌套对象替换为合并对象中的相应属性。

tryGet

tryGet(itemToTest, keyOrIndex)

tryGet 帮助避免在尝试访问对象或数组中不存在的属性或索引时出现部署失败。 如果指定的键或索引不存在，则返回 null， tryGet 而不是引发错误。

在 Bicep 中，使用 safe-dereference 运算符。

参数

参数 必选 类型 说明
itemToTest 是 array、 object 要调查的对象或数组。
keyOrIndex 是 字符串， int 要从数组或对象中检索的键或索引。 对象的属性名称或数组的索引。

返回值

返回键/索引处的值（如果存在）。 如果键/索引缺失或超出边界，则返回 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)]"
    }
  }
}

前述示例的输出为：

名称 类型 值
区域 String （空值）
姓名 String 无名氏
firstColor String 红色

并

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

返回包含参数中所有元素的单个数组或对象。 对于数组，仅包含重复值一次。 对于对象，仅包含重复属性名称一次。

在 Bicep 中，使用函数 union 。

参数

参数 必选 类型 说明
arg1 是 数组或对象 用于联接元素的第一个值。
arg2 是 数组或对象 用于联接元素的第二个值。
其他参数 否 数组或对象 用于联接元素的其他值。

返回值

数组或对象。

备注

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

上述示例中的默认值输出为：

名称 类型 值
objectOutput 对象 {“one”： “a”， “two”： “b”， “three”： “c2”， “four”： “d”， “five”： “e”}
arrayOutput Array [“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 对象 {"property":{"one":"a","two":"b","three":"c2","four":"d","five":"e"},"nestedArray":[3,4]}
arrayOutput Array [["one","two"],["three"],["four","two"]]

如果合并了嵌套数组，则 objectOutput.nestedArray 的值将为 [1, 2, 3, 4]，arrayOutput 的值将为 [["one", "two", "three"], ["three", "four", "two"]]。

后续步骤