Funciones de objeto para plantillas de Resource Manager

  • Artículo

Resource Manager proporciona varias funciones para trabajar con objetos en la plantilla de Resource Manager:

Sugerencia

Se recomienda Bicep porque ofrece las mismas funcionalidades que las plantillas de ARM y la sintaxis es más fácil de usar. Para más información, consulte las funciones de objeto.

contains

contains(container, itemToFind)

Comprueba si una matriz contiene un valor, un objeto contiene una clave o una cadena contiene una subcadena. La comparación de cadena distingue mayúsculas de minúsculas. Pero, cuando se prueba si un objeto contiene una clave, la comparación no distingue mayúsculas de minúsculas.

En Bicep, use la función contains.

Parámetros

Parámetro Obligatorio Type Descripción
contenedor Sí matriz, objeto o cadena El valor que contiene el valor para buscar.
itemToFind Sí cadena o entero El valor para buscar.

Valor devuelto

True si el elemento se encuentra; en caso contrario, False.

Ejemplo

En el ejemplo siguiente se muestra cómo utilizar contains con 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')]"
    }
  }
}

La salida del ejemplo anterior con el valor predeterminado es:

Nombre Tipo Value
stringTrue Bool True
stringFalse Bool False
objectTrue Bool True
objectFalse Bool False
arrayTrue Bool True
arrayFalse Bool False

createObject

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

Crea un objeto a partir de las claves y los valores.

La función createObject no es compatible con Bicep. Construya un objeto mediante {}. Vea Objetos.

Parámetros

Parámetro Obligatorio Type Descripción
key1 No string El nombre de la clave.
value1 No int, booleano, cadena, objeto o matriz Valor de la clave.
más claves No string Más nombres de las claves.
más valores No int, booleano, cadena, objeto o matriz Más valores para las claves.

La función solo acepta un número par de parámetros. Cada clave debe tener un valor coincidente.

Valor devuelto

Un objeto con cada par de clave y valor.

Ejemplo

En el ejemplo siguiente se crea un objeto a partir de distintos 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'))]"
    }
  }
}

La salida del ejemplo anterior con los valores predeterminados es un objeto denominado newObjectcon el siguiente valor:

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

empty

empty(itemToTest)

Determina si una matriz, un objeto o una cadena están vacíos.

En Bicep, use la función empty.

Parámetros

Parámetro Obligatorio Type Descripción
itemToTest Sí matriz, objeto o cadena El valor para comprobar si está vacío.

Valor devuelto

Devuelve True si el valor está vacío; en caso contrario, False.

Ejemplo

En el ejemplo siguiente se comprueba si una matriz, un objeto y una cadena están vacíos.

{
  "$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'))]"
    }
  }
}

La salida del ejemplo anterior con el valor predeterminado es:

Nombre Tipo Value
arrayEmpty Bool True
objectEmpty Bool True
stringEmpty Bool True

intersección

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

Devuelve una única matriz u objeto con los elementos comunes de los parámetros.

En Bicep, use la función intersection.

Parámetros

Parámetro Obligatorio Type Descripción
arg1 Sí matriz u objeto El primer valor que se utilizará para buscar elementos comunes.
arg2 Sí matriz u objeto El segundo valor que se utilizará para buscar elementos comunes.
más argumentos No matriz u objeto Más valores que se utilizarán para buscar elementos comunes.

Valor devuelto

Una matriz o un objeto con los elementos comunes.

Ejemplo

En el ejemplo siguiente se muestra cómo utilizar la intersección con matrices y 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'))]"
    }
  }
}

La salida del ejemplo anterior con el valor predeterminado es:

Nombre Tipo Value
objectOutput Object {"one": "a", "three": "c"}
arrayOutput Array ["two", "three"]

items

items(object)

Convierte un objeto de diccionario en una matriz. Consulta toObject acerca de cómo convertir una matriz en un objeto.

En Bicep, use los elementos.

Parámetros

Parámetro Obligatorio Type Description
object Sí object El objeto de diccionario que se va a convertir en una matriz.

Valor devuelto

Una matriz de objetos para el diccionario convertido. Cada objeto de la matriz tiene una propiedad key que contiene el valor de clave para el diccionario. Además, cada objeto tiene una propiedad value que contiene las propiedades para el objeto.

Ejemplo

En el ejemplo siguiente se convierte un objeto de diccionario en una matriz. Para cada objeto de la matriz, crea un objeto con 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')]"
    }
  }
}

El ejemplo anterior devuelve:

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

En el ejemplo siguiente se muestra la matriz que se devuelve de la función 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')]"
    }
  }
}

El ejemplo devuelve:

"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
      }
    }
  ]
}

En JSON, un objeto es una colección desordenada de cero o más pares clave-valor. El orden puede ser diferente en función de las implementaciones. Por ejemplo, la función Bicep items() ordena los objetos por orden alfabético. En otros lugares, se puede conservar la ordenación original. Debido a este no determinismo, evite realizar suposiciones sobre el orden de las claves de objeto al escribir código, que interactúa con los parámetros y salidas de implementación.

json

json(arg1)

Convierte una cadena JSON válida en un tipo de datos JSON.

En Bicep, use la función json.

Parámetros

Parámetro Obligatorio Type Descripción
arg1 Sí string Valor que se va a convertir en JSON. La cadena debe ser una cadena JSON con el formato correcto.

Valor devuelto

El tipo de datos JSON de la cadena especificada o un valor vacío si se especifica null.

Comentarios

Si necesita incluir un valor de parámetro o una variable en el objeto JSON, use la función de formato para crear la cadena que pasa a la función.

También puede usar null () para obtener un valor null.

Ejemplo

En el ejemplo siguiente se muestra cómo usar la función json. Tenga en cuenta que puede pasar null para un objeto vacío.

{
  "$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'), '\"}'))]"
    }
  }
}

La salida del ejemplo anterior con el valor predeterminado es:

Nombre Tipo Value
emptyObjectOutput Boolean True
objectOutput Object {"a": "b"}
stringOutput String test
booleanOutput Boolean True
intOutput Entero 3
arrayOutput Array [ 1, 2, 3 ]
concatObjectOutput Object {"a": "demo value"}

length

length(arg1)

Devuelve el número de elementos de una matriz, caracteres de una cadena o propiedades de nivel raíz de un objeto.

En Bicep, use la función length.

Parámetros

Parámetro Obligatorio Type Descripción
arg1 Sí matriz, cadena u objeto La matriz que se usará para obtener el número de elementos, la cadena que se usará para obtener el número de caracteres o el objeto que se usará para obtener el número de propiedades del nivel raíz.

Valor devuelto

Un entero.

Ejemplo

En el ejemplo siguiente se muestra cómo utilizar length con una matriz y una cadena:

{
  "$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'))]"
    }
  }
}

La salida del ejemplo anterior con el valor predeterminado es:

Nombre Tipo Value
arrayLength Int 3
stringLength Int 13
objectLength Int 4

null

null()

Devuelve NULL.

La función null no está disponible en Bicep. En su lugar, use la palabra clave null.

Parámetros

La función null no acepta ningún parámetro.

Valor devuelto

Valor booleano que siempre es null.

Ejemplo

En el siguiente ejemplo se utiliza la función 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())]"
    }
  }
}

El resultado del ejemplo anterior es:

Nombre Tipo Value
emptyOutput Bool True

union

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

Devuelve una única matriz u objeto con todos los elementos de los parámetros. Para las matrices, los valores duplicados se incluyen una vez. Para los objetos, los nombres de propiedad duplicados solo se incluyen una vez.

En Bicep, use la función union.

Parámetros

Parámetro Obligatorio Type Descripción
arg1 Sí matriz u objeto El primer valor que se utiliza para unir elementos.
arg2 Sí matriz u objeto El segundo valor que se utiliza para unir elementos.
más argumentos No matriz u objeto Más valores que se utilizan para unir elementos.

Valor devuelto

Una matriz u objeto.

Comentarios

La función de unión usa la secuencia de los parámetros para determinar el orden y los valores del resultado.

Para las matrices, la función se itera por cada elemento del primer parámetro y lo agrega al resultado si no está presente. A continuación, repite el proceso para el segundo parámetro y los parámetros adicionales. Si un valor ya existe, se conserva su ubicación anterior en la matriz.

En el caso de los objetos, los nombres de propiedad y los valores del primer parámetro se agregan al resultado. Para los parámetros posteriores, se agregarán los nuevos nombres al resultado. Si un parámetro posterior tiene una propiedad con el mismo nombre, ese valor sobrescribe el valor existente. El orden de las propiedades no está garantizado.

La función union combina no solo los elementos de nivel superior, sino que también combina recursivamente las matrices y objetos anidados dentro de ellos. Consulte el segundo ejemplo de la sección siguiente.

Ejemplo

En el ejemplo siguiente se muestra cómo utilizar la unión con matrices y 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'))]"
    }
  }
}

La salida del ejemplo anterior con el valor predeterminado es:

Nombre Tipo Value
objectOutput Object {"one": "a", "two": "b", "three": "c2", "four": "d", "five": "e"}
arrayOutput Array ["one", "two", "three", "four"]

En el ejemplo siguiente se muestra la funcionalidad de combinación 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'))]"
    }
  }
}

El resultado del ejemplo anterior es:

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

Si se combinaron matrices anidadas, el valor de objectOutput.nestedArray sería [1, 2, 3, 4], y el valor de arrayOutput sería [["one", "two", "three"], ["three", "four", "two"]].

Pasos siguientes