Creare file di parametri per la distribuzione Bicep

  • Articolo

Anziché passare parametri come valori inline nello script, è possibile usare un file di parametri Bicep con l'estensione di file .bicepparam o un file di parametri JSON che contiene i valori dei parametri. Questo articolo illustra come creare file di parametri.

Nota

Il file dei parametri Bicep è supportato 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. Questa relazione viene stabilita usando l'istruzione using all'interno del file di parametri Bicep.

È possibile compilare file di parametri Bicep in file di parametri JSON da distribuire con un file Bicep. Vedere build-params. È anche possibile decompilare un file di parametri JSON in un file di parametri Bicep. 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 usare l'istruzione using con file Bicep, modelli JSON ARM, moduli Bicep e specifiche di modello. 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 l'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. L'interfaccia della riga di comando bicep versione 0.21.X o successiva è necessaria per l'uso di variabili nel file bicepparam. Di seguito sono riportati alcuni esempi.

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
}

Vale la pena notare che il file dei parametri salva i valori dei parametri come testo normale. Per motivi di sicurezza, questo approccio non è consigliato per valori sensibili, ad esempio password. Se devi passare un parametro con un valore sensibile, mantieni il valore in un insieme di credenziali delle chiavi. Anziché aggiungere il valore sensibile al file dei parametri, usare la funzione getSecret per recuperarla. Per altre informazioni, vedere Usare Azure Key Vault per passare valori di parametro protetti durante la distribuzione di Bicep.

Formati dei tipi di parametro

Nell'esempio seguente vengono illustrati i formati di tipi di parametro diversi: stringa, integer, booleano, matrice e oggetto.

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

Il file dei parametri Bicep ha l'estensione di file di .bicepparam.

Per la distribuzione in ambienti diversi, si possono creare più di un file di parametri. Quando si assegna un nome ai file di parametri, identificarne l'uso, come sviluppo e produzione. Ad esempio, usare main.dev.bicepparam e main.prod.bicepparam per distribuire le risorse.

Definire i valori dei parametri

Per determinare come definire i nomi e i valori dei parametri, aprire il file Bicep. Esaminare la sezione del file Bicep relativa ai parametri. Negli esempi seguenti vengono illustrati 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 di parametri, il primo dettaglio da notare è 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 utilizzo dell’istruzione.

Dopo aver digitato 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 nome parametro, è possibile visualizzare il tipo di dati e la descrizione del parametro.

Screenshot del tipo di dati e della descrizione del parametro.

Si noti il tipo di parametro. I tipi di parametro nel file di 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 con un valore predefinito. Se un parametro ha un valore predefinito, è possibile specificare un valore nel file di 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 will use default value if not provided.

Controllare i valori consentiti del file Bicep ed eventuali restrizioni, ad esempio la lunghezza massima. Questi valori specificano l'intervallo di valori che è possibile specificare per un parametro. In questo esempio, storagePrefix può 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

Per generare un file di parametri, sono disponibili due opzioni: tramite Visual Studio Code o usando l'interfaccia della riga di comando di Bicep. Entrambi i metodi consentono di derivare il file dei parametri da un file Bicep. Da Visual Studio Code, vedere Generare il file dei parametri. Dall'interfaccia della riga di comando di Bicep, vedere Generare il file dei parametri.

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.

Con l'interfaccia della riga di comando di Azure versione 2.53.0 o successiva e l'interfaccia della riga di comando di Bicep versione 0.22.X o successiva, è possibile distribuire un file Bicep usando un file di parametri Bicep. 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 risorse con Bicep e l'interfaccia della riga di comando di Azure.

Azure PowerShell

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

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 ulteriori informazioni, vedere Distribuire le risorse con Bicep e Azure PowerShell. Per distribuire i file .bicep, è 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.

È possibile usare un file di parametri JSON esterno, fornendo l'URI al file. Il file dei parametri Bicep esterno non è attualmente supportato. Tuttavia, quando si usa un file di parametri esterni, non è possibile trasmettere altri valori, né inline né da un file locale. Tutti i parametri inline vengono ignorati. È necessario fornire tutti i valori dei parametri presenti nel file esterno.

Conflitti nei nomi di parametro

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

Passaggi successivi