Compartilhar via

Funções de matriz para Bicep

  • Artigo

Este artigo descreve as funções bicep para trabalhar com matrizes. As funções lambda para trabalhar com matrizes podem ser encontradas aqui.

array

array(convertToArray)

Converte o valor em uma matriz.

Namespace: sys.

Parâmetros

Parâmetro Obrigatório Type Descrição
convertToArray Sim int, string, array ou object O valor a ser convertido em uma matriz.

Retornar valor

Uma matriz .

Exemplo

O seguinte exemplo mostra como usar a função array com tipos diferentes.

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 Array [1]
stringOutput Array ["efgh"]
objectOutput Array [{"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.

Namespace: sys.

Parâmetros

Parâmetro Obrigatório Type Descrição
arg1 Sim matriz A primeira matriz de concatenação.
mais argumentos Não array Matrizes adicionais em ordem sequencial para concatenação.

Essa função usa qualquer número de matrizes e as combina.

Valor retornado

Uma matriz de valores concatenados.

Exemplo

O próximo exemplo 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
return Array ["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 subcadeia de caracteres. 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.

Namespace: sys.

Parâmetros

Parâmetro Obrigatório Type Descrição
contêiner Sim matriz, objeto ou cadeia de caracteres O valor que contém o valor a ser encontrado.
itemToFind Sim cadeia de caracteres ou inteiro O valor a ser encontrado.

Retornar valor

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

Exemplo

O seguinte exemplo mostra como usar contains com tipos diferentes:

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 Falso
objectTrue Bool True
objectFalse Bool Falso
arrayTrue Bool True
arrayFalse Bool Falso

empty

empty(itemToTest)

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

Namespace: sys.

Parâmetros

Parâmetro Obrigatório Type Descrição
itemToTest Sim matriz, objeto ou cadeia de caracteres O valor a ser verificado se está vazio ou nulo.

Valor retornado

Retorna True se o valor for vazio ou nulo; caso contrário, False.

Exemplo

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

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)

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

Nome Tipo Valor
arrayEmpty Bool True
objectEmpty Bool True
stringEmpty Bool Verdadeiro
stringNull Bool True

Exemplos de início rápido

O exemplo a seguir foi 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 vazia é usada para verificar se a matriz dnsServers é uma matriz vazia.

first

first(arg1)

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

Namespace: sys.

Parâmetros

Parâmetro Obrigatório Type Descrição
arg1 Sim matriz ou cadeia de caracteres O valor para recuperar o primeiro elemento ou caractere.

Retornar valor

O tipo (cadeia de caracteres, inteiro, matriz ou objeto) do primeiro elemento em 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 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 one
stringOutput String O

mesclar

flatten(arrayToFlatten)

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

Namespace: sys.

Parâmetros

Parâmetro Obrigatório Type Descrição
arrayToFlattern Sim matriz A matriz de submatrizes a serem mescladas.

Retornar valor

Array

Exemplo

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

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 array ['one', 'two', 'three', 'four', 'five']

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 nas cadeias de caracteres.

Namespace: sys.

Parâmetros

Parâmetro Obrigatório Type Descrição
arrayToSearch Sim matriz A matriz a ser usada para localizar o índice do item pesquisado.
itemToFind Sim int, string, array ou object O item a ser encontrado na matriz.

Valor retornado

Um inteiro que representa o primeiro índice do item na matriz. O índice começa no zero. Se o item não for encontrado, -1 será retornado.

Exemplos

O seguinte exemplo 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)

O resultado do exemplo anterior é:

Nome Tipo Valor
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

interseção

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

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

Namespace: sys.

Parâmetros

Parâmetro Obrigatório Type Descrição
arg1 Sim objeto ou matriz O primeiro valor a ser usado para localizar elementos comuns.
arg2 Sim objeto ou matriz O segundo valor a ser usado para localizar elementos comuns.
mais argumentos Não objeto ou matriz Mais valores a serem usados para localizar elementos comuns.

Retornar valor

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 Objeto {"one": "a", "three": "c"}
arrayOutput Array ["two", "three"]

O primeiro parâmetro de matriz determina a ordem dos elementos interseccionais. 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)

O resultado do exemplo anterior é:

Nome Tipo Valor
commonUp array [1, 2, 3]
commonDown array [3, 2, 1]

last

last(arg1)

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

Namespace: sys.

Parâmetros

Parâmetro Obrigatório Type Descrição
arg1 Sim matriz ou cadeia de caracteres O valor para recuperar o último elemento ou caractere.

Retornar valor

O tipo (cadeia de caracteres, inteiro, matriz ou objeto) do último elemento em 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 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 nas cadeias de caracteres.

Namespace: sys.

Parâmetros

Parâmetro Obrigatório Type Descrição
arrayToSearch Sim matriz A matriz a ser usada para localizar o índice do item pesquisado.
itemToFind Sim int, string, array ou object O item a ser encontrado na matriz.

Valor retornado

Um inteiro que representa o último índice do item na matriz. O índice começa no zero. Se o item não for encontrado, -1 será retornado.

Exemplos

O seguinte exemplo 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)

O resultado do exemplo anterior é:

Nome Tipo Valor
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

comprimento

length(arg1)

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

Namespace: sys.

Parâmetros

Parâmetro Obrigatório Type Descrição
arg1 Sim matriz, cadeia de caracteres ou objeto A matriz usada para obter o número de elementos, a cadeia de caracteres usada para obter o número de caracteres ou o objeto usado para obter o número de propriedades em nível raiz.

Retornar valor

Um inteiro.

Exemplo

O seguinte exemplo mostra como usar length com uma matriz e 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, Implantar Gerenciamento de API na VNet externa com IP público:

@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 tamanho da matriz availabilityZones.

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

max

max(arg1)

Retorna o valor máximo de uma matriz de inteiros ou uma lista de inteiros separados por vírgulas.

Namespace: sys.

Parâmetros

Parâmetro Obrigatório Type Descrição
arg1 Sim matriz de inteiros ou lista de inteiros separados por vírgulas A coleção para obtenção do valor máximo.

Retornar valor

Um inteiro que representa o valor máximo.

Exemplo

O seguinte exemplo 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)

Retorna o valor mínimo de uma matriz de inteiros ou uma lista de inteiros separados por vírgulas.

Namespace: sys.

Parâmetros

Parâmetro Obrigatório Type Descrição
arg1 Sim matriz de inteiros ou lista de inteiros separados por vírgulas A coleção para obtenção do valor mínimo.

Retornar valor

Um inteiro que representa o valor mínimo.

Exemplo

O seguinte exemplo 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 de um inteiro inicial e que contém o número de itens.

Namespace: sys.

Parâmetros

Parâmetro Obrigatório Type Descrição
startIndex Sim INT O primeiro inteiro na matriz. A soma de startIndex e Count não deve ser maior que 2147483647.
count Sim INT O número de inteiros na matriz. Deve ser um inteiro não negativo de até 10000.

Retornar valor

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
rangeOutput Array [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 na VNET – Load Balancer Interno e regras de 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 recursos virtualMachine.

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

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.

Namespace: sys.

Parâmetros

Parâmetro Obrigatório Type Descrição
originalValue Sim matriz ou cadeia de caracteres A matriz ou cadeia de caracteres a ser usada para ignorar.
numberToSkip Sim INT O número de elementos ou caracteres a ser ignorado. Se esse valor for 0 ou menos, todos os elementos ou caracteres no valor serão retornados. Se ele for maior que o tamanho da matriz ou da cadeia de caracteres, uma matriz ou uma cadeia de caracteres vazia será retornada.

Retornar valor

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 Array ["three"]
stringOutput String two three

take

take(originalValue, numberToTake)

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

Namespace: sys.

Parâmetros

Parâmetro Obrigatório Type Descrição
originalValue Sim matriz ou cadeia de caracteres A matriz ou cadeia de caracteres da qual extrair os elementos.
numberToTake Sim INT O número de elementos ou caracteres a ser extraído. Se esse valor for 0 ou menos, uma matriz ou cadeia de caracteres vazia será retornada. Se ele for maior que o tamanho da matriz ou da cadeia de caracteres especificada, todos os elementos da matriz ou da cadeia de caracteres serão retornados.

Retornar valor

Uma matriz ou cadeia de caracteres.

Exemplo

O exemplo a seguir extrai o número especificado de elementos da matriz e de 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 Array ["one", "two"]
stringOutput String on

union

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

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

Namespace: sys.

Parâmetros

Parâmetro Obrigatório Type Descrição
arg1 Sim objeto ou matriz O primeiro valor a ser usado para unir elementos.
arg2 Sim objeto ou matriz O segundo valor a ser usado para unir elementos.
mais argumentos Não objeto ou matriz Mais valores a serem usados para unir elementos.

Retornar valor

Uma matriz ou objeto.

Comentários

A função union 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 o adiciona ao resultado se ainda não estiver presente. Em seguida, ele repete o processo para o segundo parâmetro e quaisquer parâmetros adicionais. Se um valor já estiver presente, o posicionamento anterior na matriz será preservado.

Para objetos, nomes de propriedades e valores do primeiro parâmetro são adicionados ao resultado. Para parâmetros posteriores, todos os 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 union mescla não apenas os elementos de nível superior, mas também mescla recursivamente qualquer objeto aninhado dentro deles. Os valores da 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 union 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 Objeto {"one": "a", "two": "b", "three": "c2", "four": "d", "five": "e"}
arrayOutput Array ["one", "two", "three", "four"]

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)

O resultado do exemplo anterior é:

Nome Tipo Valor
objectOutput Objeto {"property":{"one":"a","two":"b","three":"c2","four":"d","five":"e"},"nestedArray":[3,4]}
arrayOutput Array [["one","two"],["three"],["four","two"]]

Se as matrizes aninhadas forem mescladas, o valor de objectOutput.nestedArray será [1, 2, 3, 4], e o valor de arrayOutput será [["one", "two", "three"], ["three", "four", "two"]].

Próximas etapas

  • Para obter uma matriz de valores de cadeia de caracteres delimitada por um valor, confira split.