Parámetros en plantillas de ARM

  • Artículo

En este artículo se describe cómo definir y usar parámetros en una plantilla de Azure Resource Manager (plantilla de ARM). Si proporciona valores diferentes para los parámetros, podrá volver a usar una plantilla para distintos entornos.

Resource Manager resuelve los valores de parámetro antes de iniciar las operaciones de implementación. Siempre que el parámetro se use en la plantilla, Resource Manager lo reemplaza por el valor resuelto.

Cada parámetro debe establecerse en uno de los tipos de datos.

Además de minValue, maxValue, minLength, maxLength y allowedValues, languageVersion 2.0 presenta algunas restricciones de validación de tipos agregados que se usarán en definiciones, parámetros y definiciones de salidas. Estas restricciones incluyen:

Nota

La versión actual de la extensión Herramientas de Azure Resource Manager para Visual Studio Code no reconoce las mejoras realizadas en languageVersion 2.0.

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 obtener más información, consulte parámetros.

Está limitado a 256 parámetros en una plantilla. Para obtener más información, consulte Límites de plantilla.

Para conocer los procedimientos recomendados de parámetros, consulte Parámetros.

Declaración mínima

Como mínimo, cada parámetro necesita un nombre y un tipo.

Al implementar una plantilla mediante Azure Portal, los nombres de parámetro con mayúsculas y minúsculas Camel se convierten en nombres separados por espacios. Por ejemplo, demoString en el ejemplo siguiente se muestra como cadena de demostración. Para más información, consulte Usar un botón de implementación para implementar plantillas desde el repositorio de GitHub e Implementación de recursos con plantillas de ARM y Azure Portal.

"parameters": {
  "demoString": {
    "type": "string"
  },
  "demoInt": {
    "type": "int"
  },
  "demoBool": {
    "type": "bool"
  },
  "demoObject": {
    "type": "object"
  },
  "demoArray": {
    "type": "array"
  }
}

Parámetros seguros

Puede marcar los parámetros de objeto o cadena como seguros. El valor de un parámetro seguro no se guarda en el historial de implementaciones y no se registra.

"parameters": {
  "demoPassword": {
    "type": "secureString"
  },
  "demoSecretObject": {
    "type": "secureObject"
  }
}

Valores permitidos

Puede definir valores permitidos para un parámetro. Los valores permitidos se proporcionan en una matriz. Se produce un error en la implementación durante la validación si se pasa un valor para el parámetro que no es uno de los valores permitidos.

"parameters": {
  "demoEnum": {
    "type": "string",
    "allowedValues": [
      "one",
      "two"
    ]
  }
}

Valor predeterminado

Puede especificar un valor predeterminado para un parámetro. El valor predeterminado se usa cuando no se proporciona un valor durante la implementación.

"parameters": {
  "demoParam": {
    "type": "string",
    "defaultValue": "Contoso"
  }
}

Para especificar un valor predeterminado junto con otras propiedades para el parámetro, use la sintaxis siguiente.

"parameters": {
  "demoParam": {
    "type": "string",
    "defaultValue": "Contoso",
    "allowedValues": [
      "Contoso",
      "Fabrikam"
    ]
  }
}

Puede usar expresiones con el valor predeterminado. La función no puede usar la función reference ni ninguna de las funciones list de la sección de parámetros. Estas funciones obtienen el estado de tiempo de ejecución de un recurso y no se pueden ejecutar antes de la implementación cuando se resuelven parámetros.

No se permiten expresiones con otras propiedades de parámetro.

"parameters": {
  "location": {
    "type": "string",
    "defaultValue": "[resourceGroup().location]"
  }
}

Puede usar otro valor de parámetro para compilar un valor predeterminado. La plantilla siguiente crea un nombre de plan de host a partir del nombre del sitio.

"parameters": {
  "siteName": {
    "type": "string",
    "defaultValue": "[concat('site', uniqueString(resourceGroup().id))]"
  },
  "hostingPlanName": {
    "type": "string",
    "defaultValue": "[concat(parameters('siteName'),'-plan')]"
  }
}

Restricciones de longitud

Puede especificar la longitud mínima y máxima de los parámetros de matriz y de cadena. Puede establecer una o las dos restricciones. Para las cadenas, la longitud indica el número de caracteres. Para las matrices, la longitud indica el número de elementos de la matriz.

En el ejemplo siguiente se declaran dos parámetros. Un parámetro es para un nombre de cuenta de almacenamiento que debe tener entre 3 y 24 caracteres. El otro parámetro es una matriz que debe tener entre 1 y 5 elementos.

"parameters": {
  "storageAccountName": {
    "type": "string",
    "minLength": 3,
    "maxLength": 24
  },
  "appNames": {
    "type": "array",
    "minLength": 1,
    "maxLength": 5
  }
}

Restricciones de enteros

Puede establecer valores mínimos y máximos para los parámetros de entero. Puede establecer una o las dos restricciones.

"parameters": {
  "month": {
    "type": "int",
    "minValue": 1,
    "maxValue": 12
  }
}

Restricciones de objeto

Las restricciones de objeto solo se permiten en objetos y solo se pueden usar con languageVersion 2.0.

Propiedades

El valor de properties es un mapa de nombre de propiedad =>definición de tipo.

En el ejemplo siguiente se aceptaría {"foo": "string", "bar": 1}, pero rechazaría {"foo": "string", "bar": -1}, {"foo": "", "bar": 1} o cualquier objeto sin una propiedad foo o bar.

"parameters": {
  "objectParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3
      },
      "bar": {
        "type": "int",
        "minValue": 0
      }
    }
  }
}

Todas las propiedades son necesarias a menos que la definición de tipo de la propiedad tenga la restricción "nullable": true. Para hacer que ambas propiedades del ejemplo anterior sean opcionales, quedaría así:

"parameters": {
  "objectParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3,
        "nullable": true
      },
      "bar": {
        "type": "int",
        "minValue": 0,
        "nullable": true
      }
    }
  }
}

additionalProperties

El valor de additionalProperties es una definición de tipo o un valor booleano. Si no se define ninguna restricción additionalProperties, el valor predeterminado es true.

Si value es una definición de tipo, el valor describe el esquema que se aplica a todas las propiedades que no se mencionan en la restricción properties. En el ejemplo siguiente se aceptaría {"fizz": "buzz", "foo": "bar"} pero se rechazaría {"property": 1}.

"parameters": {
  "dictionaryParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3,
        "nullable": true
      },
      "bar": {
        "type": "int",
        "minValue": 0,
        "nullable": true
      }
    },
    "additionalProperties": {
      "type": "string"
    }
  }
}

Si el valor es false, no se pueden proporcionar propiedades más allá de las definidas en la restricción properties. En el ejemplo siguiente se aceptaría {"foo": "string", "bar": 1} pero se rechazaría {"foo": "string", "bar": 1, "fizz": "buzz"}.

"parameters": {
  "dictionaryParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3
      },
      "bar": {
        "type": "int",
        "minValue": 0
      }
    },
    "additionalProperties": false
  }
}

Si el valor es true, cualquier propiedad no definida en la restricción properties no acepta ningún valor. En el ejemplo siguiente se aceptaría {"foo": "string", "bar": 1, "fizz": "buzz"}.

"parameters": {
  "dictionaryParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3
      },
      "bar": {
        "type": "int",
        "minValue": 0
      }
    },
    "additionalProperties": true
  }
}

discriminator

El valor discriminator define qué esquema se va a aplicar en función de una propiedad Discriminator. En el ejemplo siguiente se aceptaría {"type": "ints", "foo": 1, "bar": 2} o {"type": "strings", "fizz": "buzz", "pop": "goes", "the": "weasel"}, pero se rechazaría {"type": "ints", "fizz": "buzz"}.

"parameters": {
  "taggedUnionParameter": {
    "type": "object",
    "discriminator": {
      "propertyName": "type",
      "mapping": {
        "ints": {
          "type": "object",
          "additionalProperties": {"type": "int"}
        },
        "strings": {
          "type": "object",
          "additionalProperties": {"type": "string"}
          }
      }
    }
  }
}

Restricciones de matriz

Las restricciones de matriz solo se permiten en matrices y solo se pueden usar con languageVersion 2.0.

prefixItems

El valor de prefixItems es una matriz de definiciones de tipo. Cada definición de tipo del valor es el esquema que se va a usar para validar el elemento de una matriz en el mismo índice. En el ejemplo siguiente se aceptaría [1, true] pero se rechazaría [1, "string"] o [1]:

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  }
}

items

El valor de items es una definición de tipo o un booleano. Si no se define ninguna restricción items, el valor predeterminado es true.

Si value es una definición de tipo, el valor describe el esquema que se aplica a todos los elementos de la matriz cuyo índice es mayor que el índice más grande de la restricción prefixItems. En el ejemplo siguiente se aceptaría [1, true, 1] o [1, true, 1, 1] pero se rechazaría [1, true, "foo"]:

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      { "type": "int" },
      { "type": "bool" }
    ],
    "items": { "type": "int" },
    "defaultValue": [1, true, "foo"]
  }
}

Puede usar items sin usar prefixItems. En el ejemplo siguiente se aceptaría [1, 2] o [1] pero se rechazaría ["foo"]:

"parameters": {
  "intArrayParameter": {
    "type": "array",
    "items": {"type": "int"}
  }
}

Si el valor es false, la matriz validada debe tener exactamente la misma longitud que la restricción prefixItems. En el ejemplo siguiente se aceptaría [1, true] pero se rechazaría [1, true, 1] y [1, true, false, "foo", "bar"].

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ],
    "items": false
  }
}

Si el valor es true, los elementos de la matriz cuyo índice es mayor que el índice más grande de la restricción prefixItems aceptan cualquier valor. Los ejemplos siguientes aceptarían [1, true], [1, true, 1] y [1, true, false, "foo", "bar"].

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  }
}

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  },
  "items": true
}

restricción que admite un valor NULL

La restricción que admite un valor NULL solo se puede usar con languageVersion 2.0. Indica que el valor puede ser null u omitirse. Vea Propiedades para obtener un ejemplo.

Descripción

Puede agregar una descripción a un parámetro para ayudar a los usuarios de la plantilla a comprender el valor que deben proporcionar. Al implementar la plantilla a través del portal, el texto que proporciona en la descripción se usa automáticamente como sugerencia para ese parámetro. Agregue solo una descripción cuando el texto proporcione más información de la que se puede deducir del nombre del parámetro.

"parameters": {
  "virtualMachineSize": {
    "type": "string",
    "metadata": {
      "description": "Must be at least Standard_A3 to support 2 NICs."
    },
    "defaultValue": "Standard_DS1_v2"
  }
}

Uso del parámetro

Para hacer referencia al valor de un parámetro, use la función parameters. En el ejemplo siguiente se usa un valor de parámetro para un nombre de almacén de claves.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "vaultName": {
      "type": "string",
      "defaultValue": "[format('keyVault{0}', uniqueString(resourceGroup().id))]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.KeyVault/vaults",
      "apiVersion": "2021-06-01-preview",
      "name": "[parameters('vaultName')]",
      ...
    }
  ]
}

Objetos como parámetros

Para organizar los valores relacionados, páselos en un objeto. Con este enfoque también se reduce el número de parámetros de la plantilla.

En el ejemplo siguiente se muestra un parámetro que es un objeto. El valor predeterminado muestra las propiedades esperadas para el objeto. Esas propiedades se usan al definir el recurso que se va a implementar.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "vNetSettings": {
      "type": "object",
      "defaultValue": {
        "name": "VNet1",
        "location": "eastus",
        "addressPrefixes": [
          {
            "name": "firstPrefix",
            "addressPrefix": "10.0.0.0/22"
          }
        ],
        "subnets": [
          {
            "name": "firstSubnet",
            "addressPrefix": "10.0.0.0/24"
          },
          {
            "name": "secondSubnet",
            "addressPrefix": "10.0.1.0/24"
          }
        ]
      }
    }
  },
  "resources": [
    {
      "type": "Microsoft.Network/virtualNetworks",
      "apiVersion": "2021-02-01",
      "name": "[parameters('vNetSettings').name]",
      "location": "[parameters('vNetSettings').location]",
      "properties": {
        "addressSpace": {
          "addressPrefixes": [
            "[parameters('vNetSettings').addressPrefixes[0].addressPrefix]"
          ]
        },
        "subnets": [
          {
            "name": "[parameters('vNetSettings').subnets[0].name]",
            "properties": {
              "addressPrefix": "[parameters('vNetSettings').subnets[0].addressPrefix]"
            }
          },
          {
            "name": "[parameters('vNetSettings').subnets[1].name]",
            "properties": {
              "addressPrefix": "[parameters('vNetSettings').subnets[1].addressPrefix]"
            }
          }
        ]
      }
    }
  ]
}

Plantillas de ejemplo

En los siguientes ejemplos se muestran escenarios para usar parámetros.

Plantilla Descripción
parámetros con funciones para los valores predeterminados Muestra cómo utilizar las funciones de plantilla al definir valores predeterminados para parámetros. La plantilla no implementa ningún recurso. Genera valores de parámetro y devuelve dichos valores.
objeto de parámetro Muestra cómo utilizar un objeto para un parámetro. La plantilla no implementa ningún recurso. Genera valores de parámetro y devuelve dichos valores.

Pasos siguientes