Entender a estrutura e a sintaxe dos arquivos Bicep

Artigo
09/01/2024

Este artigo descreve a estrutura e sintaxe de um arquivo Bicep. Ele apresenta as diferentes seções do arquivo e as propriedades que estão disponíveis nessas seções.

Para obter um tutorial passo a passo que guia você durante o processo de criação de um arquivo Bicep, consulte Início Rápido: criar arquivos Bicep com Visual Studio Code.

Formato Bicep

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

O arquivo Bicep tem os elementos a seguir.

@<decorator>(<argument>)
metadata <metadata-name> = ANY

targetScope = '<scope>'

@<decorator>(<argument>)
type <user-defined-data-type-name> = <type-expression>

@<decorator>(<argument>)
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>

@<decorator>(<argument>)
var <variable-name> = <variable-value>

@<decorator>(<argument>)
resource <resource-symbolic-name> '<resource-type>@<api-version>' = {
  <resource-properties>
}

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

@<decorator>(<argument>)
output <output-name> <output-data-type> = <output-value>

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

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

Metadados

Metadados no Bicep é um valor não digitado que pode ser incluído nos arquivos do Bicep. Ele permite que você forneça informações complementares sobre seus arquivos do Bicep, incluindo detalhes como nome, descrição, autor, data de criação e muito mais.

Escopo de destino

Por padrão, o escopo de destino é definido como resourceGroup. Se você estiver implantando no nível do grupo de recursos, não será necessário definir o escopo de destino no seu arquivo Bicep.

Os valores permitidos são:

resourceGroup – valor padrão, usado para implantações do grupo de recursos.
subscription – Usado para implantações de assinatura.
managementGroup – Usado para implantações do grupo de gerenciamento.
tenant – Usado para implantações de locatário.

Em um módulo, você pode especificar um escopo diferente do escopo para o restante do arquivo Bicep. Para saber mais, consulte Configurar escopo do módulo

Decoradores

Você pode adicionar um ou mais decoradores para cada um dos seguintes elementos:

param
var
recurso
module
output
func
tipo

Os decoradores incluem:

Decorador	Aplicar ao elemento	Aplicar ao tipo de dados	Argument	Descrição
permitido	param	all	matriz	Use este decorador para garantir que o usuário forneça valores corretos. Esse decorador só é permitido em instruções `param`. Para declarar que uma propriedade deve ser um de um conjunto de valores predefinidos em uma instrução `type` ou `output`, use a sintaxe de tipo de união. A sintaxe de tipo de união também pode ser usada em instruções `param`.
batchSize	módulo, recurso	N/D	Número inteiro	Configure instâncias para serem implantadas sequencialmente.
descrição	função, parâmetro, módulo, saída, recurso, tipo, variável	all	string	Forneça descrições para os elementos. O texto formatado em Markdown pode ser usado para o texto de descrição.
discriminador	param, type, output	objeto	string	Use esse decorador para garantir que a subclasse correta seja identificada e gerenciada. Para obter mais informações, confira Tipo de dados de união com marcas personalizadas.
exportar	função, tipo, variável	all	nenhum	Indica que o elemento pode ser importado por outro arquivo Bicep.
maxLength	parâmetro, saída, tipo	matriz, cadeia de caracteres	int	O tamanho máximo para elementos de cadeia de caracteres e matriz. O valor é inclusivo.
maxValue	parâmetro, saída, tipo	INT	INT	O valor máximo para os elementos inteiros. Esse valor é inclusivo.
metadata	função, saída, parâmetros, tipo	all	objeto	Propriedades personalizadas a serem aplicadas aos elementos. Pode incluir uma propriedade de descrição que seja equivalente ao decorador da descrição.
minLength	parâmetro, saída, tipo	matriz, cadeia de caracteres	int	O tamanho mínimo para elementos de cadeia de caracteres e matriz. O valor é inclusivo.
minValue	parâmetro, saída, tipo	INT	INT	O valor mínimo para os elementos inteiros. Esse valor é inclusivo.
sealed	param, type, output	objeto	nenhum	Eleve o BCP089 de aviso para erro quando um nome de propriedade de um tipo de dados definido pelo usuário for provavelmente um erro de digitação. Para obter mais informações, consulte Elevar nível de erro.
seguro	parâmetro, tipo	cadeia de caracteres, objeto	nenhum	Marca o parâmetro como seguro. O valor de um parâmetro seguro não é salvo no histórico de implantação e não é registrado em log. Para obter mais informações, confira Proteger cadeias de caracteres e objetos.

Parâmetros

Use parâmetros para valores que precisam variar para implantações diferentes. Você poderá definir um valor padrão para o parâmetro que será usado se nenhum valor for fornecido durante a implantação.

Por exemplo, você pode adicionar um parâmetro de SKU a fim de especificar tamanhos diferentes para um recurso. Você pode passar valores diferentes dependendo se estiver implantando para teste ou produção.

param storageSKU string = 'Standard_LRS'

O parâmetro está disponível para uso em seu arquivo Bicep.

sku: {
  name: storageSKU
}

Você pode adicionar um ou mais decoradores para cada parâmetro. Para obter mais informações, confira Usar decoradores.

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

Variáveis

Você pode tornar o arquivo Bicep mais legível encapsulando expressões complexas em uma variável. Por exemplo, você pode adicionar uma variável para um nome de recurso que é construído concatenando vários valores juntos.

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

Aplique essa variável sempre que precisar da expressão complexa.

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

Você pode adicionar um ou mais decoradores para cada variável. Para obter mais informações, confira Usar decoradores.

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

Tipos

Você pode usar a instrução type para definir tipos de dados definidos pelo usuário.

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@2023-04-01' = {
  name: storageAccountConfig.name
  location: location
  sku: {
    name: storageAccountConfig.sku
  }
  kind: 'StorageV2'
}

É possível adicionar um ou mais decoradores para cada tipo de dados definido pelo usuário. Para obter mais informações, confira Usar decoradores.

Para obter mais informações, confira Tipos de dados definidos pelo usuário.

Funções

No arquivo Bicep, você pode criar suas próprias funções além de usar as funções padrão do Bicep que estão automaticamente disponíveis em seus arquivos do Bicep. Crie suas próprias funções quando tiver expressões complicadas que são usadas repetidamente em seus arquivos do 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')

Para obter mais informações, consulte Funções definidas pelo usuário.

Recursos

Use a palavra-chave resource para definir um recurso a ser implantado. Sua declaração de recurso inclui um nome simbólico para o recurso. Você usa esse nome simbólico em outras partes do arquivo do Bicep para obter um valor do recurso.

A declaração de recurso inclui o tipo de recurso e a versão da API. No corpo da declaração de recurso, inclua propriedades que são específicas para o tipo de recurso.

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

Você pode adicionar um ou mais decoradores para cada recurso. Para obter mais informações, confira Usar decoradores.

Para obter mais informações, consulte Declaração de recursos no Bicep.

Alguns recursos têm uma relação pai/filho. Você pode definir um recurso filho dentro ou fora do recurso pai.

O exemplo a seguir mostra como definir um recurso filho dentro de um recurso pai. Ele contém uma conta de armazenamento com um recurso filho (serviço de arquivo) definido dentro da conta de armazenamento. O serviço de arquivo também tem um recurso filho (compartilhamento) definido nele.

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

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

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

O próximo exemplo mostra como definir o recurso filho de fora do recurso pai. Você usa a propriedade pai para identificar uma relação pai/filho. Os mesmos três recursos são definidos.

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

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

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

Para obter mais informações, confira Definir o nome e o tipo de recursos filho no Bicep.

Módulos

Os módulos permitem que você reutilize o código de um arquivo Bicep em outros arquivos Bicep. Na declaração do módulo, você vincula ao arquivo a ser reutilizado. Quando você implanta o arquivo Bicep, os recursos no módulo também são implantados.

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

O nome simbólico permite que você referencie o módulo de outros lugares do arquivo. Por exemplo, você pode obter um valor de saída de um módulo usando o nome simbólico e o nome do valor de saída.

Você pode adicionar um ou mais decoradores para cada módulo. Para obter mais informações, confira Usar decoradores.

Para obter mais informações, confira Usar módulos do Bicep.

Saídas

Use as saídas para retornar valores da implantação. Normalmente, você retorna um valor de um recurso implantado quando precisa reutilizar esse valor para outra operação.

output storageEndpoint object = stg.properties.primaryEndpoints

Você pode adicionar um ou mais decoradores para cada saída. Para obter mais informações, confira Usar decoradores.

Para obter mais informações, consulte Saídas no Bicep.

Loops

Você pode adicionar loops iterativos ao arquivo Bicep para definir várias cópias de um:

recurso
module
variável
propriedade
output

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: {
  }
}]

Você pode iterar sobre uma matriz, objeto ou índice de inteiro.

Para obter mais informações, confira Loops iterativos no Bicep.

Implantação condicional

Você pode adicionar um recurso ou módulo ao arquivo Bicep que está implantado condicionalmente. Durante a implantação, a condição é avaliada e o resultado determina se o recurso ou o módulo está implantado. Use a if expressão para definir uma implantação condicional.

param deployZone bool

resource dnsZone 'Microsoft.Network/dnsZones@2023-07-01-preview' = if (deployZone) {
  name: 'myZone'
  location: 'global'
}

Para obter mais informações, confira Implantação condicional no Bicep.

Espaço em branco

Os espaços e as guias são ignorados durante a criação de arquivos Bicep.

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

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

Não pode ser escrito como:

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

Defina objetos e matrizes em várias linhas.

Comentários

Use // para comentários de linha única ou /* ... */ para comentários de várias linhas

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

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

O exemplo a seguir mostra um comentário de várias linhas.

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

Cadeias de caracteres de várias linhas

Você pode dividir uma cadeia de caracteres em várias linhas. Use três caracteres de aspas simples ''' para iniciar e terminar a cadeia de caracteres de várias linhas.

Os caracteres que pertencem à cadeia de caracteres de várias linhas são tratados no estado em que se encontram. Não são necessários caracteres de escape. Não é permitido incluir ''' em cadeias de caracteres de várias linhas. Atualmente, não há suporte para a interpolação de cadeia de caracteres.

Você pode iniciar sua cadeia de caracteres logo após a abertura de ''' ou incluir uma nova linha. Em ambos os casos, a cadeia de caracteres resultante não inclui uma nova linha. Dependendo das terminações de linha do arquivo Bicep, novas linhas são interpretadas como \r\n ou \n.

O exemplo a seguir mostra uma cadeia de caracteres de várias linhas.

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

O código anterior é o equivalente ao JSON a seguir.

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

Declarações de várias linhas

Agora, você pode usar várias linhas em declarações de funções, matrizes e objetos. Esse recurso requer a CLI do Bicep versão 0.7.X ou superior.

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

var foo = resourceGroup(
  mySubscription,
  myRgName)

Consulte Matrizes e Objetos para obter exemplos de declarações de várias linhas.

Limitações conhecidas

Não há suporte para o conceito de apiProfile, que é usado para mapear um único apiProfile para um apiVersion de conjunto para cada tipo de recurso.
No momento, não há suporte para funções definidas pelo usuário. No entanto, um recurso experimental está acessível no momento. Para obter mais informações, confira Funções definidas pelo usuário no Bicep.
Alguns recursos do Bicep exigem uma alteração correspondente à linguagem intermediária (modelos JSON do Azure Resource Manager). Anunciamos esses recursos como disponíveis quando todas as atualizações necessárias foram implantadas no Azure global. Se você estiver usando um ambiente diferente, como o Azure Stack, pode haver um atraso na disponibilidade do recurso. O recurso Bicep só estará disponível quando a linguagem intermediária também tiver sido atualizada nesse ambiente.

Próximas etapas

Para obter uma introdução ao Bicep, confira O que é o Bicep?. Para tipos de dados Bicep, consulte Tipos de dados.

Compartilhar via

Entender a estrutura e a sintaxe dos arquivos Bicep

Formato Bicep

Metadados

Escopo de destino

Decoradores

Parâmetros

Variáveis

Tipos

Funções

Recursos

Módulos

Saídas

Loops

Implantação condicional

Espaço em branco

Comentários

Cadeias de caracteres de várias linhas

Declarações de várias linhas

Limitações conhecidas

Próximas etapas

Comentários

Recursos adicionais