Bicep 的数组函数

项目
10/29/2024

本文介绍用于处理数组的 Bicep 函数。可在此处找到用于处理数组的 lambda 函数。

array

array(convertToArray)

将值转换为数组。

命名空间：sys。

参数

参数	必选	类型	说明
convertToArray	是	整数、字符串、数组或对象	要转换为数组的值。

返回值

一个数组。

示例

以下示例演示如何对不同的类型使用 array 函数。

param intToConvert int = 1
param stringToConvert string = 'efgh'
param objectToConvert object = {
  a: 'b'
  c: 'd'
}

output intOutput array = array(intToConvert)
output stringOutput array = array(stringToConvert)
output objectOutput array = array(objectToConvert)

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

名称	类型	Value
intOutput	Array	[1]
stringOutput	Array	["efgh"]
objectOutput	Array	[{"a": "b", "c": "d"}]

concat

concat(arg1, arg2, arg3, ...)

组合多个数组并返回串联的数组。有关组合多个字符串的详细信息，请参阅 concat。

命名空间：sys。

参数

参数	必选	类型	说明
arg1	是	array	串联的第一个数组。
其他参数	否	array	按顺序排列要进行串联的其他数组。

此函数接受任意数量的数组并将它们组合在一起。

返回值

一个包含串联值的数组。

示例

以下示例演示如何组合两个数组。

param firstArray array = [
  '1-1'
  '1-2'
  '1-3'
]
param secondArray array = [
  '2-1'
  '2-2'
  '2-3'
]

output return array = concat(firstArray, secondArray)

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

名称	类型	值
return	Array	["1-1", "1-2", "1-3", "2-1", "2-2", "2-3"]

contains

contains(container, itemToFind)

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

命名空间：sys。

参数

参数	必选	类型	说明
container	是	数组、对象或字符串	包含要查找的值的值。
itemToFind	是	字符串或整数	要查找的值。

返回值

如果找到该项，则为 True；否则为 False。

示例

以下示例演示如何对不同的类型使用 contains：

param stringToTest string = 'OneTwoThree'
param objectToTest object = {
  one: 'a'
  two: 'b'
  three: 'c'
}
param arrayToTest array = [
  'one'
  'two'
  'three'
]

output stringTrue bool = contains(stringToTest, 'e')
output stringFalse bool = contains(stringToTest, 'z')
output objectTrue bool = contains(objectToTest, 'one')
output objectFalse bool = contains(objectToTest, 'a')
output arrayTrue bool = contains(arrayToTest, 'three')
output arrayFalse bool = contains(arrayToTest, 'four')

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

名称	类型	值
stringTrue	Bool	True
stringFalse	Bool	False
objectTrue	Bool	True
objectFalse	Bool	False
arrayTrue	Bool	True
arrayFalse	Bool	False

empty

empty(itemToTest)

确定数组、对象或字符串是否为空或 null。

命名空间：sys。

参数

参数	必选	类型	说明
itemToTest	是	数组、对象或字符串	要检查是否为空或 null 的值。

返回值

如果该值为空或 null，则返回 True；否则返回 False。

示例

以下示例检查某个数组、对象和字符串是否为空。

param testArray array = []
param testObject object = {}
param testString string = ''
param testNullString string?

output arrayEmpty bool = empty(testArray)
output objectEmpty bool = empty(testObject)
output stringEmpty bool = empty(testString)
output stringNull bool = empty(testNullString)

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

名称	类型	值
arrayEmpty	Bool	True
objectEmpty	Bool	True
stringEmpty	Bool	True
stringNull	Bool	True

快速启动示例

以下示例提取自带有诊断日志设置的虚拟网络快速启动模板：

@description('Array containing DNS Servers')
param dnsServers array = []

...

resource vnet 'Microsoft.Network/virtualNetworks@2023-11-01' = {
  name: vnetName
  location: location
  properties: {
    addressSpace: {
      addressPrefixes: vnetAddressSpace
    }
    dhcpOptions: empty(dnsServers) ? null : {
      dnsServers: dnsServers
    }
    ...
  }
}

在条件表达式中，使用 empty 函数检查 dnsServers 数组是否为空数组。

first

first(arg1)

返回数组的第一个元素，或字符串的第一个字符。

命名空间：sys。

参数

参数	必选	类型	说明
arg1	是	数组或字符串	要检索第一个元素或字符的值。

返回值

数组中第一个元素的类型（字符串、整数、数组或对象），或者字符串的第一个字符。

示例

以下示例演示如何对不同的类型使用 first 函数。

param arrayToTest array = [
  'one'
  'two'
  'three'
]

output arrayOutput string = first(arrayToTest)
output stringOutput string = first('One Two Three')

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

名称	类型	值
arrayOutput	String	one
stringOutput	String	O

平展 (flatten)

flatten(arrayToFlatten)

获取数组组成的数组，并按原始顺序返回子数组元素组成的数组。子数组仅平展一次，不以递归方式。

命名空间：sys。

参数

参数	必选	类型	描述
arrayToFlattern	是	array	要平展的子数组组成的数组。

返回值

Array

示例

以下示例显示了如何使用 flatten 函数。

param arrayToTest array = [
  ['one', 'two']
  ['three']
  ['four', 'five']
]
output arrayOutput array = flatten(arrayToTest)

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

名称	类型	值
arrayOutput	array	['one', 'two', 'three', 'four', 'five']

indexOf

indexOf(arrayToSearch, itemToFind)

返回数组中第一次出现的项的索引的整数。字符串比较区分大小写。

命名空间：sys。

参数

参数	必选	类型	说明
arrayToSearch	是	array	用于查找所搜索项索引的数组。
itemToFind	是	整数、字符串、数组或对象	要在数组中查找的项。

返回值

一个整数，表示数组中项的第一个索引。该索引从零开始。如果未找到该项，则返回 -1。

示例

以下示例演示如何使用 indexOf 和 lastIndexOf 函数：

var names = [
  'one'
  'two'
  'three'
]

var numbers = [
  4
  5
  6
]

var collection = [
  names
  numbers
]

var duplicates = [
  1
  2
  3
  1
]

output index1 int = lastIndexOf(names, 'two')
output index2 int = indexOf(names, 'one')
output notFoundIndex1 int = lastIndexOf(names, 'Three')

output index3 int = lastIndexOf(numbers, 4)
output index4 int = indexOf(numbers, 6)
output notFoundIndex2 int = lastIndexOf(numbers, '5')

output index5 int = indexOf(collection, numbers)

output index6 int = indexOf(duplicates, 1)
output index7 int = lastIndexOf(duplicates, 1)

前述示例的输出为：

名称	类型	值
index1	int	1
index2	int	0
index3	int	0
index4	int	2
index5	int	1
index6	int	0
index7	int	3
notFoundIndex1	int	-1
notFoundIndex2	int	-1

intersection

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

返回包含参数中通用元素的单个数组或对象。

命名空间：sys。

参数

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

返回值

包含通用元素的数组或对象。元素的顺序由第一个数组参数确定。

示例

以下示例演示如何对数组和对象使用 intersection：

param firstObject object = {
  one: 'a'
  two: 'b'
  three: 'c'
}

param secondObject object = {
  one: 'a'
  two: 'z'
  three: 'c'
}

param firstArray array = [
  'one'
  'two'
  'three'
]

param secondArray array = [
  'two'
  'three'
]

output objectOutput object = intersection(firstObject, secondObject)
output arrayOutput array = intersection(firstArray, secondArray)

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

名称	类型	值
objectOutput	对象	{"one": "a", "three": "c"}
arrayOutput	Array	["two", "three"]

第一个数组参数确定相交元素的顺序。以下示例演示了返回元素的顺序如何基于哪个数组排在前面。

var array1 = [
  1
  2
  3
  4
]

var array2 = [
  3
  2
  1
]

var array3 = [
  4
  1
  3
  2
]

output commonUp array = intersection(array1, array2, array3)
output commonDown array = intersection(array2, array3, array1)

前述示例的输出为：

名称	类型	值
commonUp	array	[1, 2, 3]
commonDown	array	[3, 2, 1]

last

last(arg1)

返回数组的最后一个元素，或字符串的最后一个字符。

命名空间：sys。

参数

参数	必选	类型	说明
arg1	是	数组或字符串	要检索最后一个元素或字符的值。

返回值

数组中最后一个元素的类型（字符串、整数、数组或对象），或者字符串的最后一个字符。

示例

以下示例演示如何对不同的类型使用 last 函数。

param arrayToTest array = [
  'one'
  'two'
  'three'
]

output arrayOutput string = last(arrayToTest)
output stringOutput string = last('One Two three')

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

名称	类型	值
arrayOutput	String	three
stringOutput	String	e

lastIndexOf

lastIndexOf(arrayToSearch, itemToFind)

返回数组中最后一次出现的项的索引的整数。字符串比较区分大小写。

命名空间：sys。

参数

参数	必选	类型	说明
arrayToSearch	是	array	用于查找所搜索项索引的数组。
itemToFind	是	整数、字符串、数组或对象	要在数组中查找的项。

返回值

一个整数，表示数组中项的最后一个索引。该索引从零开始。如果未找到该项，则返回 -1。

示例

以下示例演示如何使用 indexOf 和 lastIndexOf 函数：

var names = [
  'one'
  'two'
  'three'
]

var numbers = [
  4
  5
  6
]

var collection = [
  names
  numbers
]

var duplicates = [
  1
  2
  3
  1
]

output index1 int = lastIndexOf(names, 'two')
output index2 int = indexOf(names, 'one')
output notFoundIndex1 int = lastIndexOf(names, 'Three')

output index3 int = lastIndexOf(numbers, 4)
output index4 int = indexOf(numbers, 6)
output notFoundIndex2 int = lastIndexOf(numbers, '5')

output index5 int = indexOf(collection, numbers)

output index6 int = indexOf(duplicates, 1)
output index7 int = lastIndexOf(duplicates, 1)

前述示例的输出为：

名称	类型	值
index1	int	1
index2	int	0
index3	int	0
index4	int	2
index5	int	1
index6	int	0
index7	int	3
notFoundIndex1	int	-1
notFoundIndex2	int	-1

length

length(arg1)

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

命名空间：sys。

参数

参数	必选	类型	说明
arg1	是	数组、字符串或对象	用于获取元素数的数组、用于获取字符数的字符串，或用于获取根级属性数的对象。

返回值

一个整数。

示例

以下示例演示如何对数组和字符串使用 length：

param arrayToTest array = [
  'one'
  'two'
  'three'
]
param stringToTest string = 'One Two Three'
param objectToTest object = {
  propA: 'one'
  propB: 'two'
  propC: 'three'
  propD: {
    'propD-1': 'sub'
    'propD-2': 'sub'
  }
}

output arrayLength int = length(arrayToTest)
output stringLength int = length(stringToTest)
output objectLength int = length(objectToTest)

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

名称	类型	值
arrayLength	int	3
stringLength	int	13
objectLength	int	4

快速启动示例

以下示例摘自快速启动模板使用公共 IP 在外部 VNet 中部署 API 管理：

@description('Numbers for availability zones, for example, 1,2,3.')
param availabilityZones array = [
  '1'
  '2'
]

resource exampleApim 'Microsoft.ApiManagement/service@2023-05-01-preview' = {
  name: apiManagementName
  location: location
  sku: {
    name: sku
    capacity: skuCount
  }
  zones: ((length(availabilityZones) == 0) ? null : availabilityZones)
  ...
}

在条件表达式中，length 函数检查 availabilityZones 数组的长度。

可在以下快速启动 Bicep 文件中找到更多示例：

max

max(arg1)

返回整数数组或逗号分隔的整数列表中的最大值。

命名空间：sys。

参数

参数	必选	类型	说明
arg1	是	整数数组或逗号分隔的整数列表	要获取最大值的集合。

返回值

表示最大值的整数。

示例

以下示例演示如何对整数数组和整数列表使用 max：

param arrayToTest array = [
  0
  3
  2
  5
  4
]

output arrayOutput int = max(arrayToTest)
output intOutput int = max(0,3,2,5,4)

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

名称	类型	值
arrayOutput	int	5
intOutput	int	5

min

min(arg1)

返回整数数组或逗号分隔的整数列表中的最小值。

命名空间：sys。

参数

参数	必选	类型	说明
arg1	是	整数数组或逗号分隔的整数列表	要获取最小值的集合。

返回值

表示最小值的整数。

示例

以下示例演示如何对整数数组和整数列表使用 min：

param arrayToTest array = [
  0
  3
  2
  5
  4
]

output arrayOutput int = min(arrayToTest)
output intOutput int = min(0,3,2,5,4)

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

名称	类型	值
arrayOutput	int	0
intOutput	int	0

range

range(startIndex, count)

从起始整数并提供项数创建一个整数数组。

命名空间：sys。

参数

参数	必选	类型	说明
startIndex	是	int	数组中的第一个整数。 startIndex 和 count 的总和不得大于 2147483647。
count	是	int	数组中的整数个数。必须为非负整数，最大为 10000。

返回值

整数数组。

示例

以下示例演示如何使用 range 函数：

param startingInt int = 5
param numberOfElements int = 3

output rangeOutput array = range(startingInt, numberOfElements)

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

名称	类型	Value
rangeOutput	Array	[5, 6, 7]

快速启动示例

以下示例摘自快速启动模板 VNET 中的两个 VM - 内部负载均衡器和 LB 规则：

...
var numberOfInstances = 2

resource networkInterface 'Microsoft.Network/networkInterfaces@2023-11-01' = [for i in range(0, numberOfInstances): {
  name: '${networkInterfaceName}${i}'
  location: location
  properties: {
    ...
  }
}]

resource vm 'Microsoft.Compute/virtualMachines@2024-03-01' = [for i in range(0, numberOfInstances): {
  name: '${vmNamePrefix}${i}'
  location: location
  properties: {
    ...
  }
}]

Bicep 文件创建两个 networkInterface 和两个 virtualMachine 资源。

可在以下快速启动 Bicep 文件中找到更多示例：

skip

skip(originalValue, numberToSkip)

返回一个数组，其中包含数组中指定数字后面的所有元素；或返回一个字符串，其中包含字符串中指定数后面的所有字符。

命名空间：sys。

参数

参数	必选	类型	说明
originalValue	是	数组或字符串	用于跳过的数组或字符串。
numberToSkip	是	int	要跳过的元素数或字符数。如果此值小于或等于 0，则返回值中的所有元素或字符。如果此值大于数组或字符串的长度，则返回空数组或字符串。

返回值

数组或字符串。

示例

以下示例跳过数组中指定数目的元素，以及字符串中指定数目的字符。

param testArray array = [
  'one'
  'two'
  'three'
]
param elementsToSkip int = 2
param testString string = 'one two three'
param charactersToSkip int = 4

output arrayOutput array = skip(testArray, elementsToSkip)
output stringOutput string = skip(testString, charactersToSkip)

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

名称	类型	值
arrayOutput	Array	["three"]
stringOutput	String	two three

take

take(originalValue, numberToTake)

返回一个数组，其中包含从数组开头位置算起的指定数目的元素；或返回一个字符串，其中包含从字符串开头位置算起的指定数目的字符。

命名空间：sys。

参数

参数	必选	类型	说明
originalValue	是	数组或字符串	要从中提取元素的数组或字符串。
numberToTake	是	int	要提取的元素或字符数。如果此值为 0 或更小，则返回一个空数组或字符串。如果此值大于给定数组或字符串的长度，则返回数组或字符串中的所有元素。

返回值

数组或字符串。

示例

以下示例从数组中提取指定数目的元素，并从字符串中提取指定数目的字符。

param testArray array = [
  'one'
  'two'
  'three'
]
param elementsToTake int = 2
param testString string = 'one two three'
param charactersToTake int = 2

output arrayOutput array = take(testArray, elementsToTake)
output stringOutput string = take(testString, charactersToTake)

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

名称	类型	值
arrayOutput	Array	["one", "two"]
stringOutput	String	on

union

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

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

命名空间：sys。

参数

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

返回值

数组或对象。

备注

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

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

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

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

示例

以下示例演示如何对数组和对象使用 union：

param firstObject object = {
  one: 'a'
  two: 'b'
  three: 'c1'
}

param secondObject object = {
  three: 'c2'
  four: 'd'
  five: 'e'
}

param firstArray array = [
  'one'
  'two'
  'three'
]

param secondArray array = [
  'three'
  'four'
  'two'
]

output objectOutput object = union(firstObject, secondObject)
output arrayOutput array = union(firstArray, secondArray)

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

名称	类型	值
objectOutput	Object	{"one": "a", "two": "b", "three": "c2", "four": "d", "five": "e"}
arrayOutput	Array	["one", "two", "three", "four"]

以下示例演示了深度合并功能：

var firstObject = {
  property: {
    one: 'a'
    two: 'b'
    three: 'c1'
  }
  nestedArray: [
    1
    2
  ]
}
var secondObject = {
  property: {
    three: 'c2'
    four: 'd'
    five: 'e'
  }
  nestedArray: [
    3
    4
  ]
}
var firstArray = [
  [
    'one'
    'two'
  ]
  [
    'three'
  ]
]
var secondArray = [
  [
    'three'
  ]
  [
    'four'
    'two'
  ]
]

output objectOutput object = union(firstObject, secondObject)
output arrayOutput array = union(firstArray, 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"]]。

后续步骤

若要获取由某个值分隔的字符串值数组，请参阅 split。

通过

Bicep 的数组函数

array

参数

返回值

示例

concat

参数

返回值

示例

contains

参数

返回值

示例

empty

参数

返回值

示例

快速启动示例

first

参数

返回值

示例

平展 (flatten)

参数

返回值

示例

indexOf

参数

返回值

示例

intersection

参数

返回值

示例

last

参数

返回值

示例

lastIndexOf

参数

返回值

示例

length

参数

返回值

示例

快速启动示例

max

参数

返回值

示例

min

参数

返回值

示例

range

参数

返回值

示例

快速启动示例

skip

参数

返回值

示例

take

参数

返回值

示例

union

参数

返回值

备注

示例

后续步骤

其他资源