Condividi tramite

Creare un file di parametri per la distribuzione Bicep

  • Articolo

Questo articolo illustra come creare un file di parametri, che è possibile usare invece di passare parametri come valori inline nello script. È possibile usare un file di parametri Bicep con l'estensione .bicepparam di file o un file di parametri JSON che contiene il valore del parametro.

Nota

I file di parametri Bicep sono supportati solo nell'interfaccia della riga di comando di Bicep versione 0.18.4 o successiva, nell'interfaccia della riga di comando di Azure versione 2.47.0 o successiva e in Azure PowerShell versione 9.7.1 o successiva.

A un singolo file Bicep possono essere associati più file di parametri Bicep. Tuttavia, ogni file di parametri Bicep è destinato a un particolare file Bicep. È possibile stabilire questa relazione applicando l'istruzione using all'interno del file di parametri Bicep.

È possibile compilare file di parametri Bicep in file di parametri JSON che è possibile distribuire usando un file Bicep. Per ulteriori informazioni, vedere build-params. È anche possibile decompilare un file di parametri JSON in un file di parametri Bicep. Per ulteriori informazioni, vedere decompile-params.

File dei parametri

Un file di parametri usa il formato seguente:

using '<path>/<file-name>.bicep'

param <first-parameter-name> = <first-value>
param <second-parameter-name> = <second-value>

È possibile applicare l'istruzione using usando un file Bicep, i modelli di Azure Resource Manager JSON, i moduli Bicep e le specifiche dei modelli. Ad esempio:

using './main.bicep'
...

using './azuredeploy.json'
...

using 'br/public:avm/res/storage/storage-account:0.9.0' 
...

using 'br:myacr.azurecr.io/bicep/modules/storage:v1'
...

using 'ts:00000000-0000-0000-0000-000000000000/myResourceGroup/storageSpec:1.0'
...

Per altre informazioni, vedere Istruzione Using.

È possibile usare espressioni con il valore predefinito. Ad esempio:

using 'main.bicep'

param storageName = toLower('MyStorageAccount')
param intValue = 2 + 2

È possibile fare riferimento alle variabili di ambiente come valori dei parametri. Ad esempio:

using './main.bicep'

param intFromEnvironmentVariables = int(readEnvironmentVariable('intEnvVariableName'))

È possibile definire e usare le variabili. È necessario usare l'interfaccia della riga di comando di Bicep versione 0.21.X o successiva per usare le variabili nei .bicepparam file. Vedere gli esempi seguenti:

using './main.bicep'

var storagePrefix = 'myStorage'
param primaryStorageName = '${storagePrefix}Primary'
param secondaryStorageName = '${storagePrefix}Secondary'

using './main.bicep'

var testSettings = {
  instanceSize: 'Small'
  instanceCount: 1
}

var prodSettings = {
  instanceSize: 'Large'
  instanceCount: 4
}

param environmentSettings = {
  test: testSettings
  prod: prodSettings
}

Nota

Un file di parametri salva i valori dei parametri come testo normale. Per motivi di sicurezza, non è consigliabile usare questo approccio con valori sensibili, ad esempio password.

Se è necessario passare un parametro con un valore sensibile, è necessario mantenere il valore in un insieme di credenziali delle chiavi. Anziché aggiungere un valore sensibile al file dei parametri, usare la getSecret funzione per recuperarla. Per altre informazioni, vedere Usare Azure Key Vault per passare un segreto come parametro durante la distribuzione di Bicep.

Formati dei tipi di parametro

Nell'esempio seguente vengono illustrati i formati di vari tipi di parametro: string, integer, Boolean, array e object.

using './main.bicep'

param exampleString = 'test string'
param exampleInt = 2 + 2
param exampleBool = true
param exampleArray = [
  'value 1'
  'value 2'
]
param exampleObject = {
  property1: 'value 1'
  property2: 'value 2'
}

Usare la sintassi Bicep per dichiarare oggetti e matrici.

File name

L'estensione di file per un file di parametri Bicep è .bicepparam.

Per eseguire la distribuzione in più ambienti, creare più file di parametri. Quando si usano più file di parametri, etichettarli in base al loro uso. Ad esempio, per distribuire le risorse, usare l'etichetta main.dev.bicepparam per lo sviluppo e l'etichetta main.prod.bicepparam per la produzione.

Definire i valori dei parametri

Per determinare come definire i nomi e i valori dei parametri, aprire il file Bicep. Esaminare la sezione dei parametri del file Bicep. Gli esempi seguenti illustrano i parametri di un file Bicep denominato main.bicep:

@maxLength(11)
param storagePrefix string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
param storageAccountType string = 'Standard_LRS'

Nel file dei parametri cercare il nome di ogni parametro. I nomi dei parametri nel file di parametri devono corrispondere ai nomi dei parametri nel file Bicep.

using 'main.bicep'

param storagePrefix
param storageAccountType

L'istruzione using collega il file dei parametri Bicep a un file Bicep. Per altre informazioni, vedere Istruzione Using.

Quando si digita la parola chiave param in Visual Studio Code, vengono richiesti i parametri disponibili e le relative descrizioni dal file Bicep collegato.

Screenshot della richiesta dei parametri disponibili.

Quando si passa il puntatore del mouse su un param nome, è possibile visualizzare il tipo di dati e la descrizione del parametro.

Screenshot del tipo di dati e della descrizione del parametro.

Esaminare il tipo di parametro, perché i tipi di parametro nel file dei parametri devono usare gli stessi tipi del file Bicep. In questo esempio entrambi i tipi di parametro sono stringhe:

using 'main.bicep'

param storagePrefix = ''
param storageAccountType = ''

Controllare il file Bicep per i parametri che includono un valore predefinito. Se un parametro ha un valore predefinito, è possibile specificare un valore nel file dei parametri, ma non è obbligatorio. Il valore del file dei parametri sostituisce il valore predefinito del file Bicep.

using 'main.bicep'

param storagePrefix = '' // This value must be provided.
param storageAccountType = '' // This value is optional. Bicep uses default value if not provided.

Per verificare se sono presenti restrizioni come la lunghezza massima, controllare i valori consentiti del file Bicep. I valori consentiti specificano l'intervallo di valori che è possibile specificare per un parametro. In questo esempio può storagePrefix avere un massimo di 11 caratteri e storageAccountType deve specificare un valore consentito.

using 'main.bicep'

param storagePrefix = 'storage'
param storageAccountType = 'Standard_ZRS'

Generare un file di parametri

È possibile creare un file di parametri usando Visual Studio Code o l'interfaccia della riga di comando di Bicep. Entrambi gli strumenti consentono di usare un file Bicep per generare un file di parametri. Vedere Generare il file dei parametri per il metodo di Visual Studio Code e Generare il file dei parametri per il metodo dell'interfaccia della riga di comando di Bicep.

Creare un file di parametri Bicep

Dall'interfaccia della riga di comando di Bicep è possibile compilare un file di parametri Bicep in un file di parametri JSON. Per altre informazioni, vedere File dei parametri di compilazione.

Distribuire il file Bicep con il file dei parametri

Interfaccia della riga di comando di Azure

Dall'interfaccia della riga di comando di Azure è possibile passare un file di parametri con la distribuzione di file Bicep.

È possibile distribuire un file Bicep usando un file di parametri Bicep con l'interfaccia della riga di comando di Azure versione 2.53.0 o successiva e l'interfaccia della riga di comando bicep versione 0.22.X o successiva. Con l'istruzione using all'interno del file di parametri Bicep, non è necessario fornire l'opzione --template-file quando si specifica un file di parametri Bicep per l'opzione --parameters .

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --parameters storage.bicepparam

È possibile usare parametri inline e un file di parametri di posizione nella stessa operazione di distribuzione. Ad esempio:

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --parameters storage.bicepparam \
  --parameters storageAccountType=Standard_LRS

Per altre informazioni, vedere Distribuire file Bicep usando l'interfaccia della riga di comando di Azure.

Azure PowerShell

Da Azure PowerShell passare un file di parametri locale usando il TemplateParameterFile parametro .

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

È possibile usare parametri inline e un file di parametri di posizione nella stessa operazione di distribuzione. Ad esempio:

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile C:\MyTemplates\storage.bicep `
  -TemplateParameterFile C:\MyTemplates\storage.bicepparam `
  -storageAccountType Standard_LRS

Per altre informazioni, vedere Distribuire file Bicep con Azure PowerShell. Per distribuire .bicep i file, è necessario Azure PowerShell versione 5.6.0 o successiva.

Precedenza dei parametri

È possibile usare i parametri inline e un file di parametri locale nella stessa operazione di distribuzione. Ad esempio, è possibile specificare alcuni valori nel file di parametri locale e aggiungere altri valori inline durante la distribuzione. Se si specificano valori per un parametro sia nel file dei parametri locale che inline, il valore inline ha la precedenza.

Anche se i file di parametri Bicep esterni non sono attualmente supportati, è possibile usare un file di parametri JSON esterno fornendo l'URI al file. Quando si usa un file di parametri esterni, specificare tutti i valori dei parametri nel file esterno. Quando si usa un file esterno, non è possibile passare altri valori inline o da un file locale e tutti i parametri inline vengono ignorati.

Conflitti nei nomi di parametro

Se il file Bicep include un parametro con lo stesso nome di uno dei parametri nel comando di Azure PowerShell, Azure PowerShell presenta il parametro dal file Bicep con il FromTemplate prefisso . Ad esempio, se un parametro denominato ResourceGroupName nel file Bicep è in conflitto con il ResourceGroupName parametro nel New-AzResourceGroupDeployment cmdlet , viene richiesto di specificare un valore per ResourceGroupNameFromTemplate. È possibile evitare questa confusione usando nomi di parametro non utilizzati per i comandi di distribuzione.

Contenuto correlato