Bicep 的数组函数

本文介绍用于处理数组的 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)

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

命名空间:sys

参数

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

返回值

如果该值为空,则返回 True;否则返回 False

示例

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

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

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

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

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

快速启动示例

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

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

...

resource vnet 'Microsoft.Network/virtualNetworks@2021-02-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@2021-08-01' = {
  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@2021-05-01' = [for i in range(0, numberOfInstances): {
  name: '${networkInterfaceName}${i}'
  location: location
  properties: {
    ...
  }
}]

resource vm 'Microsoft.Compute/virtualMachines@2021-11-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