File di parametri estendibili in Bicep

Usando i file di parametri Bicep estendibili, è possibile definire i parametri una sola volta in un file di parametri di base e riutilizzarli in più file di parametri derivati. Questo approccio migliora significativamente la riutilizzabilità dei parametri e garantisce la coerenza tra le distribuzioni. Bicep CLI versione 0.44.1 e successive supportano file di parametri estensibili, insieme alle parole chiave extends e base.

Un file di parametri derivato può estendere un solo file di parametri di base. Può contenere una extends sola istruzione. Tuttavia, è possibile creare file di parametri annidati concatenando le estensioni tra più file. Per altre informazioni, vedere File di parametri annidati.

L'istruzione extends eredita solo le assegnazioni di parametri.

• È possibile definire le variabili nel file dei parametri di base per calcolarne i valori dei parametri, ma tali variabili non vengono esposte ai file di parametri derivati.
• È possibile definire tipi definiti dall'utente nei file di parametri. È anche possibile importare tipi definiti dall'utente in un file di Bicep. Tuttavia, questi tipi definiti dall'utente non sono esposti ai file di parametri derivati.
• Non è possibile dichiarare funzioni definite dall'utente direttamente in un file di parametri. Tuttavia, è possibile importarli in un file di parametri. Queste funzioni non sono esposte ai file di parametri derivati.

Estendere il file di parametri

Per impostazione predefinita, i parametri definiti in un file di parametri derivato sovrascrivono completamente quelli nel file dei parametri di base. Per unire invece di sovrascrivere, usare la parola chiave base con la sintassi di diffusione di oggetti o matrici. Per altre informazioni, vedere Accedere ai parametri padre.

Usare l'istruzione using none nei file di parametri di base per indicare al compilatore di non associarli o convalidarli in base a un file di Bicep specifico.

Nell'esempio seguente viene illustrato il funzionamento dei file di parametri estendibili in Bicep.

Il modello Bicep principale, main.bicep, definisce i parametri che la distribuzione accetta.

param namePrefix string
param location string
param tags object

Un file di parametri di base, base.bicepparam, che è possibile riutilizzare in più distribuzioni e ambienti.

using none
// Notice that the first line of this .bicepparam file declares `using none` which tells the compiler not to validate this against any particular .bicep file.

param namePrefix = 'Prod'
param location = 'westus'
param tags = {
  environment: 'dev'
  owner: 'platform'
}

Un file di parametri esteso, derived.bicepparam, basato sul file di parametri di base. Fa riferimento sia al file Bicep che al file di parametri di base. I valori definiti qui eseguono l'override di quelli precedenti.

using 'main.bicep'

extends 'base.bicepparam'

param namePrefix = 'Dev'
param tags = {
  ...base.tags        // inherit the object from the base file
  environment: 'prod' // override a single property
  region: 'westus2'   // add new data
}

In questo esempio i valori dei parametri vengono applicati nei livelli con un ordine di precedenza chiaro. Il main.bicep file dichiara i parametri e può fornire valori predefiniti. Un file derivato.bicepparam può eseguire l'override dei valori definiti in un file di base.bicepparam e i valori dei parametri assegnati finali hanno la precedenza su qualsiasi valore predefinito definito nel modello di destinazione. I valori risolti sono:

Accedere ai parametri padre

Per usare la base parola chiave , il file di parametri derivato deve includere una extends clausola . Questa clausola rende disponibile base come identificatore, consentendoti di accedere a tutti i parametri padre come proprietà. Se si tenta di usare base senza una extends clausola , viene visualizzato un errore.

È possibile combinare l'operatore spread (...) con base per estendere o unire tipi di dati complessi in modo pulito. Questo approccio consente di copiare i valori di matrice o oggetti esistenti dal file padre e modificarli senza digitare nuovamente l'intera struttura di dati. L'operatore spread è strettamente limitato a oggetti e matrici. Se si tenta di distribuire un valore primitivo, ad esempio una stringa, un numero intero o un valore booleano, si verifica un errore di compilazione.

Tutti i valori sottoposti a override devono corrispondere al tipo di dati esatto previsto dal parametro di destinazione. L'inserimento di un tipo incompatibile genera un errore di tipo durante la compilazione.

Il file Bicep main.bicep:

param app object
param locations array
param fullName string

Il file di parametri di base base.bicepparam:

using none

param app = {
  name: 'demo'
  tags: {
    owner: 'platform'
    environment: 'dev'
  }
}
param locations = ['westus', 'eastus']

Il file di parametri derivato derived.bicepparam:

using './main.bicep'
extends './base.bicepparam'

// Merge objects
param app = {
  ...base.app
  tags: {
    ...base.app.tags
    environment: 'prod'
    costCenter: '1234'
  }
}

// Merge arrays
param locations = [...base.locations, 'centralus']

// Use base in expressions or variables
var suffix = '-api'
param fullName = '${base.app.name}${suffix}'

I valori risolti sono:

File di parametri annidati

Mentre un file di parametri derivato può contenere una sola istruzione extends, Bicep consente di creare gerarchie multilivello concatenando sequenzialmente i file di parametri (file di parametri A $\rightarrow$ file di parametri B $\rightarrow$ file di parametri C).

Questa struttura è utile per organizzare le distribuzioni aziendali. È possibile definire le impostazioni predefinite globali nella radice, eseguire l'override delle impostazioni a livello di ambiente nel livello intermedio e specificare configurazioni localizzate specifiche delle risorse a livello foglia.

Quando si compila una catena, qualsiasi file di parametri intermedio o radice nella sequenza deve includere l'istruzione using none . Questa istruzione segnala al compilatore Bicep che il file agisce rigorosamente come livello di configurazione e non è direttamente associato a un modello di distribuzione specifico.bicep.

L'esempio seguente illustra come configurare una catena a tre livelli per configurare un layout di risorse Azure, passando dalle impostazioni globali dell'organizzazione a un ambiente di sviluppo localizzato specifico.

Il file Bicep (compute.bicep)

param primaryLocation string

param globalTags object 
param environmentTags object
param resourceTags object

param skuName string
param vmSku string
param vmName string
...

Il livello radice: le impostazioni predefinite globali (global.bicepparam) stabiliscono le proprietà di base usate nell'intera organizzazione. Viene usato using none perché è puramente una base di configurazione.

using none

// Global baseline tags applied to every single resource
param globalTags = {
  BillingUnit: 'Enterprise-IT'
  DataClassification: 'Confidential'
}

// Default regional pair
param primaryLocation = 'eastus'

Il livello intermedio: le impostazioni di ambiente (dev-defaults.bicepparam) ereditano le proprietà globali, sostituiscono il tipo di ambiente e aggiungono configurazioni specifiche dell'ambiente. Poiché si tratta di un livello intermedio, usa anche using none.

using none
extends './global.bicepparam'

// Inherit global tags and inject the environment designation
param environmentTags = {
  ...base.globalTags
  Environment: 'Development'
}

// Override region for low-cost development testing
param primaryLocation = 'westus'

// Tier-specific infrastructure sizes
param skuName = 'Standard_D2s_v5'

Il livello leaf: distribuzione mirata (compute.dev.bicepparam) si rivolge a una distribuzione specifica del carico di lavoro. Si connette direttamente al vero e proprio modello di infrastruttura Bicep mediante l'istruzione using standard, ereditando l'intero stato combinato della catena.

extends './dev-defaults.bicepparam'
using './compute.bicep' // Binds the final resolved values to the template

// Combine all inherited layers into the final parameters expected by compute.bicep
param resourceTags = {
  ...base.environmentTags
  Workload: 'Web-FrontEnd'
}

// Use inherited environment SKU directly, or override it if needed
param vmSku = base.skuName

// Explicit deployment property
param vmName = 'vm-web-dev-01'

Contenuti correlati

• Per informazioni sui file di parametri Bicep, vedi File di parametri Bicep.
• Per informazioni su using e using none, vedere Uso e uso di istruzioni none.
• Per informazioni sull'operatore spread, vedere Operatore Spread.