Funções de objetos para modelos do ARM

Artigo
02/08/2024

O Resource Manager oferece diversas funções para trabalhar com objetos no modelo do ARM (Azure Resource Manager):

contains
createObject
empty
intersection
items
json
length
null
union

Dica

Recomendamos o Bicep porque ele oferece as mesmas funcionalidades que os modelos do ARM e a sintaxe é mais fácil de usar. Para saber mais, confira funções de objeto.

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.

No Bicep, use a função contains.

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:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "stringToTest": {
      "type": "string",
      "defaultValue": "OneTwoThree"
    },
    "objectToTest": {
      "type": "object",
      "defaultValue": {
        "one": "a",
        "two": "b",
        "three": "c"
      }
    },
    "arrayToTest": {
      "type": "array",
      "defaultValue": [ "one", "two", "three" ]
    }
  },
  "resources": [
  ],
  "outputs": {
    "stringTrue": {
      "type": "bool",
      "value": "[contains(parameters('stringToTest'), 'e')]"
    },
    "stringFalse": {
      "type": "bool",
      "value": "[contains(parameters('stringToTest'), 'z')]"
    },
    "objectTrue": {
      "type": "bool",
      "value": "[contains(parameters('objectToTest'), 'one')]"
    },
    "objectFalse": {
      "type": "bool",
      "value": "[contains(parameters('objectToTest'), 'a')]"
    },
    "arrayTrue": {
      "type": "bool",
      "value": "[contains(parameters('arrayToTest'), 'three')]"
    },
    "arrayFalse": {
      "type": "bool",
      "value": "[contains(parameters('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

createObject

createObject(key1, value1, key2, value2, ...)

Cria um objeto com base nas chaves e valores.

Não há suporte para a função createObject no Bicep. Construir um objeto usando {}. Consultar Objetos.

Parâmetros

Parâmetro	Obrigatório	Type	Descrição
key1	Não	string	O nome da chave.
value1	Não	int, booliano, cadeia de caracteres, objeto ou matriz	O valor da chave.
mais chaves	Não	string	Mais nomes das chaves.
mais valores	Não	int, booliano, cadeia de caracteres, objeto ou matriz	Mais valores para as chaves.

A função somente aceita um número par de parâmetros. Cada chave deve ter um valor correspondente.

Retornar valor

Um objeto com cada par de chave e valor.

Exemplo

O exemplo a seguir cria um objeto de diferentes tipos de valores.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "resources": [
  ],
  "outputs": {
    "newObject": {
      "type": "object",
      "value": "[createObject('intProp', 1, 'stringProp', 'abc', 'boolProp', true(), 'arrayProp', createArray('a', 'b', 'c'), 'objectProp', createObject('key1', 'value1'))]"
    }
  }
}

A saída do exemplo anterior com os valores padrão é um objeto chamado newObject com o seguinte valor:

{
  "intProp": 1,
  "stringProp": "abc",
  "boolProp": true,
  "arrayProp": ["a", "b", "c"],
  "objectProp": {"key1": "value1"}
}

vazio

empty(itemToTest)

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

No Bicep, use a função empty.

Parâmetros

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

Retornar valor

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

Exemplo

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

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "testArray": {
      "type": "array",
      "defaultValue": []
    },
    "testObject": {
      "type": "object",
      "defaultValue": {}
    },
    "testString": {
      "type": "string",
      "defaultValue": ""
    }
  },
  "resources": [
  ],
  "outputs": {
    "arrayEmpty": {
      "type": "bool",
      "value": "[empty(parameters('testArray'))]"
    },
    "objectEmpty": {
      "type": "bool",
      "value": "[empty(parameters('testObject'))]"
    },
    "stringEmpty": {
      "type": "bool",
      "value": "[empty(parameters('testString'))]"
    }
  }
}

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

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

interseção

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

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

No Bicep, use a função intersection.

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.

Exemplo

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

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "firstObject": {
      "type": "object",
      "defaultValue": {
        "one": "a",
        "two": "b",
        "three": "c"
      }
    },
    "secondObject": {
      "type": "object",
      "defaultValue": {
        "one": "a",
        "two": "z",
        "three": "c"
      }
    },
    "firstArray": {
      "type": "array",
      "defaultValue": [ "one", "two", "three" ]
    },
    "secondArray": {
      "type": "array",
      "defaultValue": [ "two", "three" ]
    }
  },
  "resources": [
  ],
  "outputs": {
    "objectOutput": {
      "type": "object",
      "value": "[intersection(parameters('firstObject'), parameters('secondObject'))]"
    },
    "arrayOutput": {
      "type": "array",
      "value": "[intersection(parameters('firstArray'), parameters('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"]

itens

items(object)

Converte um objeto de dicionário em uma matriz. Confira toObject sobre como converter uma matriz em um objeto.

No Bicep, use os itens.

Parâmetros

Parâmetro	Obrigatório	Type	Descrição
objeto	Sim	objeto	O objeto de dicionário a ser convertido em uma matriz.

Valor retornado

Uma matriz de objetos para o dicionário convertido. Cada objeto na matriz tem uma propriedade key que contém o valor de chave para o dicionário. Cada objeto também tem uma propriedade value que contém as propriedades do objeto .

Exemplo

O exemplo a seguir converte um objeto de dicionário em uma matriz. Para cada objeto na matriz, ele cria um novo objeto com valores modificados.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "variables": {
    "copy": [
      {
        "name": "modifiedListOfEntities",
        "count": "[length(items(variables('entities')))]",
        "input": {
          "key": "[items(variables('entities'))[copyIndex('modifiedListOfEntities')].key]",
          "fullName": "[items(variables('entities'))[copyIndex('modifiedListOfEntities')].value.displayName]",
          "itemEnabled": "[items(variables('entities'))[copyIndex('modifiedListOfEntities')].value.enabled]"
        }
      }
    ],
    "entities": {
      "item002": {
        "enabled": false,
        "displayName": "Example item 2",
        "number": 200
      },
      "item001": {
        "enabled": true,
        "displayName": "Example item 1",
        "number": 300
      }
    }
  },
  "resources": [],
  "outputs": {
    "modifiedResult": {
      "type": "array",
      "value": "[variables('modifiedListOfEntities')]"
    }
  }
}

O exemplo anterior retorna:

"modifiedResult": {
  "type": "Array",
  "value": [
    {
      "fullName": "Example item 1",
      "itemEnabled": true,
      "key": "item001"
    },
    {
      "fullName": "Example item 2",
      "itemEnabled": false,
      "key": "item002"
    }
  ]
}

O exemplo a seguir mostra a matriz retornada da função de itens.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "variables": {
    "entities": {
      "item002": {
        "enabled": false,
        "displayName": "Example item 2",
        "number": 200
      },
      "item001": {
        "enabled": true,
        "displayName": "Example item 1",
        "number": 300
      }
    },
    "entitiesArray": "[items(variables('entities'))]"
  },
  "resources": [],
  "outputs": {
    "itemsResult": {
      "type": "array",
      "value": "[variables('entitiesArray')]"
    }
  }
}

O exemplo retorna:

"itemsResult": {
  "type": "Array",
  "value": [
    {
      "key": "item001",
      "value": {
        "displayName": "Example item 1",
        "enabled": true,
        "number": 300
      }
    },
    {
      "key": "item002",
      "value": {
        "displayName": "Example item 2",
        "enabled": false,
        "number": 200
      }
    }
  ]
}

No JSON, um objeto é uma coleção não ordenada de zero ou mais pares chave-valor. A ordenação pode ser diferente, dependendo das implementações. Por exemplo, a função items() do Bicep classifica os objetos na ordem alfabética. Em outros locais, a ordenação original pode ser preservada. Devido a esse não determinismo, evite fazer suposições sobre a ordem das chaves de objeto ao escrever códigos que interagem com parâmetros e saídas de implantações.

json

json(arg1)

Converte uma cadeia de caracteres JSON válida em um tipo de dados JSON.

No Bicep, use a função json.

Parâmetros

Parâmetro	Obrigatório	Type	Descrição
arg1	Sim	string	O valor a ser convertido para JSON. A cadeia de caracteres deve ser uma cadeia de caracteres JSON formatada corretamente.

Retornar valor

O tipo de dados JSON de cadeia de caracteres especificada, ou um valor vazio quando nulo for especificado.

Comentários

Se você precisar incluir um valor de parâmetro ou variável no objeto JSON, use a função format para criar a cadeia de caracteres que você passa para a função.

Você também pode usar null() para obter um valor nulo.

Exemplo

O exemplo a seguir mostra como usar a função json. Observe que você pode passar null para um objeto vazio.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "jsonEmptyObject": {
      "type": "string",
      "defaultValue": "null"
    },
    "jsonObject": {
      "type": "string",
      "defaultValue": "{\"a\": \"b\"}"
    },
    "jsonString": {
      "type": "string",
      "defaultValue": "\"test\""
    },
    "jsonBoolean": {
      "type": "string",
      "defaultValue": "true"
    },
    "jsonInt": {
      "type": "string",
      "defaultValue": "3"
    },
    "jsonArray": {
      "type": "string",
      "defaultValue": "[[1,2,3 ]"
    },
    "concatValue": {
      "type": "string",
      "defaultValue": "demo value"
    }
  },
  "resources": [
  ],
  "outputs": {
    "emptyObjectOutput": {
      "type": "bool",
      "value": "[empty(json(parameters('jsonEmptyObject')))]"
    },
    "objectOutput": {
      "type": "object",
      "value": "[json(parameters('jsonObject'))]"
    },
    "stringOutput": {
      "type": "string",
      "value": "[json(parameters('jsonString'))]"
    },
    "booleanOutput": {
      "type": "bool",
      "value": "[json(parameters('jsonBoolean'))]"
    },
    "intOutput": {
      "type": "int",
      "value": "[json(parameters('jsonInt'))]"
    },
    "arrayOutput": {
      "type": "array",
      "value": "[json(parameters('jsonArray'))]"
    },
    "concatObjectOutput": {
      "type": "object",
      "value": "[json(concat('{\"a\": \"', parameters('concatValue'), '\"}'))]"
    }
  }
}

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

Nome	Tipo	Valor
emptyObjectOutput	Booliano	verdadeiro
objectOutput	Objeto	{"a": "b"}
stringOutput	String	test
booleanOutput	Booliano	verdadeiro
intOutput	Integer	3
arrayOutput	Array	[ 1, 2, 3 ]
concatObjectOutput	Objeto	{"a": "demo value"}

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.

No Bicep, use a função length.

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:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "arrayToTest": {
      "type": "array",
      "defaultValue": [
        "one",
        "two",
        "three"
      ]
    },
    "stringToTest": {
      "type": "string",
      "defaultValue": "One Two Three"
    },
    "objectToTest": {
      "type": "object",
      "defaultValue": {
        "propA": "one",
        "propB": "two",
        "propC": "three",
        "propD": {
          "propD-1": "sub",
          "propD-2": "sub"
        }
      }
    }
  },
  "resources": [],
  "outputs": {
    "arrayLength": {
      "type": "int",
      "value": "[length(parameters('arrayToTest'))]"
    },
    "stringLength": {
      "type": "int",
      "value": "[length(parameters('stringToTest'))]"
    },
    "objectLength": {
      "type": "int",
      "value": "[length(parameters('objectToTest'))]"
    }
  }
}

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

Nome	Tipo	Valor
arrayLength	int	3
stringLength	int	13
objectLength	int	4

null

null()

Retorna um valor nulo.

A função null não está disponível no Bicep. Em vez disso, use a palavra-chave null.

Parâmetros

A função nula não aceita nenhum parâmetro.

Retornar valor

Um valor que é sempre nulo.

Exemplo

O exemplo a seguir usa a função “nulo”.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "resources": [],
  "outputs": {
    "emptyOutput": {
      "type": "bool",
      "value": "[empty(null())]"
    }
  }
}

O resultado do exemplo anterior é:

Nome	Tipo	Valor
emptyOutput	Bool	True

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.

No Bicep, use a função union.

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 de união mescla não apenas os elementos de nível superior, mas também mescla recursivamente qualquer matriz e objeto aninhado dentro deles. Veja o segundo exemplo na seção a seguir.

Exemplo

O exemplo a seguir mostra como usar a union com matrizes e objetos:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "firstObject": {
      "type": "object",
      "defaultValue": {
        "one": "a",
        "two": "b",
        "three": "c1"
      }
    },
    "secondObject": {
      "type": "object",
      "defaultValue": {
        "three": "c2",
        "four": "d",
        "five": "e"
      }
    },
    "firstArray": {
      "type": "array",
      "defaultValue": [ "one", "two", "three" ]
    },
    "secondArray": {
      "type": "array",
      "defaultValue": [ "three", "four" ]
    }
  },
  "resources": [
  ],
  "outputs": {
    "objectOutput": {
      "type": "object",
      "value": "[union(parameters('firstObject'), parameters('secondObject'))]"
    },
    "arrayOutput": {
      "type": "array",
      "value": "[union(parameters('firstArray'), parameters('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:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "variables": {
    "firstObject": {
      "property": {
        "one": "a",
        "two": "b",
        "three": "c1"
      },
      "nestedArray": [
        1,
        2
      ]
    },
    "secondObject": {
      "property": {
        "three": "c2",
        "four": "d",
        "five": "e"
      },
      "nestedArray": [
        3,
        4
      ]
    },
    "firstArray": [
      [
        "one",
        "two"
      ],
      [
        "three"
      ]
    ],
    "secondArray": [
      [
        "three"
      ],
      [
        "four",
        "two"
      ]
    ]
  },
  "resources": [],
  "outputs": {
    "objectOutput": {
      "type": "Object",
      "value": "[union(variables('firstObject'), variables('secondObject'))]"
    },
    "arrayOutput": {
      "type": "Array",
      "value": "[union(variables('firstArray'), variables('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 descrição das seções de um modelo do ARM, confira Entender a estrutura e a sintaxe dos modelos do ARM.

Funções de objetos para modelos do ARM

contém

Parâmetros

Retornar valor

Exemplo

createObject

Parâmetros

Retornar valor

Exemplo

vazio

Parâmetros

Retornar valor

Exemplo

interseção

Parâmetros

Retornar valor

Exemplo

itens

Parâmetros

Valor retornado

Exemplo

json

Parâmetros

Retornar valor

Comentários

Exemplo

comprimento

Parâmetros

Retornar valor

Exemplo

null

Parâmetros

Retornar valor

Exemplo

union

Parâmetros

Retornar valor

Comentários

Exemplo

Próximas etapas

Recursos adicionais