Condividi tramite

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 con 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 un file Bicep, modelli JSON di Azure Resource Manager, 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 nei file con estensione 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 un 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 denominano più file di parametri, etichettarne l'uso come sviluppo e produzione. Ad esempio, usare main.dev.bicepparam per lo sviluppo e main.prod.bicepparam per la produzione 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 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 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 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 will use default value if not provided.

Controllare i valori consentiti del file Bicep e le eventuali restrizioni, ad esempio la lunghezza massima. Questi valori 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 in due modi: con VS 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 VS 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 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 con estensione 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.

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 perché 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 PowerShell, PowerShell presenta il parametro del file Bicep con il FromTemplate prefisso . 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