Compreender a estrutura e sintaxe dos ficheiros Bicep

Este artigo descreve a estrutura e a sintaxe de um ficheiro Bicep. Apresenta as diferentes secções do ficheiro e as propriedades que estão disponíveis nessas secções.

Para um tutorial passo a passo que o guia através do processo de criação de um ficheiro Bicep, consulte Quickstart: Create Bicep files with Visual Studio Code.

Formato Bicep

Bicep é uma linguagem declarativa, o que significa que os elementos podem aparecer em qualquer ordem. Ao contrário das línguas imperativas, a ordem dos elementos não afeta a forma como a implantação é processada.

Um ficheiro Bicep tem os seguintes elementos.

targetScope = '<scope>'

@<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>

O exemplo a seguir mostra uma implementação destes elementos.

@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@2019-04-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

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

output storageEndpoint object = stg.properties.primaryEndpoints

Âmbito de destino

Por predefinição, o âmbito de aplicação do alvo é definido para resourceGroup. Se estiver a implementar ao nível do grupo de recursos, não precisa de definir o âmbito de destino no seu ficheiro Bicep.

Os valores permitidos são:

Num módulo, pode especificar um âmbito diferente do âmbito para o resto do ficheiro Bicep. Para mais informações, consulte o âmbito do módulo Configure

Parâmetros

Utilize parâmetros para valores que precisam de variar para diferentes implementações. Pode definir um valor predefinido para o parâmetro que é utilizado se não for fornecido qualquer valor durante a implementação.

Por exemplo, pode adicionar um parâmetro SKU para especificar diferentes tamanhos para um recurso. Pode passar em valores diferentes dependendo se está a implementar para testar ou produzir.

param storageSKU string = 'Standard_LRS'

O parâmetro está disponível para utilização no seu ficheiro Bicep.

sku: {
  name: storageSKU
}

Para mais informações, consulte Parâmetros em Bicep.

Decoradores de parâmetros

Pode adicionar um ou mais decoradores para cada parâmetro. Estes decoradores descrevem o parâmetro e definem constrangimentos para os valores que são passados. O exemplo a seguir mostra um decorador, mas há muitos outros disponíveis.

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

Para mais informações, incluindo descrições de todos os decoradores disponíveis, consulte decoradores.

Variáveis

Pode tornar o seu ficheiro Bicep mais legível encapsulando expressões complexas numa variável. Por exemplo, pode adicionar uma variável para um nome de recurso que é construído através da concatenação de vários valores juntos.

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

Aplique esta variável onde precisar da expressão complexa.

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

Para mais informações, consulte Variáveis em Bicep.

Recursos

Utilize a resource palavra-chave para definir um recurso para implementar. A sua declaração de recursos inclui um nome simbólico para o recurso. Você usará este nome simbólico em outras partes do ficheiro Bicep para obter um valor do recurso.

A declaração de recursos inclui o tipo de recurso e a versão API. Dentro do corpo da declaração de recursos, incluem propriedades específicas do tipo de recurso.

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

Para mais informações, consulte a declaração de Recursos em Bicep.

Alguns recursos têm uma relação pai/filho. Pode definir um recurso para crianças dentro do recurso dos pais ou fora dele.

O exemplo a seguir mostra como definir um recurso infantil dentro de um recurso principal. Contém uma conta de armazenamento com um recurso infantil (serviço de ficheiros) que é definido dentro da conta de armazenamento. O serviço de ficheiros também tem um recurso infantil (share) que é definido dentro dele.

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

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

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

O exemplo seguinte mostra como definir um recurso infantil fora do recurso principal. Usa a propriedade dos pais para identificar uma relação pai/filho. Os mesmos três recursos são definidos.

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

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

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

Para obter mais informações, consulte o nome definido e o tipo de recursos para crianças em Bicep.

Módulos

Os módulos permitem a reutilização do código a partir de um ficheiro Bicep em outros ficheiros Bicep. Na declaração do módulo, liga-se ao ficheiro para reutilizar. Quando implementa o ficheiro Bicep, os recursos do módulo também são implantados.

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

O nome simbólico permite-lhe fazer referência ao módulo a partir de outro lugar do ficheiro. Por exemplo, pode obter um valor de saída a partir de um módulo usando o nome simbólico e o nome do valor de saída.

Para obter mais informações, consulte os módulos Bicep.

Decoradores de recursos e módulos

Pode adicionar um decorador a uma definição de recurso ou módulo. O único decorador apoiado é batchSize(int). Só é possível aplicá-lo a uma definição de recurso ou módulo que utilize uma for expressão.

Por defeito, os recursos são implantados em paralelo. Quando se adiciona o batchSize decorador, implementa-se as ocorrências em série.

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

Para obter mais informações, consulte Implementar em lotes.

Saídas

Utilize saídas para devolver valores da implantação. Normalmente, devolve-se um valor a partir de um recurso implantado quando é necessário reutilizar esse valor para outra operação.

output storageEndpoint object = stg.properties.primaryEndpoints

Para mais informações, consulte Outputs em Bicep.

Ciclos

Pode adicionar laços iterativos ao seu ficheiro Bicep para definir várias cópias de a:

  • recurso
  • módulo
  • variável
  • property
  • saída

Use a for expressão para definir um loop.

param moduleCount int = 2

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

Pode iterar sobre um índice de matriz, objeto ou inteiro.

Para mais informações, consulte loops iterativos em Bicep.

Implementação condicional

Pode adicionar um recurso ou módulo ao seu ficheiro Bicep que esteja equipado condicionalmente. Durante a implementação, a condição é avaliada e o resultado determina se o recurso ou módulo é implantado. Utilize a if expressão para definir uma implementação condicional.

param deployZone bool

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

Para obter mais informações, consulte a implementação condicional em Bicep.

Espaço em branco

Os espaços e separadores são ignorados quando se autorizam ficheiros Bicep.

Bicep é sensível à nova linha. Por exemplo:

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

Não pode ser escrito como:

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

Defina objetos e matrizes em várias linhas.

Comentários

Utilização // para comentários de linha única ou /* ... */ para comentários multi-linhas

O exemplo a seguir mostra um comentário de uma única linha.

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

O exemplo a seguir mostra um comentário multi-line.

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

Cordas multi-linha

Pode partir uma corda em várias linhas. Utilize três caracteres ''' de citação única para iniciar e terminar a cadeia multi-linha.

Os caracteres dentro da cadeia multi-linha são manuseados como-é. Os personagens de fuga são desnecessários. Não pode incluir ''' na corda multi-linha. A interpolação de cordas não é suportada atualmente.

Pode iniciar a corda logo após a abertura ''' ou incluir uma nova linha. Em qualquer dos casos, a cadeia resultante não inclui uma nova linha. Dependendo das terminações de linha no seu ficheiro Bicep, novas linhas são interpretadas como \r\n ou \n.

O exemplo a seguir mostra uma corda multi-linha.

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

O exemplo anterior é equivalente ao seguinte JSON.

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

Declarações de linha múltipla

Pode agora utilizar várias linhas em função, declarações de matriz e objeto. Esta funcionalidade requer a versão Bicep 0.7.4 ou posterior.

No exemplo seguinte, a resourceGroup() definição é dividida em várias linhas.

var foo = resourceGroup(
  mySubscription,
  myRgName)

Consulte Arrays e Objects para obter amostras de declaração de várias linhas.

Limitações conhecidas

  • Sem suporte para o conceito de apiProfile, que é usado para mapear um único apiProfile para uma apiversão definida para cada tipo de recurso.
  • Sem suporte para funções definidas pelo utilizador.
  • Algumas características bicep requerem uma alteração correspondente à linguagem intermédia (Azure Resource Manager modelos JSON). Anunciamos estas funcionalidades como disponíveis quando todas as atualizações necessárias foram implementadas para o Azure global. Se estiver a utilizar um ambiente diferente, como o Azure Stack, poderá haver um atraso na disponibilidade da funcionalidade. A funcionalidade Bicep só está disponível quando a língua intermédia também foi atualizada nesse ambiente.

Passos seguintes

Para uma introdução a Bicep, veja o que é Bicep? Para os tipos de dados Bicep, consulte os tipos de Dados.