ARM 模板的对象函数

项目
06/21/2024

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

contains
createObject
empty
intersection
items
json
length
null
union

提示

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

contains

contains(container, itemToFind)

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

在 Bicep 中，使用 contains 函数。

参数

参数	必选	类型	说明
container	是	数组、对象或字符串	包含要查找的值的值。
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 函数。使用 {} 构造对象。请参阅对象。

parameters

参数	必选	类型	说明
key1	否	string	键的名称。
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。

参数

参数	必选	类型	说明
object	是	对象 (object)	要转换为数组的字典对象。

返回值

转换后的字典对象数组。数组中的每个对象都具有 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	是	string	要转换为 JSON 的值。字符串必须是格式正确的 JSON 字符串。

返回值

指定字符串中的 JSON 数据类型，或指定 null 时的空值。

备注

如需将某个参数值或变量包含在 JSON 对象中，可使用 format 函数创建要传递到此函数的字符串。

还可以使用 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'), '\"}'))]"
    }
  }
}

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

名称	类型	Value
emptyObjectOutput	布尔	True
objectOutput	Object	{"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())]"
    }
  }
}

前述示例的输出为：

名称	类型	Value
emptyOutput	Bool	True

objectKeys

objectKeys(object)

返回对象中的键，其中的对象是键值对的集合。

在 Bicep 中，使用 objectKeys 函数。

参数

参数	必选	类型	说明
object	是	对象 (object)	对象，是键值对的集合。

返回值

一个数组。

示例

以下示例演示如何对对象使用 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" ]

shallowMerge

shallowMerge(inputArray)

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

在 Bicep 中，使用 shallowMerge 函数。

参数

参数	必选	类型	说明
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	object	{"one":"a","two":"c"}
secondOutput	object	{"one":"a","nested":{"b":2},"two":"b"}

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

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

union

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

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

在 Bicep 中，使用 union 函数。

参数

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

返回值

数组或对象。

备注

联合函数使用参数序列来确定结果的顺序和值。

对于数组，该函数会循环访问第一个参数中的每个元素，并将其添加到结果中（如果尚不存在）。然后，对第二个参数和任何其他参数重复该过程。如果某个值已存在，则保留其此前在数组中的放置位置。

对于对象，来自第一个参数的属性名称和值将添加到结果中。对于稍后的参数，任何新名称都将添加到结果中。如果稍后的参数具有同名的属性，该值将覆盖现有值。不保证属性的顺序。

联合函数不仅合并顶级元素，而且还以递归方式合并其中的嵌套数组和对象。请参阅以下部分中的第二个示例。

示例

以下示例演示如何对数组和对象使用 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	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	Object	{"property":{"one":"a","two":"b","three":"c2","four":"d","five":"e"},"nestedArray":[3,4]}
arrayOutput	数组	[["one","two"],["three"],["four","two"]]

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

后续步骤

有关 ARM 模板中各部分的说明，请参阅了解 ARM 模板的结构和语法。

通过

ARM 模板的对象函数

contains

参数

返回值

示例

createObject

parameters

返回值

示例

empty

参数

返回值

示例

intersection

参数

返回值

示例

items

参数

返回值

示例

json

参数

返回值

备注

示例

length

参数

返回值

示例

null

参数

返回值

示例

objectKeys

参数

返回值

示例

shallowMerge

参数

返回值

示例

union

参数

返回值

备注

示例

后续步骤

其他资源