Creación de un archivo de parámetros de Resource Manager

  • Artículo

En lugar de pasar parámetros como valores en línea en el script, puede usar un archivo JSON que contenga los valores de parámetro. En este artículo se muestra cómo crear un archivo de parámetros que se usa con una plantilla JSON.

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 archivos de parámetros.

Archivo de parámetros

Un archivo de parámetros usa el siguiente formato:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "<first-parameter-name>": {
      "value": "<first-value>"
    },
    "<second-parameter-name>": {
      "value": "<second-value>"
    }
  }
}

Vale la pena tener en cuenta que el archivo de parámetros guarda los valores del parámetro como texto sin formato. Por motivos de seguridad, este enfoque no se recomienda para valores confidenciales, como contraseñas. Si necesita pasar un parámetro con un valor confidencial, conserve el valor en un almacén de claves. A continuación, en el archivo de parámetros, incluya una referencia al almacén de claves. Durante la implementación, el valor confidencial se recupera de forma segura. Para más información, consulte Uso de Azure Key Vault para pasar el valor de parámetro seguro durante la implementación.

El archivo de parámetros siguiente incluye un valor de texto sin formato y un valor confidencial que está almacenado en un almacén de claves.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "<first-parameter-name>": {
      "value": "<first-value>"
    },
    "<second-parameter-name>": {
      "reference": {
        "keyVault": {
          "id": "<resource-id-key-vault>"
        },
        "secretName": "<secret-name>"
      }
    }
  }
}

Para más información sobre el uso de valores de una instancia de Key Vault, consulte Uso de Azure Key Vault para pasar el valor de parámetro seguro durante la implementación.

Definición de los valores de parámetro

Para determinar cómo definir los nombres y valores de los parámetros, abra la plantilla JSON y revise la sección parameters. En el ejemplo siguiente se muestran los parámetros de la plantilla JSON.

"parameters": {
  "storagePrefix": {
    "type": "string",
    "maxLength": 11
  },
  "storageAccountType": {
    "type": "string",
    "defaultValue": "Standard_LRS",
    "allowedValues": [
    "Standard_LRS",
    "Standard_GRS",
    "Standard_ZRS",
    "Premium_LRS"
    ]
  }
}

En el archivo de parámetros, el primer detalle que se debe tener en cuenta es el nombre de cada parámetro. Los nombres de los parámetros del archivo de parámetros deben coincidir con los nombres de los parámetros de la plantilla.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
    },
    "storageAccountType": {
    }
  }
}

Tenga en cuenta el tipo del parámetro. Los tipos de parámetros del archivo de parámetros deben usar los mismos tipos que la plantilla. En este ejemplo, ambos tipos de parámetros son cadenas.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
      "value": ""
    },
    "storageAccountType": {
      "value": ""
    }
  }
}

Compruebe en la plantilla los parámetros con un valor predeterminado. Si un parámetro tiene un valor predeterminado, puede proporcionar un valor en el archivo de parámetros, pero no es necesario. El valor del archivo de parámetros invalida el valor predeterminado de la plantilla.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
      "value": "" // This value must be provided.
    },
    "storageAccountType": {
      "value": "" // This value is optional. Template will use default value if not provided.
    }
  }
}

Compruebe los valores permitidos y las restricciones de la plantilla, como la longitud máxima. Esos valores especifican el intervalo de valores que puede proporcionar para un parámetro. En este ejemplo, storagePrefix puede tener un máximo de 11 caracteres y storageAccountType debe especificar un valor permitido.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
      "value": "storage"
    },
    "storageAccountType": {
      "value": "Standard_ZRS"
    }
  }
}

Nota:

El archivo de parámetros solo puede contener valores para los parámetros que se definan en la plantilla. Si el archivo de parámetros contiene parámetros adicionales que no coinciden con los de la plantilla, recibirá un error.

Formatos de tipo de parámetro

En el ejemplo siguiente se muestran los formatos de distintos tipos de parámetros: cadena, entero, booleano, matriz y objeto.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "exampleString": {
      "value": "test string"
    },
    "exampleInt": {
      "value": 4
    },
    "exampleBool": {
      "value": true
    },
    "exampleArray": {
      "value": [
        "value 1",
        "value 2"
      ]
    },
    "exampleObject": {
      "value": {
        "property1": "value1",
        "property2": "value2"
      }
    }
  }
}

Implementación de la plantilla con el archivo de parámetros

Desde la CLI de Azure se pasa un archivo de parámetros local mediante @ y el nombre del archivo de parámetros. Por ejemplo, @storage.parameters.json.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.json \
  --parameters @storage.parameters.json

Para más información, consulte Implementación de recursos con plantillas de ARM y la CLI de Azure.

Desde Azure PowerShell se pasa un archivo de parámetros local mediante el parámetro TemplateParameterFile.

New-AzResourceGroupDeployment -Name ExampleDeployment -ResourceGroupName ExampleResourceGroup `
  -TemplateFile C:\MyTemplates\storage.json `
  -TemplateParameterFile C:\MyTemplates\storage.parameters.json

Para más información, consulte Implementación de recursos con las plantillas de ARM y Azure PowerShell.

Nota:

No es posible usar un archivo de parámetros con la hoja de plantilla personalizada en el portal.

Sugerencia

Si usa el proyecto de grupo de recursos de Azure en Visual Studio, asegúrese de que el archivo de parámetros tiene su acción de compilación establecida en Contenido.

Nombre de archivo

La convención de nomenclatura general para el archivo de parámetros consiste en agregar parameters al nombre de la plantilla. Por ejemplo, si la plantilla se denomina azuredeploy.json, el archivo de parámetros se denomina azuredeploy.parameters.json. Esta convención de nomenclatura le ayuda a ver la conexión entre la plantilla y los parámetros.

Para realizar la implementación en entornos diferentes, cree más de un archivo de parámetros. Cuando asigne un nombre a los archivos de parámetros, identifique su uso, desarrollo y producción. Por ejemplo, use azuredeploy.parameters-dev.json y azuredeploy.parameters-prod.json para implementar recursos.

Prioridad de parámetros

Puede usar parámetros en línea y un archivo de parámetros local en la misma operación de implementación. Por ejemplo, puede especificar algunos valores en el archivo de parámetros local y agregar otros valores en línea durante la implementación. Si proporciona valores para un parámetro en el archivo de parámetros local y en línea, el valor en línea tiene prioridad.

Es posible usar un archivo de parámetros externo proporcionando el URI al archivo. Cuando se utiliza un archivo de parámetros externo, no se pueden pasar otros valores, tanto si se hace en línea como desde un archivo local. Se omiten todos los parámetros insertados. Proporcione todos los valores de parámetro en el archivo externo.

Conflictos de nombres de parámetro

Si la plantilla incluye un parámetro con el mismo nombre que uno de los parámetros del comando de PowerShell, PowerShell presenta el parámetro de la plantilla con el postfijo FromTemplate. Por ejemplo, un parámetro denominado ResourceGroupName en la plantilla entra en conflicto con el parámetro ResourceGroupName del cmdlet ResourceGroupName. Se le pedirá que proporcione un valor para ResourceGroupNameFromTemplate. Para evitar esta confusión, use nombres de parámetros que no se usan para los comandos de implementación.

Pasos siguientes