Funções de objeto para modelos ARM
O Resource Manager fornece várias funções para trabalhar com objetos no seu modelo do Azure Resource Manager (modelo ARM):
Gorjeta
Recomendamos o Bicep porque ele oferece os mesmos recursos que os modelos ARM e a sintaxe é mais fácil de usar. Para saber mais, consulte 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 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.
No Bicep, utilize a função contém .
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 contains com diferentes tipos:
{
"$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 | False |
| objectTrue | Bool | True |
| objectFalse | Bool | False |
| arrayTrue | Bool | True |
| arrayFalse | Bool | False |
createObject
createObject(key1, value1, key2, value2, ...)
Cria um objeto a partir das chaves e valores.
A createObject função não é suportada pelo Bicep. Construa um objeto usando {}. Consulte Objetos.
Parâmetros
| Parâmetro | Necessário | Type | Description |
|---|---|---|---|
| chave1 | Não | string | O nome da chave. |
| valor1 | Não | int, booleano, string, objeto ou array | O valor da chave. |
| mais chaves | Não | string | Mais nomes das chaves. |
| mais valores | Não | int, booleano, string, objeto ou array | Mais valores para as chaves. |
A função só aceita um número par de parâmetros. Cada chave deve ter um valor correspondente.
Valor devolvido
Um objeto com cada par de chave e valor.
Exemplo
O exemplo a seguir cria um objeto a partir 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 nomeado newObject com o seguinte valor:
{
"intProp": 1,
"stringProp": "abc",
"boolProp": true,
"arrayProp": ["a", "b", "c"],
"objectProp": {"key1": "value1"}
}
empty
empty(itemToTest)
Determina se uma matriz, objeto ou cadeia de caracteres está vazia.
No Bicep, use a função vazia .
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.
{
"$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 |
|---|---|---|
| arrayVazio | Bool | True |
| objectEmpty | Bool | True |
| stringEmpty | Bool | True |
intersecção
intersection(arg1, arg2, arg3, ...)
Retorna uma única matriz ou objeto com os elementos comuns dos parâmetros.
No Bicep, use a função de interseção .
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.
Exemplo
O exemplo a seguir mostra como usar intersection 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 | Object | {"um": "a", "três": "c"} |
| arrayOutput | Matriz | ["dois", "três"] |
itens
items(object)
Converte um objeto de dicionário em uma matriz. Consulte toObject sobre como converter uma matriz em um objeto.
No Bicep, use os itens.
Parâmetros
| Parâmetro | Necessário | Type | Description |
|---|---|---|---|
| objeto | Sim | objeto | O objeto de dicionário a ser convertido em uma matriz. |
Valor devolvido
Uma matriz de objetos para o dicionário convertido. Cada objeto na matriz tem uma key propriedade que contém o valor da chave para o dicionário. Cada objeto também tem uma value propriedade que contém as propriedades para o 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 que é retornada da função items.
{
"$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
}
}
]
}
Em 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 Bicep items() classifica os objetos na ordem alfabética. Em outros lugares, o pedido original pode ser preservado. Devido a esse não-determinismo, evite fazer suposições sobre a ordenação de chaves de objeto ao escrever código, que interage com parâmetros de implantação e saídas.
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 | Necessário | Type | Description |
|---|---|---|---|
| Arg1 | Sim | string | O valor a ser convertido em JSON. A cadeia de caracteres deve ser uma cadeia de caracteres JSON formatada corretamente. |
Valor devolvido
O tipo de dados JSON da cadeia de caracteres especificada ou um valor vazio quando null é especificado.
Observações
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 json função. Observe que você pode passar para um null 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 | Boolean | True |
| objectOutput | Object | {"a": "b"} |
| stringOutput | String | test |
| booleanOutput | Boolean | True |
| intOutput | Número inteiro | 3 |
| arrayOutput | Matriz | [ 1, 2, 3 ] |
| concatObjectOutput | Object | { "a": "valor de demonstração" } |
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.
No Bicep, use a função de comprimento .
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 length com uma matriz e uma 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 |
nulo
null()
Retorna null.
A null função não está disponível no Bicep. Em vez disso, use a null palavra-chave.
Parâmetros
A função null não aceita nenhum parâmetro.
Valor devolvido
Um valor que é sempre nulo.
Exemplo
O exemplo a seguir usa a função null.
{
"$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())]"
}
}
}
A saída do exemplo anterior é:
| Nome | Tipo | valor |
|---|---|---|
| emptyOutput | Bool | True |
objectKeys
objectKeys(object)
Retorna as chaves de um objeto, onde um objeto é uma coleção de pares chave-valor.
No Bicep, use a função objectKeys .
Parâmetros
| Parâmetro | Necessário | Type | Description |
|---|---|---|---|
| objeto | Sim | objeto | O objeto, que é uma coleção de pares chave-valor. |
Valor devolvido
Uma matriz.
Exemplo
O exemplo a seguir mostra como usar objectKeys com um objeto:
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"variables": {
"obj": {
"a": 1,
"b": 2
}
},
"resources": [],
"outputs": {
"keyArray": {
"type": "array",
"value": "[objectKeys(variables('obj'))]"
}
}
}
A saída do exemplo anterior é:
| Nome | Tipo | valor |
|---|---|---|
| chaveArray | Matriz | [ "a", "b" ] |
Em 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 Bicep items() classifica os objetos na ordem alfabética. Em outros lugares, o pedido original pode ser preservado. Devido a esse não-determinismo, evite fazer suposições sobre a ordenação de chaves de objeto ao escrever código, que interage com parâmetros de implantação e saídas.
shallowMerge
shallowMerge(inputArray)
Combina uma matriz de objetos, onde apenas os objetos de nível superior são mesclados. Isso significa que, se os objetos que estão sendo mesclados contiverem objetos aninhados, esses objetos aninhados não serão profundamente mesclados; em vez disso, eles são substituídos inteiramente pela propriedade correspondente do objeto de mesclagem.
No Bicep, use a função shallowMerge .
Parâmetros
| Parâmetro | Necessário | Type | Description |
|---|---|---|---|
| inputArray | Sim | matriz | Uma matriz de objetos. |
Valor devolvido
Um objeto.
Exemplo
O exemplo a seguir mostra como usar shallowMerge:
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"variables": {
"firstArray": [
{
"one": "a"
},
{
"two": "b"
},
{
"two": "c"
}
],
"secondArray": [
{
"one": "a",
"nested": {
"a": 1,
"nested": {
"c": 3
}
}
},
{
"two": "b",
"nested": {
"b": 2
}
}
]
},
"resources": [],
"outputs": {
"firstOutput": {
"type": "object",
"value": "[shallowMerge(variables('firstArray'))]"
},
"secondOutput": {
"type": "object",
"value": "[shallowMerge(variables('secondArray'))]"
}
}
}
A saída do exemplo anterior com os valores padrão é:
| Nome | Tipo | valor |
|---|---|---|
| firstOutput | objeto | {"um":"a","dois":"c"} |
| segundoSaída | objeto | {"um":"a","aninhado":{"b":2},"dois":"b"} |
firstOutput mostra as propriedades dos objetos de mesclagem são combinadas em um novo objeto. Se houver propriedades conflitantes (ou seja, propriedades com o mesmo nome), a propriedade do último objeto que está sendo mesclado geralmente tem precedência.
secondOutput mostra que a mesclagem superficial não mescla recursivamente esses objetos aninhados. Em vez disso, todo o objeto aninhado é substituído pela propriedade correspondente do objeto de mesclagem.
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.
No Bicep, use a função de união .
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 parâmetros adicionais. 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 matrizes e objetos aninhados dentro deles. Veja o segundo exemplo na seção a seguir.
Exemplo
O exemplo a seguir mostra como usar 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 | 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:
{
"$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'))]"
}
}
}
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 descrição das seções em um modelo ARM, consulte Compreender a estrutura e a sintaxe dos modelos ARM.