Parametri in Bicep

Questo articolo descrive come definire e usare i parametri in un file Bicep. Fornendo valori diversi per i parametri, è possibile riutilizzare un file Bicep per ambienti diversi.

Resource Manager risolve i valori dei parametri prima di avviare le operazioni di distribuzione. Ovunque venga usato il parametro, Resource Manager lo sostituisce con il valore risolto.

Ogni parametro deve essere impostato su uno dei tipi di dati.

Bicep consente un massimo di 256 parametri. Per altre informazioni, vedere Limiti dei modelli.

Per le procedure consigliate per i parametri, vedere Parametri.

Risorse di formazione

Se si preferisce ottenere informazioni sui parametri per mezzo di materiale sussidiario passo-passo, vedere Creare modelli Bicep flessibili per mezzo di parametri.

Dichiarazione

Ogni parametro ha un nome e un tipo di dati. Facoltativamente, è possibile specificare un valore predefinito per il parametro.

param <parameter-name> <parameter-data-type> = <default-value>

Un parametro non può avere lo stesso nome di una variabile, una risorsa, un output o un altro parametro nello stesso ambito.

Nell'esempio seguente vengono illustrate le dichiarazioni di base dei parametri.

param demoString string
param demoInt int
param demoBool bool
param demoObject object
param demoArray array

La parola chiave param viene usata anche nei file con estensione bicepparam. Nei file con estensione bicepparam non è necessario specificare il tipo di dati come definito nei file Bicep.

param <parameter-name> = <value>

Per altre informazioni, vedere File di parametri.

Le espressioni di tipo definite dall'utente possono essere usate come clausola tipo di un'istruzione param. Ad esempio:

param storageAccountConfig {
  name: string
  sku: string
}

Per altre informazioni, vedere Tipi di dati definiti dall'utente.

Valore predefinito

È possibile specificare un valore predefinito per un parametro. Il valore predefinito viene usato quando non viene specificato un valore durante la distribuzione.

param demoParam string = 'Contoso'

È possibile usare espressioni con il valore predefinito. Le espressioni non sono consentite con altre proprietà dei parametri. Non è possibile usare la funzione di riferimento o una qualsiasi delle funzioni elenco presenti nella sezione Parametri. Queste funzioni ottengono lo stato di runtime della risorsa e non possono essere eseguite prima della distribuzione quando i parametri vengono risolti.

param location string = resourceGroup().location

Si può usare il valore di un altro parametro per generare un valore predefinito. Il modello seguente costruisce un nome di piano host dal nome del sito.

param siteName string = 'site${uniqueString(resourceGroup().id)}'
param hostingPlanName string = '${siteName}-plan'

output siteNameOutput string = siteName
output hostingPlanOutput string = hostingPlanName

Tuttavia, non è possibile fare riferimento a una variabile come valore predefinito.

Elementi Decorator

I parametri usano decorator per vincoli o metadati. I decorator sono nel formato @expression e vengono posizionati sopra la dichiarazione del parametro. È possibile contrassegnare un parametro come sicuro, specificare i valori consentiti, impostare la lunghezza minima e massima per una stringa, impostare il valore minimo e massimo per un numero intero e fornire una descrizione del parametro.

Nell'esempio seguente vengono illustrati due usi comuni per gli elementi decorator.

@secure()
param demoPassword string

@description('Must be at least Standard_A3 to support 2 NICs.')
param virtualMachineSize string = 'Standard_DS1_v2'

La tabella seguente descrive i decorator disponibili e come usarli.

Decorator	Applica a	Argomento	Descrizione
consentito	tutto	array	Usare questo elemento decorator per assicurarsi che l'utente fornisca valori corretti. L’espressione Decorator è consentita solo per le istruzioni param. Per dichiarare che una proprietà deve essere uno dei set di valori predefiniti in un'istruzione type o output, usare la sintassi dei tipi di unione. La sintassi dei tipi di unione può essere usata anche nelle istruzioni param.
description	tutto	string	Testo che spiega come usare il parametro. La descrizione viene visualizzata agli utenti tramite il portale.
maxLength	array, stringa	int	Lunghezza massima per i parametri stringa e array. Il valore è inclusivo.
maxValue	int	int	Valore massimo per il parametro numero intero. Questo valore è inclusivo.
metadata	tutto	oggetto	Proprietà personalizzate da applicare al parametro. Può includere una proprietà description equivalente all'elemento decorator della descrizione.
minLength	array, stringa	int	Lunghezza minima per i parametri stringa e array. Il valore è inclusivo.
minValue	int	int	Valore minimo per il parametro numero intero. Questo valore è inclusivo.
sicuro	stringa, oggetto	Nessuno	Contrassegna il parametro come sicuro. Il valore di un parametro sicuro non viene salvato nella cronologia di distribuzione e non viene registrato. Per altre informazioni, vedere Proteggere stringhe e oggetti.

I decorator si trovano nello spazio dei nomi sys. Se è necessario distinguere un decorator da un altro elemento con lo stesso nome, anteporre al decorator con sys. Ad esempio, se il file Bicep include un parametro denominato description, è necessario aggiungere lo spazio dei nomi sys quando si usa il decorator descrizione.

@sys.description('The name of the instance.')
param name string
@sys.description('The description of the instance to display.')
param description string

I decorator disponibili sono descritti nelle sezioni seguenti.

Parametri protetti

È possibile contrassegnare i parametri stringa o oggetto come sicuri. Il valore di un parametro sicuro non viene salvato nella cronologia di distribuzione e non viene registrato.

@secure()
param demoPassword string

@secure()
param demoSecretObject object

Valori consentiti

È possibile definire i valori consentiti per un parametro. È possibile specificare i valori consentiti in un array. La distribuzione non riesce durante la convalida se viene passato un valore per il parametro che non rientra tra i valori consentiti.

@allowed([
  'one'
  'two'
])
param demoEnum string

Se si definiscono valori consentiti per un parametro di array, il valore effettivo può essere qualsiasi subset dei valori consentiti.

Vincoli di lunghezza

È possibile specificare lunghezze minime e massime per le definizioni dei parametri stringa e array. È possibile impostare uno o entrambi i vincoli. Per le stringhe, la lunghezza indica il numero di caratteri. Per le matrici, la lunghezza indica il numero di elementi nell'array.

Nell'esempio seguente vengono dichiarati due parametri. Un parametro è per un nome di account di archiviazione che deve avere 3-24 caratteri. L'altro parametro è un array che deve avere da 1 a 5 elementi.

@minLength(3)
@maxLength(24)
param storageAccountName string

@minLength(1)
@maxLength(5)
param appNames array

Vincoli sui numeri interi

È possibile impostare valori minimi e massimi per i parametri sui numeri interi. È possibile impostare uno o entrambi i vincoli.

@minValue(1)
@maxValue(12)
param month int

Descrizione

Per aiutare gli utenti a comprendere il valore da fornire, aggiungere una descrizione al parametro. Quando un utente distribuisce il modello tramite il portale, il testo della descrizione viene usato automaticamente come suggerimento per tale parametro. Aggiungere una descrizione solo quando il testo fornisce più informazioni di quanto possa essere dedotto dal nome del parametro.

@description('Must be at least Standard_A3 to support 2 NICs.')
param virtualMachineSize string = 'Standard_DS1_v2'

Il testo formattato markdown può essere usato per il testo della descrizione:

@description('''
Storage account name restrictions:
- Storage account names must be between 3 and 24 characters in length and may contain numbers and lowercase letters only.
- Your storage account name must be unique within Azure. No two storage accounts can have the same name.
''')
@minLength(3)
@maxLength(24)
param storageAccountName string

Quando si passa il cursore su storageAccountName in VS Code, viene visualizzato il testo formattato:

Assicurarsi che il testo segua la formattazione Markdown corretta; altrimenti è possibile che non venga visualizzato correttamente durante il rendering.

Metadati UFX

Se si dispone di proprietà personalizzate da applicare a un parametro, aggiungere un decorator di metadati. All'interno dei metadati definire un oggetto con i nomi e i valori personalizzati. L'oggetto definito per i metadati può contenere proprietà di qualsiasi nome e tipo.

È possibile usare questo decorator per tenere traccia delle informazioni sul parametro che non ha senso aggiungere alla descrizione.

@description('Configuration values that are applied when the application starts.')
@metadata({
  source: 'database'
  contact: 'Web team'
})
param settings object

Quando si fornisce un decorator @metadata() con una proprietà in conflitto con un altro decorator, tale decorator ha sempre la precedenza su qualsiasi elemento nel decorator @metadata(). Pertanto, la proprietà in conflitto all'interno del valore @metadata() è ridondante e verrà sostituita. Per altre informazioni, vedere Nessun metadati in conflitto.

Usare il parametro

Per fare riferimento al valore di un parametro, usare il nome del parametro. Nell'esempio seguente viene usato un valore di parametro per un nome dell'insieme di credenziali delle chiavi.

param vaultName string = 'keyVault${uniqueString(resourceGroup().id)}'

resource keyvault 'Microsoft.KeyVault/vaults@2019-09-01' = {
  name: vaultName
  ...
}

Oggetti come parametri

Può essere più semplice organizzare i valori correlati passandoli come oggetto. Questo approccio riduce anche il numero di parametri nel modello.

Nell'esempio seguente viene illustrato un parametro che è un oggetto. Il valore predefinito mostra le proprietà previste per l'oggetto. Queste proprietà vengono usate quando si definisce la risorsa da distribuire.

param vNetSettings object = {
  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'
    }
  ]
}

resource vnet 'Microsoft.Network/virtualNetworks@2023-11-01' = {
  name: vNetSettings.name
  location: vNetSettings.location
  properties: {
    addressSpace: {
      addressPrefixes: [
        vNetSettings.addressPrefixes[0].addressPrefix
      ]
    }
    subnets: [
      {
        name: vNetSettings.subnets[0].name
        properties: {
          addressPrefix: vNetSettings.subnets[0].addressPrefix
        }
      }
      {
        name: vNetSettings.subnets[1].name
        properties: {
          addressPrefix: vNetSettings.subnets[1].addressPrefix
        }
      }
    ]
  }
}

Passaggi successivi

• Per informazioni sulle proprietà disponibili per i parametri, vedere Informazioni sulla struttura e la sintassi dei file Bicep.
• Per informazioni sul passaggio dei valori dei parametri come file, vedere Creare un file di parametri Bicep.
• Per informazioni sulla specificazione dei valori dei parametri come distribuzione, consultare Implementare con l’interfaccia della riga di comando di Azure e Implementare con Azure PowerShell.