Informazioni sui parametri

  • 8 minuti

I parametri consentono di fornire informazioni a un modello Bicep al momento della distribuzione. Dichiarando parametri all'interno di un modello Bicep, lo si rende flessibile e riutilizzabile.

Le espressioni Decorator consentono di associare vincoli e metadati a un parametro, in modo che chiunque usi il modello comprenda facilmente quali sono le informazioni da inserire.

In questa unità verranno illustrati i parametri e le espressioni Decorator.

Dichiarare un parametro

In un modello Bicep, per dichiarare un parametro si usa la parola chiave param. È possibile inserire queste dichiarazioni in qualunque punto del file modello, anche se in generale è consigliabile collocarle all'inizio, per rendere il codice Bicep facile da leggere.

Ecco come dichiarare un parametro:

param environmentName string

Ecco come funzionano i vari elementi:

  • param indica a Bicep che si sta dichiarando un parametro.

  • environmentName fa riferimento al nome del parametro. Anche se è possibile assegnare al parametro un nome qualsiasi, è necessario che sia chiaro e comprensibile per gli utenti del modello. All'interno dello stesso modello è anche possibile fare riferimento al parametro usando il suo nome. I nomi dei parametri devono essere univoci. Non possono avere lo stesso nome di una variabile o di una risorsa nello stesso file Bicep.

    Suggerimento

    Usare le convenzioni di denominazione consigliate per le dichiarazioni di parametro. Convenzioni di denominazione adeguate rendono i modelli facili da leggere e da capire. Assicurarsi di usare nomi chiari e descrittivi e di adottare una strategia di denominazione coerente.

  • string fa riferimento al tipo del parametro.

    Suggerimento

    Riflettere attentamente sui parametri utilizzati dal modello. Provare a usare parametri per le impostazioni che cambiano tra una distribuzione e l'altra. Per le impostazioni che non cambiano tra le distribuzioni si possono usare variabili e valori hardcoded.

Aggiungere un valore predefinito

È possibile assegnare valori predefiniti ai parametri nei modelli. Assegnando un valore predefinito, si rende il parametro facoltativo. Se il modello viene distribuito senza un valore specificato per il parametro, viene assegnato il valore predefinito.

Di seguito viene illustrato come aggiungere un valore predefinito:

param environmentName string = 'dev'

Al parametro environmentName viene assegnato il valore predefinito dev.

È possibile usare espressioni come valori predefiniti. Di seguito è riportato l'esempio di un parametro stringa denominato location con il valore predefinito impostato sulla posizione del gruppo di risorse corrente:

param location string = resourceGroup().location

Suggerimento

Prestare attenzione ai valori predefiniti che si usano. Verificare che sia possibile distribuire il file Bicep in tutta sicurezza con i valori predefiniti. Considerare ad esempio l'uso di piani tariffari e SKU convenienti, in modo che chi distribuisce il modello in un ambiente di test non debba sostenere costi inutilmente elevati.

Informazioni su tipi di parametro

Quando si dichiara un parametro, è necessario indicare a Bicep il tipo di informazioni che conterrà. Bicep verificherà che il valore assegnato al parametro sia compatibile con il tipo di parametro.

I parametri in Bicep possono essere dei tipi seguenti:

  • string, che consente di immettere testo arbitrario.
  • int, che consente di immettere un numero.
  • bool, che rappresenta un valore booleano (true o false).
  • object e array, che rappresentano elenchi e dati strutturati.

Oggetti

È possibile usare parametri di oggetto per combinare dati strutturati in un'unica posizione. Un oggetto può avere più proprietà di tipo diverso. Nel file Bicep è possibile usare oggetti all'interno di definizioni di risorse, di variabili o di espressioni. Ecco un esempio di oggetto:

param appServicePlanSku object = {
  name: 'F1'
  tier: 'Free'
  capacity: 1
}

Questo parametro è un oggetto con due proprietà stringa, name e tier, e una proprietà integer, capacity. Si noti che ognuna delle proprietà si trova su una riga a sé stante.

Quando si fa riferimento al parametro nel modello, è possibile selezionare le singole proprietà dell'oggetto usando un punto seguito dal nome della proprietà, come nell'esempio seguente:

resource appServicePlan 'Microsoft.Web/serverfarms@2022-03-01' = {
  name: appServicePlanName
  location: location
  sku: {
    name: appServicePlanSku.name
    tier: appServicePlanSku.tier
    capacity: appServicePlanSku.capacity
  }
}

Importante

Tenere presente che non si specifica il tipo di ogni proprietà all'interno di un oggetto. Tuttavia, quando si usa il valore di una proprietà, il relativo tipo deve corrispondere a quello previsto. Nell'esempio precedente, il nome e il livello dello SKU del piano di servizio app devono essere stringhe.

Un altro esempio di dove può essere utile impiegare un parametro di oggetto è per specificare tag di risorsa. È possibile associare alle risorse distribuite metadati di tag personalizzati, che permettono di identificare informazioni importanti su una risorsa.

I tag sono utili per scenari quali determinare il team proprietario di una risorsa oppure se la risorsa appartiene a un ambiente di produzione o meno. Normalmente si usano tag diversi per ogni ambiente, ma è necessario riutilizzare gli stessi valori dei tag in tutte le risorse all'interno del modello. Per questo motivo, i tag delle risorse rappresentano un buon caso d'uso per un parametro di oggetto, come in questo esempio:

param resourceTags object = {
  EnvironmentName: 'Test'
  CostCenter: '1000100'
  Team: 'Human Resources'
}

Ogni volta che si definisce una risorsa nel file Bicep, è possibile riutilizzarla ogni volta che si definisce la proprietà tags:

resource appServicePlan 'Microsoft.Web/serverfarms@2022-03-01' = {
  name: appServicePlanName
  location: location
  tags: resourceTags
  sku: {
    name: 'S1'
  }
}

resource appServiceApp 'Microsoft.Web/sites@' = {
  name: appServiceAppName
  location: location
  tags: resourceTags
  kind: 'app'
  properties: {
    serverFarmId: appServicePlan.id
  }
}

Matrici

Una matrice è un elenco di elementi. Per fare un esempio, si potrebbe usare una matrice di valori stringa per dichiarare un elenco di indirizzi di posta elettronica per un gruppo di azioni di Monitoraggio di Azure. Oppure, si potrebbe usare una matrice di oggetti per rappresentare un elenco di subnet per una rete virtuale.

Nota

Non è possibile specificare il tipo dei singoli elementi che una matrice deve contenere. Ad esempio, non si può specificare che una matrice deve contenere stringhe.

Di seguito è riportato un esempio. Azure Cosmos DB consente di creare account di database che si estendono su più aree e gestisce automaticamente la replica dei dati. Quando si distribuisce un nuovo account di database, è necessario specificare l'elenco di aree di Azure in cui distribuire l'account. Spesso è utile disporre di elenchi di posizioni diversi per ambienti diversi. Ad esempio, per risparmiare sull'ambiente di test si potrebbero usare solo una o due posizioni. Nell'ambiente di produzione, al contrario, si potrebbero usare più posizioni.

È possibile creare un parametro di matrice che specifica un elenco di posizioni:

param cosmosDBAccountLocations array = [
  {
    locationName: 'australiaeast'
  }
  {
    locationName: 'southcentralus'
  }
  {
    locationName: 'westeurope'
  }
]

Suggerimento

L'elenco precedente è una matrice di oggetti. Ogni oggetto ha una proprietà locationName, come previsto da Azure Cosmos DB. Quando si lavora con una definizione di risorsa in Visual Studio Code, si può iniziare immettendo le proprietà della risorsa in modo da accedere a IntelliSense dagli strumenti Bicep. È possibile creare alcuni valori di esempio usando questo approccio. Quando si è soddisfatti della configurazione, spostare quella sezione di codice Bicep nel parametro. In questo modo è possibile sostituire una proprietà hardcoded con un parametro modificabile in ogni distribuzione, garantendo comunque che la risorsa sia configurata correttamente.

Ora, quando si dichiara la risorsa Azure Cosmos DB, è possibile fare riferimento al parametro di matrice:

resource account 'Microsoft.DocumentDB/databaseAccounts@2022-08-15' = {
  name: accountName
  location: location
  properties: {
    locations: cosmosDBAccountLocations
  }
}

In questa maniera è facile usare un valore di parametro diverso per l'ambiente di sviluppo, modificando il valore del parametro. A breve si apprenderà come specificare valori di parametro diversi senza modificare il modello originale.

Specificare un set di valori consentiti

In alcuni casi è necessario assicurarsi che un parametro abbia determinati valori. Ad esempio, il team potrebbe decidere che i piani di servizio app di produzione devono essere distribuiti usando SKU Premium v3. Per applicare questa regola si può usare l'espressione Decorator del parametro @allowed. Un'espressione Decorator del parametro è un modo per fornire a Bicep informazioni sul valore di un parametro. Ecco come si può limitare un parametro stringa denominato appServicePlanSkuName in modo che sia possibile assegnare solo alcuni valori specifici:

@allowed([
  'P1v3'
  'P2v3'
  'P3v3'
])
param appServicePlanSkuName string

Suggerimento

Usare l'espressione Decorator @allowed con moderazione. Usandola in modo eccessivo, se non si mantiene aggiornato l'elenco si corre il rischio di bloccare delle distribuzioni valide. L'esempio precedente permette di usare nell'ambiente di produzione solo SKU Premium v3. Se occorre usare lo stesso modello per distribuire ambienti non di produzione più economici, l'elenco dei valori consentiti potrebbe impedire l'uso di altri SKU necessari.

Limitare la lunghezza e i valori dei parametri

Quando si usano parametri stringa, spesso è necessario limitare la lunghezza della stringa. Si consideri l'esempio della denominazione delle risorse di Azure. Tutti i tipi di risorse di Azure hanno limiti relativi alla lunghezza dei nomi. È buona norma specificare il numero minimo e massimo dei caratteri per i parametri che controllano la denominazione, in modo da evitare errori in fase di distribuzione. È possibile usare le espressioni Decorator @minLength e @maxLength per indicare la lunghezza minima e massima consentita per un parametro.

Ecco un esempio che dichiara un parametro stringa denominato storageAccountName, la cui lunghezza deve essere compresa tra 5 e 24 caratteri:

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

Questo parametro include due espressioni Decorator. È possibile applicare più espressioni Decorator a un parametro, inserendone ognuna in una riga separata.

Nota

È anche possibile applicare le espressioni Decorator @minLength e @maxLength ai parametri di matrice, per controllare il numero di elementi consentiti nella matrice.

Quando si lavora con parametri numerici, può essere necessario che i valori siano compresi in uno specifico intervallo. Ad esempio, l'azienda di giocattoli potrebbe decidere che, ogni volta che un utente distribuisce un piano di servizio app, deve sempre distribuire almeno un'istanza del piano, ma non più di 10. Per soddisfare i requisiti, si possono usare le espressioni Decorator @minValue e @maxValue per specificare il valore massimo e minimo consentito. L'esempio seguente dichiara il parametro Integer appServicePlanInstanceCount, il cui valore può essere compreso solo tra 1 e 10 (inclusi):

@minValue(1)
@maxValue(10)
param appServicePlanInstanceCount int

Aggiungere descrizioni ai parametri

I parametri sono ideali per fare in modo che altre persone possano riutilizzare i modelli. Chi userà i modelli dovrà comprendere a cosa serve ogni parametro per poter inserire i valori appropriati. Bicep fornisce l'espressione Decorator @description, che consente di documentare lo scopo dei parametri in modo leggibile.

@description('The locations into which this Cosmos DB account should be configured. This parameter needs to be a list of objects, each of which has a locationName property.')
param cosmosDBAccountLocations array

È buona norma fornire descrizioni per i parametri. Provare a creare descrizioni utili e fornire tutte le informazioni importanti sui requisiti del modello in termini di valori dei parametri.

Nota

Talvolta i modelli Bicep possono essere resi disponibili nel portale di Azure perché gli utenti possano distribuirli, come quando si usano le specifiche di modello. Il portale usa le descrizioni e altre espressioni Decorator sui parametri per aiutare gli utenti a comprendere quale deve essere il valore di un parametro.