Riconoscere la struttura e la sintassi dei file Bicep

Questo articolo descrive la struttura e la sintassi di un file Bicep. Presenta le diverse sezioni del file e le proprietà disponibili in tali sezioni.

Per un'esercitazione dettagliata che illustra il processo di creazione di un file Bicep, vedere Avvio rapido: Creare file Bicep con Visual Studio Code.

Formato Bicep

Bicep è un linguaggio dichiarativo, il che significa che gli elementi possono essere visualizzati in qualsiasi ordine. A differenza dei linguaggi imperativi, l'ordine degli elementi non influisce sul modo in cui viene elaborata la distribuzione.

Un file Bicep include gli elementi seguenti.

metadata <metadata-name> = ANY

targetScope = '<scope>'

type <user-defined-data-type-name> = <type-expression>

func <user-defined-function-name> (<argument-name> <data-type>, <argument-name> <data-type>, ...) <function-data-type> => <expression>

@<decorator>(<argument>)
param <parameter-name> <parameter-data-type> = <default-value>

var <variable-name> = <variable-value>

resource <resource-symbolic-name> '<resource-type>@<api-version>' = {
  <resource-properties>
}

module <module-symbolic-name> '<path-to-file>' = {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
}

output <output-name> <output-data-type> = <output-value>

Nell'esempio seguente viene visualizzata un'implementazione di questi elementi.

metadata description = 'Creates a storage account and a web app'

@description('The prefix to use for the storage account name.')
@minLength(3)
@maxLength(11)
param storagePrefix string

param storageSKU string = 'Standard_LRS'
param location string = resourceGroup().location

var uniqueStorageName = '${storagePrefix}${uniqueString(resourceGroup().id)}'

resource stg 'Microsoft.Storage/storageAccounts@2022-09-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

module webModule './webApp.bicep' = {
  name: 'webDeploy'
  params: {
    skuName: 'S1'
    location: location
  }
}

Metadati UFX

I metadati in Bicep sono un valore non tipizzato che può essere incluso nei file Bicep. Consente di fornire informazioni supplementari sui file Bicep, inclusi dettagli come il nome, la descrizione, l'autore, la data di creazione e altro ancora.

Ambito target

Per impostazione predefinita, l'ambito di destinazione è impostato su resourceGroup. Se si esegue la distribuzione a livello di gruppo di risorse, non è necessario impostare l'ambito di destinazione nel file Bicep.

I valori consentiti sono:

• resourceGroup: valore predefinito, usato per le distribuzioni del gruppo di risorse.
• sottoscrizione: usata per le distribuzioni di sottoscrizioni.
• managementGroup: usato per le distribuzioni dei gruppi di gestione.
• tenant: usato per le distribuzioni tenant.

In un modulo è possibile specificare un ambito diverso dall'ambito per il resto del file Bicep. Per altre informazioni, vedere Configurare l'ambito del modulo

Tipi

È possibile usare l'istruzione type per definire i tipi di dati definiti dall'utente.

param location string = resourceGroup().location

type storageAccountSkuType = 'Standard_LRS' | 'Standard_GRS'

type storageAccountConfigType = {
  name: string
  sku: storageAccountSkuType
}

param storageAccountConfig storageAccountConfigType = {
  name: 'storage${uniqueString(resourceGroup().id)}'
  sku: 'Standard_LRS'
}

resource storageAccount 'Microsoft.Storage/storageAccounts@2022-09-01' = {
  name: storageAccountConfig.name
  location: location
  sku: {
    name: storageAccountConfig.sku
  }
  kind: 'StorageV2'
}

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

Funzioni (anteprima)

Nota

Per abilitare la funzionalità di anteprima, vedere Abilitare le funzionalità sperimentali.

Nel file Bicep è possibile creare funzioni personalizzate oltre a usare le funzioni Bicep standard disponibili automaticamente nei file Bicep. Creare funzioni personalizzate quando sono presenti espressioni complesse che vengono usate ripetutamente nei file Bicep.

func buildUrl(https bool, hostname string, path string) string => '${https ? 'https' : 'http'}://${hostname}${empty(path) ? '' : '/${path}'}'

output azureUrl string = buildUrl(true, 'microsoft.com', 'azure')

Per altre informazioni, vedere Eseguire funzioni definite dall'utente.

Parametri

Usare i parametri per i valori che devono variare per distribuzioni diverse. È possibile definire un valore predefinito per il parametro usato se non viene specificato alcun valore durante la distribuzione.

Ad esempio, è possibile aggiungere un parametro SKU per specificare dimensioni diverse per una risorsa. È possibile passare valori diversi a seconda che si stia distribuendo in fase di test o produzione.

param storageSKU string = 'Standard_LRS'

Il parametro è disponibile per l'uso nel file Bicep.

sku: {
  name: storageSKU
}

Per altre informazioni, vedere Parametri in Bicep.

Decorator di parametri

È possibile aggiungere uno o più elementi Decorator per ogni parametro. Questi elementi decorator descrivono il parametro e definiscono i vincoli per i valori passati. L'esempio seguente mostra un elemento Decorator, ma molti altri sono disponibili.

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
param storageSKU string = 'Standard_LRS'

Per altre informazioni, incluse le descrizioni di tutti gli elementi Decorator disponibili, vedere Decorator.

Variabili

È possibile rendere il file Bicep più leggibile incapsulando espressioni complesse in una variabile. Ad esempio, è possibile aggiungere una variabile per un nome di risorsa costruito concatenando diversi valori insieme.

var uniqueStorageName = '${storagePrefix}${uniqueString(resourceGroup().id)}'

Applicare questa variabile ovunque sia necessaria l'espressione complessa.

resource stg 'Microsoft.Storage/storageAccounts@2019-04-01' = {
  name: uniqueStorageName

Per altre informazioni, vedere Variabili in Bicep.

Risorse

Usare la parola chiave resource per definire una risorsa da distribuire. La dichiarazione di risorsa include un nome simbolico per la risorsa. Questo nome simbolico viene usato in altre parti del file Bicep per ottenere un valore dalla risorsa.

La dichiarazione di risorsa include il tipo di risorsa e la versione dell'API. All'interno del corpo della dichiarazione di risorsa includere proprietà specifiche del tipo di risorsa.

resource stg 'Microsoft.Storage/storageAccounts@2019-06-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

Per altre informazioni, vedere Dichiarazione di risorse in Bicep.

Alcune risorse hanno una relazione padre/figlio. È possibile definire una risorsa figlio all'interno della risorsa padre o all'esterno di essa.

Nell'esempio seguente viene illustrato come definire una risorsa figlio all'interno di una risorsa padre. Contiene un account di archiviazione con una risorsa figlio (servizio file) definita all'interno dell'account di archiviazione. Il servizio file include anche una risorsa figlio (condivisione) definita al suo interno.

resource storage 'Microsoft.Storage/storageAccounts@2022-09-01' = {
  name: 'examplestorage'
  location: resourceGroup().location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_LRS'
  }

  resource service 'fileServices' = {
    name: 'default'

    resource share 'shares' = {
      name: 'exampleshare'
    }
  }
}

Nell'esempio seguente viene illustrato come definire una risorsa figlio all'esterno della risorsa padre. Utilizzare la proprietà padre per identificare una relazione padre/figlio. Vengono definite le stesse tre risorse.

resource storage 'Microsoft.Storage/storageAccounts@2022-09-01' = {
  name: 'examplestorage'
  location: resourceGroup().location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_LRS'
  }
}

resource service 'Microsoft.Storage/storageAccounts/fileServices@2022-09-01' = {
  name: 'default'
  parent: storage
}

resource share 'Microsoft.Storage/storageAccounts/fileServices/shares@2022-09-01' = {
  name: 'exampleshare'
  parent: service
}

Per altre informazioni, vedere Impostare il nome e il tipo per le risorse figlio nel file Bicep.

Moduli

I moduli consentono di riutilizzare il codice da un file Bicep in altri file Bicep. Nella dichiarazione del modulo si collega al file da riutilizzare. Quando si distribuisce il file Bicep, vengono distribuite anche le risorse nel modulo.

module webModule './webApp.bicep' = {
  name: 'webDeploy'
  params: {
    skuName: 'S1'
    location: location
  }
}

Il nome simbolico consente di fare riferimento al modulo da un'altra posizione nel file. Ad esempio, è possibile ottenere un valore di output da un modulo usando il nome simbolico e il nome del valore di output.

Per altre informazioni, vedere Usare i moduli Bicep.

Decorator di risorse e moduli

È possibile aggiungere un elemento Decorator a una definizione di risorsa o modulo. Gli elementi Decorator supportati sono batchSize(int) e description. È possibile applicarlo solo a una definizione di risorsa o di modulo che usa un'espressione for.

Per impostazione predefinita, le risorse vengono distribuite in parallelo. Quando si aggiunge l'elemento Decorator batchSize(int), si distribuiscono le istanze in modo seriale.

@batchSize(3)
resource storageAccountResources 'Microsoft.Storage/storageAccounts@2019-06-01' = [for storageName in storageAccounts: {
  ...
}]

Per altre informazioni, vedere Distribuire in batch.

Output

Usare gli output per restituire valori dalla distribuzione. In genere, si restituisce un valore da una risorsa distribuita quando è necessario riutilizzare tale valore per un'altra operazione.

output storageEndpoint object = stg.properties.primaryEndpoints

Per altre informazioni, vedere Output in Bicep.

Cicli

È possibile aggiungere cicli iterativi al file Bicep per definire più copie di un oggetto :

• resource
• modulo
• Variabile
• proprietà
• output

Usare l'espressione for per definire un ciclo.

param moduleCount int = 2

module stgModule './example.bicep' = [for i in range(0, moduleCount): {
  name: '${i}deployModule'
  params: {
  }
}]

È possibile eseguire l'iterazione su una matrice, un oggetto o un indice intero.

Per altre informazioni, vedere Cicli iterativi in Bicep.

Distribuzione condizionale

È possibile aggiungere una risorsa o un modulo al file Bicep distribuito in modo condizionale. Durante la distribuzione, la condizione viene valutata e il risultato determina se la risorsa o il modulo viene distribuito. Usare l'espressione if per definire una distribuzione condizionale.

param deployZone bool

resource dnsZone 'Microsoft.Network/dnszones@2018-05-01' = if (deployZone) {
  name: 'myZone'
  location: 'global'
}

Per altre informazioni, vedere Distribuzione condizionale in Bicep.

Spazio vuoto

Gli spazi e le schede vengono ignorati durante la creazione di file Bicep.

Bicep è sensibile alla nuova riga. Ad esempio:

resource sa 'Microsoft.Storage/storageAccounts@2019-06-01' = if (newOrExisting == 'new') {
  ...
}

Non è possibile scrivere come segue:

resource sa 'Microsoft.Storage/storageAccounts@2019-06-01' =
    if (newOrExisting == 'new') {
      ...
    }

Definire oggetti e matrici in più righe.

Commenti

Usare // per i commenti a riga singola o /* ... */ per i commenti su più righe

Nell'esempio seguente viene illustrato un commento a riga singola.

// This is your primary NIC.
resource nic1 'Microsoft.Network/networkInterfaces@2020-06-01' = {
   ...
}

Nell'esempio seguente viene illustrato un commento su più righe.

/*
  This Bicep file assumes the key vault already exists and
  is in same subscription and resource group as the deployment.
*/
param existingKeyVaultName string

Stringhe multilinea

È possibile suddividere una stringa in più righe. Usare tre caratteri virgolette singole ''' per iniziare e terminare la stringa multilinea.

I caratteri all'interno della stringa a più righe vengono gestiti così come sono. I caratteri di escape non sono necessari. Non è possibile includere ''' nella stringa multilinea. L'interpolazione di stringhe non è attualmente supportata.

È possibile avviare la stringa subito dopo ''' di apertura o includere una nuova riga. In entrambi i casi, la stringa risultante non include una nuova riga. A seconda delle terminazioni di riga nel file Bicep, le nuove righe vengono interpretate come \r\n o \n.

Nell'esempio seguente viene illustrata una stringa multilinea.

var stringVar = '''
this is multi-line
  string with formatting
  preserved.
'''

L'esempio precedente è equivalente al codice JSON seguente.

"variables": {
  "stringVar": "this is multi-line\r\n  string with formatting\r\n  preserved.\r\n"
}

Dichiarazioni multilinea

È ora possibile usare più righe nelle dichiarazioni di funzione, matrice e oggetto. Questa funzione richiede l'interfaccia della riga di comando di Bicep versione 0.7.X o successiva.

Nell'esempio seguente la definizione resourceGroup() viene suddivisa in più righe.

var foo = resourceGroup(
  mySubscription,
  myRgName)

Vedere Matrici e oggetti per esempi di dichiarazione multilinea.

Limitazioni note

• Nessun supporto per il concetto di apiProfile, usato per eseguire il mapping di un singolo apiProfile a un set apiVersion per ogni tipo di risorsa.
• Le funzioni definite dall'utente non sono attualmente supportate. Tuttavia, una funzionalità sperimentale è attualmente accessibile. Per altre informazioni, vedere Funzioni definite dall'utente in Bicep.
• Alcune funzionalità di Bicep richiedono una modifica corrispondente al linguaggio intermedio (modelli JSON di Azure Resource Manager). Queste funzionalità vengono annunciate come disponibili quando tutti gli aggiornamenti necessari sono stati distribuiti in Azure globale. Se si usa un ambiente diverso, ad esempio Azure Stack, potrebbe verificarsi un ritardo nella disponibilità della funzionalità. La funzionalità Bicep è disponibile solo quando il linguaggio intermedio è stato aggiornato anche in tale ambiente.

Passaggi successivi

Per un'introduzione a Bicep, vedere Che cos'è Bicep?. Per i tipi di dati Bicep, vedere Tipi di dati.