ARM 模板的对象函数Object functions for ARM templates

资源管理器提供了多个函数,用于处理 Azure 资源管理器 (ARM) 模板中的对象。Resource Manager provides several functions for working with objects in your Azure Resource Manager (ARM) template.

containscontains

contains(container, itemToFind)

检查数组是否包含某个值、某个对象是否包含某个键,或者某个字符串是否包含某个子字符串。Checks whether an array contains a value, an object contains a key, or a string contains a substring. 字符串比较区分大小写。The string comparison is case-sensitive. 但在测试某个对象是否包含某个键时,该比较不区分大小写。However, when testing if an object contains a key, the comparison is case-insensitive.

参数Parameters

参数Parameter 必须Required 类型Type 说明Description
containercontainer Yes 数组、对象或字符串array, object, or string 包含要查找的值的值。The value that contains the value to find.
itemToFinditemToFind Yes 字符串或整数string or int 要查找的值。The value to find.

返回值Return value

如果找到该项,则为 True ;否则为 FalseTrue if the item is found; otherwise, False.

示例Example

以下示例模板演示如何对不同的类型使用 contains:The following example template shows how to use contains with different types:

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

上述示例中使用默认值的输出为:The output from the preceding example with the default values is:

名称Name 类型Type ValueValue
stringTruestringTrue BoolBool TrueTrue
stringFalsestringFalse BoolBool FalseFalse
objectTrueobjectTrue BoolBool TrueTrue
objectFalseobjectFalse BoolBool FalseFalse
arrayTruearrayTrue BoolBool TrueTrue
arrayFalsearrayFalse BoolBool FalseFalse

createObjectcreateObject

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

从键和值创建对象。Creates an object from the keys and values.

参数Parameters

参数Parameter 必须Required 类型Type 说明Description
key1key1 No stringstring 键的名称。The name of the key.
value1value1 No int、布尔值、字符串、对象或数组int, boolean, string, object, or array 键的值。The value for the key.
其他键additional keys No stringstring 键的其他名称。Additional names of the keys.
其他值additional values No int、布尔值、字符串、对象或数组int, boolean, string, object, or array 键的其他值。Additional values for the keys.

该函数只接受偶数个参数。The function only accepts an even number of parameters. 每个键必须具有匹配的值。Each key must have a matching value.

返回值Return value

具有每个键和值对的对象。An object with each key and value pair.

示例Example

下面的示例从不同类型的值创建对象。The following example creates an object from different types of values.

{
    "$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 的对象,其值如下:The output from the preceding example with the default values is an object named newObject with the following value:

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

emptyempty

empty(itemToTest)

确定数组、对象或字符串是否为空。Determines if an array, object, or string is empty.

参数Parameters

参数Parameter 必须Required 类型Type 说明Description
itemToTestitemToTest Yes 数组、对象或字符串array, object, or string 要检查是否为空的值。The value to check if it's empty.

返回值Return value

如果该值为空,则返回 True ;否则返回 FalseReturns True if the value is empty; otherwise, False.

示例Example

以下示例模板检查某个数组、对象和字符串是否为空。The following example template checks whether an array, object, and string are empty.

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

上述示例中使用默认值的输出为:The output from the preceding example with the default values is:

名称Name 类型Type ValueValue
arrayEmptyarrayEmpty BoolBool TrueTrue
objectEmptyobjectEmpty BoolBool TrueTrue
stringEmptystringEmpty BoolBool TrueTrue

intersectionintersection

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

返回包含参数中通用元素的单个数组或对象。Returns a single array or object with the common elements from the parameters.

parametersParameters

参数Parameter 必须Required 类型Type 说明Description
arg1arg1 Yes 数组或对象array or object 用于查找通用元素的第一个值。The first value to use for finding common elements.
arg2arg2 Yes 数组或对象array or object 用于查找通用元素的第二个值。The second value to use for finding common elements.
其他参数additional arguments No 数组或对象array or object 用于查找通用元素的其他值。Additional values to use for finding common elements.

返回值Return value

包含通用元素的数组或对象。An array or object with the common elements.

示例Example

以下示例模板演示如何对数组和对象使用 intersection:The following example template shows how to use intersection with arrays and objects:

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

上述示例中使用默认值的输出为:The output from the preceding example with the default values is:

名称Name 类型Type ValueValue
objectOutputobjectOutput 对象Object {"one": "a", "three": "c"}{"one": "a", "three": "c"}
arrayOutputarrayOutput ArrayArray ["two", "three"]["two", "three"]

jsonjson

json(arg1)

将有效的 JSON 字符串转换为 JSON 数据类型。Converts a valid JSON string into a JSON data type.

参数Parameters

参数Parameter 必须Required 类型Type 说明Description
arg1arg1 Yes stringstring 要转换为 JSON 的值。The value to convert to JSON. 字符串必须是格式正确的 JSON 字符串。The string must be a properly formatted JSON string.

返回值Return value

指定字符串中的 JSON 数据类型,或指定 null 时的空值。The JSON data type from the specified string, or an empty value when null is specified.

备注Remarks

如需将某个参数值或变量包含在 JSON 对象中,可使用 concat 函数创建要传递到此函数的字符串。If you need to include a parameter value or variable in the JSON object, use the concat function to create the string that you pass to the function.

还可以使用 null() 获取空值。You can also use null() to get a null value.

示例Example

以下示例模板演示如何使用 json 函数。The following example template shows how to use the json function. 请注意,可以为空对象传入 null。Notice that you can pass in null for an empty object.

{
    "$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'), '\"}'))]"
        }
    }
}

上述示例中使用默认值的输出为:The output from the preceding example with the default values is:

名称Name 类型Type ValueValue
emptyObjectOutputemptyObjectOutput 布尔Boolean TrueTrue
objectOutputobjectOutput ObjectObject {"a": "b"}{"a": "b"}
stringOutputstringOutput StringString 测试test
booleanOutputbooleanOutput 布尔Boolean TrueTrue
intOutputintOutput IntegerInteger 33
arrayOutputarrayOutput ArrayArray [ 1, 2, 3 ][ 1, 2, 3 ]
concatObjectOutputconcatObjectOutput 对象Object { "a": "demo value" }{ "a": "demo value" }

lengthlength

length(arg1)

返回数组中的元素数、字符串中的字符数或对象中的根级属性数。Returns the number of elements in an array, characters in a string, or root-level properties in an object.

parametersParameters

参数Parameter 必须Required 类型Type 说明Description
arg1arg1 Yes 数组、字符串或对象array, string, or object 用于获取元素数的数组、用于获取字符数的字符串,或用于获取根级属性数的对象。The array to use for getting the number of elements, the string to use for getting the number of characters, or the object to use for getting the number of root-level properties.

返回值Return value

一个整数。An int.

示例Example

以下示例模板演示如何对数组和字符串使用 length:The following example template shows how to use length with an array and string:

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

上述示例中使用默认值的输出为:The output from the preceding example with the default values is:

名称Name 类型Type ValueValue
arrayLengtharrayLength intInt 33
stringLengthstringLength intInt 1313
objectLengthobjectLength intInt 44

nullnull

null()

返回 Null。Returns null.

参数Parameters

Null 函数不接受任何参数。The null function doesn't accept any parameters.

返回值Return value

一个始终为 null 的值。A value that is always null.

示例Example

下面的示例使用 null 函数。The following example uses the null function.

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

前述示例的输出为:The output from the preceding example is:

名称Name 类型Type ValueValue
emptyOutputemptyOutput BoolBool TrueTrue

unionunion

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

返回包含参数中所有元素的单个数组或对象。Returns a single array or object with all elements from the parameters. 重复的值或键仅包含一次。Duplicate values or keys are only included once.

parametersParameters

参数Parameter 必须Required 类型Type 说明Description
arg1arg1 Yes 数组或对象array or object 用于联接元素的第一个值。The first value to use for joining elements.
arg2arg2 Yes 数组或对象array or object 用于联接元素的第二个值。The second value to use for joining elements.
其他参数additional arguments No 数组或对象array or object 用于联接元素的其他值。Additional values to use for joining elements.

返回值Return value

数组或对象。An array or object.

示例Example

以下示例模板演示如何对数组和对象使用 union:The following example template shows how to use union with arrays and objects:

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

上述示例中使用默认值的输出为:The output from the preceding example with the default values is:

名称Name 类型Type ValueValue
objectOutputobjectOutput ObjectObject {"one": "a", "two": "b", "three": "c2", "four": "d", "five": "e"}{"one": "a", "two": "b", "three": "c2", "four": "d", "five": "e"}
arrayOutputarrayOutput ArrayArray ["one", "two", "three", "four"]["one", "two", "three", "four"]

后续步骤Next steps