Parametri in Bicep

  • Articolo

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.

Sono limitati a 256 parametri in un file Bicep. Per ulteriori informazioni, vedere Limiti dei modelli.

Per le procedure consigliate per i parametri, vedere Parametri.

Risorse di formazione

Se si preferisce ottenere informazioni sui parametri tramite istruzioni dettagliate, vedere Creare modelli Bicep riutilizzabili usando i 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 param parola chiave 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 type 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 nessuna delle funzioni di elenco 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

Elementi Decorator

I parametri usano elementi 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.

Decoratore Applica a Argomento Descrizione
Consentito tutto array Valori consentiti per il parametro . Usare questo elemento decorator per assicurarsi che l'utente fornisca valori corretti.
description tutto string Testo che spiega come usare il parametro . La descrizione viene visualizzata agli utenti tramite il portale.
Maxlength matrice, stringa int Lunghezza massima per i parametri stringa e matrice. Il valore è inclusivo.
maxValue int int Valore massimo per il parametro integer. Questo valore è inclusivo.
metadata tutto oggetto Proprietà personalizzate da applicare al parametro. Può includere una proprietà description equivalente all'elemento decorator della descrizione.
Minlength matrice, stringa int Lunghezza minima per i parametri stringa e matrice. Il valore è inclusivo.
minValue int int Valore minimo per il parametro integer. 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.

Gli elementi Decorator si trovano nello spazio dei nomi sys. Se è necessario distinguere un elemento 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 l'elemento decorator di 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.

Proteggere i parametri

È 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 una matrice. La distribuzione non riesce durante la convalida se viene passato un valore per il parametro che non è uno dei valori consentiti.

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

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

Vincoli di lunghezza

È possibile specificare lunghezze minime e massime per i parametri stringa e matrice. È 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 nella matrice.

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 è una matrice che deve avere da 1 a 5 elementi.

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

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

Vincoli Integer

È possibile impostare valori minimi e massimi per i parametri integer. È 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:

Usare il testo in formato Markdown in VSCode

Assicurarsi che il testo segua la formattazione Markdown corretta; in caso contrario, potrebbe non essere visualizzato correttamente durante il rendering

Metadati UFX

Se si dispone di proprietà personalizzate da applicare a un parametro, aggiungere un elemento 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 elemento 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 @metadata() elemento Decorator con una proprietà in conflitto con un altro elemento Decorator, tale decorator ha sempre la precedenza su qualsiasi elemento nell'elemento @metadata() Decorator. La proprietà in conflitto all'interno del @metadata() valore è quindi 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@2020-06-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