Partilhar via

Funções de matriz para Bicep

  • Artigo

Este artigo descreve as funções do Bíceps para trabalhar com matrizes. As funções lambda para trabalhar com arrays podem ser encontradas aqui.

matriz

array(convertToArray)

Converte o valor em uma matriz.

Espaço de nome: sys.

Parâmetros

Parâmetro Necessário Type Description
convertToArray Sim int, string, array ou objeto O valor a ser convertido em uma matriz.

Valor devolvido

Uma matriz.

Exemplo

O exemplo a seguir mostra como usar a função de matriz com diferentes tipos.

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)

A saída do exemplo anterior com os valores padrão é:

Nome Tipo valor
intOutput Matriz [1]
stringOutput Matriz ["efgh"]
objectOutput Matriz [{"a": "b", "c": "d"}]

concat

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

Combina várias matrizes e retorna a matriz concatenada. Para obter mais informações sobre como combinar várias cadeias de caracteres, consulte concat.

Espaço de nome: sys.

Parâmetros

Parâmetro Necessário Type Description
Arg1 Sim matriz A primeira matriz para concatenação.
Mais argumentos Não matriz Mais matrizes em ordem sequencial para concatenação.

Esta função pega qualquer número de matrizes e as combina.

Valor devolvido

Uma matriz de valores concatenados.

Exemplo

O exemplo a seguir mostra como combinar duas matrizes.

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

output return array = concat(firstArray, secondArray)

A saída do exemplo anterior com os valores padrão é:

Nome Tipo valor
regressar Matriz ["1-1", "1-2", "1-3", "2-1", "2-2", "2-3"]

contém

contains(container, itemToFind)

Verifica se uma matriz contém um valor, um objeto contém uma chave ou uma cadeia de caracteres contém uma substring. A comparação de cadeia de caracteres diferencia maiúsculas de minúsculas. No entanto, ao testar se um objeto contém uma chave, a comparação não diferencia maiúsculas de minúsculas.

Espaço de nome: sys.

Parâmetros

Parâmetro Necessário Type Description
contentor Sim matriz, objeto ou cadeia de caracteres O valor que contém o valor a ser localizado.
itemToFind Sim string ou int O valor a ser encontrado.

Valor devolvido

True se o item for encontrado, caso contrário, False.

Exemplo

O exemplo a seguir mostra como usar contém com diferentes tipos:

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')

A saída do exemplo anterior com os valores padrão é:

Nome Tipo valor
stringTrue Bool True
stringFalse Bool False
objectTrue Bool True
objectFalse Bool False
arrayTrue Bool True
arrayFalse Bool False

empty

empty(itemToTest)

Determina se uma matriz, objeto ou cadeia de caracteres está vazia.

Espaço de nome: sys.

Parâmetros

Parâmetro Necessário Type Description
itemToTest Sim matriz, objeto ou cadeia de caracteres O valor para verificar se está vazio.

Valor devolvido

Retorna True se o valor estiver vazio, caso contrário, False.

Exemplo

O exemplo a seguir verifica se uma matriz, objeto e cadeia de caracteres estão vazios.

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

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

A saída do exemplo anterior com os valores padrão é:

Nome Tipo valor
arrayVazio Bool True
objectEmpty Bool True
stringEmpty Bool True

Exemplos de início rápido

O exemplo a seguir é extraído de um modelo de início rápido, Rede Virtual com configurações de logs de diagnóstico:

@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
    }
    ...
  }
}

Na expressão condicional, a função empty é usada para verificar se a matriz dnsServers é uma matriz vazia.

Primeiro

first(arg1)

Retorna o primeiro elemento da matriz ou o primeiro caractere da cadeia de caracteres.

Espaço de nome: sys.

Parâmetros

Parâmetro Necessário Type Description
Arg1 Sim matriz ou cadeia de caracteres O valor para recuperar o primeiro elemento ou caractere.

Valor devolvido

O tipo (string, int, array ou object) do primeiro elemento de uma matriz ou o primeiro caractere de uma cadeia de caracteres.

Exemplo

O exemplo a seguir mostra como usar a primeira função com uma matriz e uma cadeia de caracteres.

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

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

A saída do exemplo anterior com os valores padrão é:

Nome Tipo valor
arrayOutput String um
stringOutput String O

achatar

flatten(arrayToFlatten)

Usa uma matriz de matrizes e retorna uma matriz de elementos de submatriz, na ordem original. As submatrizes são achatadas apenas uma vez, não recursivamente.

Espaço de nome: sys.

Parâmetros

Parâmetro Necessário Type Description
arrayToFlattern Sim matriz A matriz de submatrizes a serem achatadas.

Valor devolvido

Matriz

Exemplo

O exemplo a seguir mostra como usar a função de achatamento.

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

A saída do exemplo anterior com os valores padrão é:

Nome Tipo valor
arrayOutput matriz ['um', 'dois', 'três', 'quatro', 'cinco']

indexOf

indexOf(arrayToSearch, itemToFind)

Retorna um inteiro para o índice da primeira ocorrência de um item em uma matriz. A comparação diferencia maiúsculas de minúsculas para cadeias de caracteres.

Espaço de nome: sys.

Parâmetros

Parâmetro Necessário Type Description
arrayToSearch Sim matriz A matriz a ser usada para localizar o índice do item pesquisado.
itemToFind Sim int, string, array ou objeto O item a ser encontrado na matriz.

Valor devolvido

Um inteiro que representa o primeiro índice do item na matriz. O índice é baseado em zero. Se o item não for encontrado, -1 será devolvido.

Exemplos

O exemplo a seguir mostra como usar as funções indexOf e 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)

A saída do exemplo anterior é:

Nome Tipo valor
índice1 número inteiro 1
índice2 número inteiro 0
Índice3 número inteiro 0
Índice4 número inteiro 2
Índice5 número inteiro 1
Índice6 número inteiro 0
Índice7 número inteiro 3
notFoundIndex1 número inteiro -1
notFoundIndex2 número inteiro -1

intersecção

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

Retorna uma única matriz ou objeto com os elementos comuns dos parâmetros.

Espaço de nome: sys.

Parâmetros

Parâmetro Necessário Type Description
Arg1 Sim matriz ou objeto O primeiro valor a ser usado para localizar elementos comuns.
Arg2 Sim matriz ou objeto O segundo valor a ser usado para localizar elementos comuns.
Mais argumentos Não matriz ou objeto Mais valores a serem usados para encontrar elementos comuns.

Valor devolvido

Uma matriz ou objeto com os elementos comuns. A ordem dos elementos é determinada pelo primeiro parâmetro de matriz.

Exemplo

O exemplo a seguir mostra como usar a interseção com matrizes e objetos:

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)

A saída do exemplo anterior com os valores padrão é:

Nome Tipo valor
objectOutput Object {"um": "a", "três": "c"}
arrayOutput Matriz ["dois", "três"]

O primeiro parâmetro de matriz determina a ordem dos elementos interseccionados. O exemplo a seguir mostra como a ordem dos elementos retornados é baseada em qual matriz é a primeira.

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)

A saída do exemplo anterior é:

Nome Tipo valor
comumUp matriz [1, 2, 3]
commonDown matriz [3, 2, 1]

Último

last(arg1)

Retorna o último elemento da matriz ou o último caractere da cadeia de caracteres.

Espaço de nome: sys.

Parâmetros

Parâmetro Necessário Type Description
Arg1 Sim matriz ou cadeia de caracteres O valor para recuperar o último elemento ou caractere.

Valor devolvido

O tipo (string, int, array ou object) do último elemento de uma matriz ou o último caractere de uma cadeia de caracteres.

Exemplo

O exemplo a seguir mostra como usar a última função com uma matriz e uma cadeia de caracteres.

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

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

A saída do exemplo anterior com os valores padrão é:

Nome Tipo valor
arrayOutput String três
stringOutput String e

lastIndexOf

lastIndexOf(arrayToSearch, itemToFind)

Retorna um inteiro para o índice da última ocorrência de um item em uma matriz. A comparação diferencia maiúsculas de minúsculas para cadeias de caracteres.

Espaço de nome: sys.

Parâmetros

Parâmetro Necessário Type Description
arrayToSearch Sim matriz A matriz a ser usada para localizar o índice do item pesquisado.
itemToFind Sim int, string, array ou objeto O item a ser encontrado na matriz.

Valor devolvido

Um inteiro que representa o último índice do item na matriz. O índice é baseado em zero. Se o item não for encontrado, -1 será devolvido.

Exemplos

O exemplo a seguir mostra como usar as funções indexOf e 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)

A saída do exemplo anterior é:

Nome Tipo valor
índice1 número inteiro 1
índice2 número inteiro 0
Índice3 número inteiro 0
Índice4 número inteiro 2
Índice5 número inteiro 1
Índice6 número inteiro 0
Índice7 número inteiro 3
notFoundIndex1 número inteiro -1
notFoundIndex2 número inteiro -1

length

length(arg1)

Retorna o número de elementos em uma matriz, caracteres em uma cadeia de caracteres ou propriedades de nível raiz em um objeto.

Espaço de nome: sys.

Parâmetros

Parâmetro Necessário Type Description
Arg1 Sim matriz, cadeia de caracteres ou objeto A matriz a ser usada para obter o número de elementos, a cadeia de caracteres a ser usada para obter o número de caracteres ou o objeto a ser usado para obter o número de propriedades de nível raiz.

Valor devolvido

Um int.

Exemplo

O exemplo a seguir mostra como usar o comprimento com uma matriz e uma cadeia de caracteres:

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)

A saída do exemplo anterior com os valores padrão é:

Nome Tipo valor
arrayLength Int 3
stringLength Int 13
objectLength Int 4

Exemplos de início rápido

O exemplo a seguir é extraído de um modelo de início rápido, Deploy API Management in external VNet with public IP :

@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)
  ...
}

Na expressão condicional, a length função verifica o comprimento da matriz availabilityZones.

Mais exemplos podem ser encontrados nestes arquivos de início rápido Bicep:

max

max(arg1)

Devolve o valor máximo de uma matriz de inteiros ou de uma lista de inteiros separada por vírgula.

Espaço de nome: sys.

Parâmetros

Parâmetro Necessário Type Description
Arg1 Sim matriz de inteiros ou lista de inteiros separados por vírgulas A coleção para obter o valor máximo.

Valor devolvido

Um int que representa o valor máximo.

Exemplo

O exemplo a seguir mostra como usar max com uma matriz e uma lista de inteiros:

param arrayToTest array = [
  0
  3
  2
  5
  4
]

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

A saída do exemplo anterior com os valores padrão é:

Nome Tipo valor
arrayOutput Int 5
intOutput Int 5

min

min(arg1)

Devolve o valor mínimo de uma matriz de inteiros ou de uma lista de inteiros separada por vírgula.

Espaço de nome: sys.

Parâmetros

Parâmetro Necessário Type Description
Arg1 Sim matriz de inteiros ou lista de inteiros separados por vírgulas A coleção para obter o valor mínimo.

Valor devolvido

Um int que representa o valor mínimo.

Exemplo

O exemplo a seguir mostra como usar min com uma matriz e uma lista de inteiros:

param arrayToTest array = [
  0
  3
  2
  5
  4
]

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

A saída do exemplo anterior com os valores padrão é:

Nome Tipo valor
arrayOutput Int 0
intOutput Int 0

range

range(startIndex, count)

Cria uma matriz de inteiros a partir de um inteiro inicial e contendo o número de itens.

Espaço de nome: sys.

Parâmetros

Parâmetro Necessário Type Description
startIndex Sim número inteiro O primeiro inteiro na matriz. A soma de startIndex e count não deve ser maior que 2147483647.
contagem Sim número inteiro O número de inteiros na matriz. Deve ser inteiro não negativo até 10000.

Valor devolvido

Uma matriz de inteiros.

Exemplo

O exemplo a seguir mostra como usar a função range:

param startingInt int = 5
param numberOfElements int = 3

output rangeOutput array = range(startingInt, numberOfElements)

A saída do exemplo anterior com os valores padrão é:

Nome Tipo valor
intervaloSaída Matriz [5, 6, 7]

Exemplos de início rápido

O exemplo a seguir é extraído de um modelo de início rápido, Duas VMs em VNET - Balanceador de carga interno e regras 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: {
    ...
  }
}]

O arquivo Bicep cria dois recursos networkInterface e dois virtualMachine.

Mais exemplos podem ser encontrados nestes arquivos de início rápido Bicep:

skip

skip(originalValue, numberToSkip)

Retorna uma matriz com todos os elementos após o número especificado na matriz ou retorna uma cadeia de caracteres com todos os caracteres após o número especificado na cadeia de caracteres.

Espaço de nome: sys.

Parâmetros

Parâmetro Necessário Type Description
originalValor Sim matriz ou cadeia de caracteres A matriz ou cadeia de caracteres a ser usada para ignorar.
númeroToSkip Sim número inteiro O número de elementos ou caracteres a ignorar. Se esse valor for 0 ou menos, todos os elementos ou caracteres no valor serão retornados. Se for maior do que o comprimento da matriz ou cadeia de caracteres, uma matriz ou cadeia de caracteres vazia será retornada.

Valor devolvido

Uma matriz ou cadeia de caracteres.

Exemplo

O exemplo a seguir ignora o número especificado de elementos na matriz e o número especificado de caracteres em uma cadeia de caracteres.

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)

A saída do exemplo anterior com os valores padrão é:

Nome Tipo valor
arrayOutput Matriz ["três"]
stringOutput String dois três

take

take(originalValue, numberToTake)

Retorna uma matriz com o número especificado de elementos do início da matriz ou uma cadeia de caracteres com o número especificado de caracteres do início da cadeia de caracteres.

Espaço de nome: sys.

Parâmetros

Parâmetro Necessário Type Description
originalValor Sim matriz ou cadeia de caracteres A matriz ou cadeia de caracteres da qual retirar os elementos.
númeroToTake Sim número inteiro O número de elementos ou caracteres a serem levados. Se esse valor for 0 ou menos, uma matriz ou cadeia de caracteres vazia será retornada. Se for maior do que o comprimento de uma determinada matriz ou cadeia de caracteres, todos os elementos na matriz ou cadeia de caracteres serão retornados.

Valor devolvido

Uma matriz ou cadeia de caracteres.

Exemplo

O exemplo a seguir usa o número especificado de elementos da matriz e caracteres de uma cadeia de caracteres.

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)

A saída do exemplo anterior com os valores padrão é:

Nome Tipo valor
arrayOutput Matriz ["um", "dois"]
stringOutput String em

união

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

Retorna uma única matriz ou objeto com todos os elementos dos parâmetros. Para matrizes, valores duplicados são incluídos uma vez. Para objetos, nomes de propriedade duplicados são incluídos apenas uma vez.

Espaço de nome: sys.

Parâmetros

Parâmetro Necessário Type Description
Arg1 Sim matriz ou objeto O primeiro valor a ser usado para unir elementos.
Arg2 Sim matriz ou objeto O segundo valor a ser usado para unir elementos.
Mais argumentos Não matriz ou objeto Mais valores para usar para unir elementos.

Valor devolvido

Uma matriz ou objeto.

Observações

A função união usa a sequência dos parâmetros para determinar a ordem e os valores do resultado.

Para matrizes, a função itera através de cada elemento no primeiro parâmetro e adiciona-o ao resultado se ainda não estiver presente. Em seguida, ele repete o processo para o segundo parâmetro e quaisquer outros parâmetros. Se um valor já estiver presente, seu posicionamento anterior na matriz será preservado.

Para objetos, nomes de propriedade e valores do primeiro parâmetro são adicionados ao resultado. Para parâmetros posteriores, quaisquer novos nomes são adicionados ao resultado. Se um parâmetro posterior tiver uma propriedade com o mesmo nome, esse valor substituirá o valor existente. A ordem das propriedades não é garantida.

A função união mescla não apenas os elementos de nível superior, mas também mescla recursivamente quaisquer objetos aninhados dentro deles. Os valores de matriz aninhada não são mesclados. Veja o segundo exemplo na seção a seguir.

Exemplo

O exemplo a seguir mostra como usar a união com matrizes e objetos:

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)

A saída do exemplo anterior com os valores padrão é:

Nome Tipo valor
objectOutput Object {"um": "a", "dois": "b", "três": "c2", "quatro": "d", "cinco": "e"}
arrayOutput Matriz ["um", "dois", "três", "quatro"]

O exemplo a seguir mostra a capacidade de mesclagem profunda:

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)

A saída do exemplo anterior é:

Nome Tipo valor
objectOutput Object {"propriedade":{"um":"a","dois":"b","três":"c2","quatro":"d","cinco":"e"},"nestedArray":[3,4]}
arrayOutput Matriz [["um","dois"],["três"],["quatro","dois"]]

Se matrizes aninhadas fossem mescladas, o valor de objectOutput.nestedArray seria [1, 2, 3, 4] e o valor de arrayOutput seria [["um", "dois", "três"], ["três", "quatro", "dois"]].

Próximos passos

  • Para obter uma matriz de valores de cadeia de caracteres delimitada por um valor, consulte dividir.