Bicep 的陣列函式

發行項
07/11/2024

本文說明處理陣列的 Bicep 函式。可以在這裡找到使用陣列的 Lambda 函式。

陣列

array(convertToArray)

將值轉換為陣列。

命名空間：sys (部分機器翻譯)。

參數

參數	必要	類型	描述
convertToArray	Yes	整數、字串、陣列或物件	要轉換為陣列的值。

傳回值

陣列。

範例

下列範例顯示如何使用不同類型的陣列函式。

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)

上述範例中具有預設值的輸出如下：

名稱	類型	值
intOutput	陣列	[1]
stringOutput	陣列	["efgh"]
objectOutput	陣列	[{"a": "b", "c": "d"}]

concat

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

結合多個陣列，並傳回串連的陣列。如需結合多個字串的詳細資訊，請參閱串連。

命名空間：sys (部分機器翻譯)。

參數

參數	必要	類型	描述
arg1	Yes	陣列	串連的第一個陣列。
更多引數	No	陣列	更多供串連的循序陣列。

此函式會接受任意數量的陣列，並將其組合在一起。

傳回值

串連值的陣列。

範例

下一個範例顯示如何結合兩個陣列。

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	陣列	["1-1", "1-2", "1-3", "2-1", "2-2", "2-3"]

contains

contains(container, itemToFind)

檢查陣列中是否包含值、物件中是否包含索引鍵，或字串中是否包含子字串。字串比較會區分大小寫。不過，測試時，如果物件包含索引鍵，比較便不區分大小寫。

命名空間：sys (部分機器翻譯)。

參數

參數	必要	類型	描述
容器	Yes	陣列、物件或字串	其中包含要尋找之值的值。
itemToFind	Yes	字串或整數	要尋找的值。

傳回值

找到項目則傳回 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	Yes	陣列、物件或字串	要檢查其是否為空白或 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
    }
    ...
  }
}

在條件運算式中，會使用空白函式來檢查 dnsServers 陣列是否為空陣列。

第一

first(arg1)

傳回陣列的第一個元素或字串的第一個字元。

命名空間：sys (部分機器翻譯)。

參數

參數	必要	類型	描述
arg1	Yes	陣列或字串	要擷取其第一個元素或字元的值。

傳回值

陣列中第一個元素的類型 (字串、整數、陣列或物件) 或字串的第一個字元。

範例

下列範例顯示如何搭配使用 first 函式與陣列和字串。

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

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

上述範例中具有預設值的輸出如下：

名稱	類型	值
arrayOutput	String	一個
stringOutput	String	O

flatten

flatten(arrayToFlatten)

採用陣列陣列，並以原始順序傳回子陣列元素的陣列。子陣列只會壓平合併一次，不會遞迴。

命名空間：sys (部分機器翻譯)。

參數

參數	必要	類型	描述
arrayToFlattern	Yes	陣列	要壓平合併的子陣列陣列。

傳回值

陣列

範例

下列範例示範如何使用壓平合併函式。

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

上述範例中具有預設值的輸出如下：

名稱	類型	值
arrayOutput	陣列	['one', 'two', 'three', 'four', 'five']

indexOf

indexOf(arrayToSearch, itemToFind)

傳回陣列中項目第一次出現索引的整數。比較會針對字串區分大小寫。

命名空間：sys (部分機器翻譯)。

參數

參數	必要	類型	描述
arrayToSearch	Yes	陣列	用於尋找搜尋項目索引的陣列。
itemToFind	Yes	整數、字串、陣列或物件	要在陣列中尋找的項目。

傳回值

代表陣列中第一次項目索引的整數。索引以零為起始。如果找不到該項目，則傳回 -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(arg1, arg2, arg3, ...)

從參數中傳回具有共同元素的單一陣列或物件。

命名空間：sys (部分機器翻譯)。

參數

參數	必要	類型	描述
arg1	Yes	陣列或物件	要用來尋找共同元素的第一個值。
arg2	Yes	陣列或物件	要用來尋找共同元素的第二個值。
更多引數	No	陣列或物件	更多用於尋找共同元素的值。

傳回值

具有共同元素的陣列或物件。元素的順序取決於第一個陣列參數。

範例

下列範例顯示如何搭配使用 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	Object	{"one": "a", "three": "c"}
arrayOutput	陣列	["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	陣列	[1, 2, 3]
commonDown	陣列	[3, 2, 1]

最後一

last(arg1)

傳回陣列的最後一個元素或字串的最後一個字元。

命名空間：sys (部分機器翻譯)。

參數

參數	必要	類型	描述
arg1	Yes	陣列或字串	要擷取其最後一個元素或字元的值。

傳回值

陣列中最後一個元素的類型 (字串、整數、陣列或物件) 或字串的最後一個字元。

範例

下列範例顯示如何搭配使用 last 函式與陣列和字串。

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

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

上述範例中具有預設值的輸出如下：

名稱	類型	值
arrayOutput	String	3
stringOutput	String	e

lastIndexOf

lastIndexOf(arrayToSearch, itemToFind)

傳回陣列中項目最後一次出現索引的整數。比較會針對字串區分大小寫。

命名空間：sys (部分機器翻譯)。

參數

參數	必要	類型	描述
arrayToSearch	Yes	陣列	用於尋找搜尋項目索引的陣列。
itemToFind	Yes	整數、字串、陣列或物件	要在陣列中尋找的項目。

傳回值

代表陣列中最後一次項目索引的整數。索引以零為起始。如果找不到該項目，則傳回 -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	Yes	陣列、字串或物件	用於取得元素數目的陣列、用於取得字元數目的字串，或用於取得根層級屬性數目的物件。

傳回值

整數。

範例

下列範例顯示如何搭配使用 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 中部署 APIM：

@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	Yes	整數的陣列，或以逗號分隔的整數清單	要用來取得最大值的集合。

傳回值

代表最大值的整數。

範例

下列範例顯示如何搭配使用 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(arg1)

傳回整數陣列的最小值，或以逗號分隔的整數清單。

命名空間：sys (部分機器翻譯)。

參數

參數	必要	類型	描述
arg1	Yes	整數的陣列，或以逗號分隔的整數清單	要用來取得最小值的集合。

傳回值

代表最小值的整數。

範例

下列範例顯示如何搭配使用 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	Yes	int	陣列中的第一個整數。 startIndex 和 count 的總和不得大於 2147483647。
計數	Yes	int	陣列中的整數數目。必須是不超過 10000 的非負整數。

傳回值

整數陣列。

範例

下列範例顯示如何使用 range 函式：

param startingInt int = 5
param numberOfElements int = 3

output rangeOutput array = range(startingInt, numberOfElements)

上述範例中具有預設值的輸出如下：

名稱	類型	值
rangeOutput	陣列	[5, 6, 7]

快速入門範例

下列範例擷取自快速入門範本：VNET 中的兩個 VM - 內部 Load Balancer 和 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	Yes	陣列或字串	要用於略過的陣列或字串。
numberToSkip	Yes	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	陣列	["three"]
stringOutput	String	two three

take

take(originalValue, numberToTake)

傳回由陣列開頭的指定元素數目所組成的陣列，或傳回由字串開頭的指定字元數目所形成的字串。

命名空間：sys (部分機器翻譯)。

參數

參數	必要	類型	描述
originalValue	Yes	陣列或字串	要從其中擷取元素的陣列或字串。
numberToTake	Yes	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	陣列	["one", "two"]
stringOutput	String	on

union

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

從參數中傳回具有所有元素的單一陣列或物件。針對陣列，會包括重複的值一次。針對物件，只會包括重複的屬性名稱一次。

命名空間：sys (部分機器翻譯)。

參數

參數	必要	類型	描述
arg1	Yes	陣列或物件	用來聯結元素的第一個值。
arg2	Yes	陣列或物件	用來聯結元素的第二個值。
更多引數	No	陣列或物件	可用於聯結元素的其他值。

傳回值

陣列或物件。

備註

Union 函式會使用參數的順序來決定結果的順序和值。

針對陣列，此函式會逐一查看第一個參數中的每個元素；若其尚未出現在結果中，便會將其新增至結果。接著，系統會對第二個參數和任何更多參數重複上述程序。如果值已經存在，則會保留較早放置於陣列中的值。

針對物件，會將來自第一個參數的屬性名稱和值新增至結果。針對較後面的參數，則會將所有新名稱新增至結果。如果較後面的參數具有相同名稱的屬性，該值就會覆寫現有的值。無法保證屬性的順序。

Union 函式不僅會合併最上層元素，也會以遞迴方式合併其中的任何巢狀物件。巢狀陣列值則不會合併。請參閱下一節的第二個範例。

範例

下列範例顯示如何搭配使用 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	陣列	["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"]]。

下一步

若要取得以值分隔的字串值陣列，請參閱分割。

共用方式為

Bicep 的陣列函式

陣列

參數

傳回值

範例

concat

參數

傳回值

範例

contains

參數

傳回值

範例

empty

參數

傳回值

範例

快速入門範例

第一

參數

傳回值

範例

flatten

參數

傳回值

範例

indexOf

參數

傳回值

範例

交集

參數

傳回值

範例

最後一

參數

傳回值

範例

lastIndexOf

參數

傳回值

範例

length

參數

傳回值

範例

快速入門範例

max

參數

傳回值

範例

分鐘

參數

傳回值

範例

range

參數

傳回值

範例

快速入門範例

skip

參數

傳回值

範例

take

參數

傳回值

範例

union

參數

傳回值

備註

範例

下一步

意見反應

其他資源