Compreender a estrutura e a sintaxe dos arquivos Bicep
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 o orienta pelo processo de criação de um arquivo Bicep, consulte Guia de início rápido: criar arquivos Bicep com o Visual Studio Code.
Formato bíceps
Bicep é uma linguagem declarativa, o que significa que os elementos podem aparecer em qualquer ordem. Ao contrário das linguagens imperativas, a ordem dos elementos não afeta a forma como a implantação é processada.
Um arquivo Bicep tem os seguintes elementos.
@<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 tipado que pode ser incluído em arquivos Bicep. Ele permite que você forneça informações suplementares sobre seus arquivos Bicep, incluindo detalhes como nome, descrição, autor, data de criação e muito mais.
Âmbito de aplicação
Por padrão, o escopo de destino é definido como resourceGroup
. Se você estiver implantando no nível do grupo de recursos, não precisará definir o escopo de destino no arquivo Bicep.
Os valores permitidos são:
- resourceGroup - valor padrão, usado para implantações de grupos de recursos.
- Assinatura - usada para implantações de assinatura.
- managementGroup - usado para implantações de grupos de gerenciamento.
- locatário - 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 obter mais informações, consulte Configurar o escopo do módulo
Decoradores
Você pode adicionar um ou mais decoradores para cada um dos seguintes elementos:
Os decoradores incluem:
Decorador | Aplicar ao elemento | Aplicar ao tipo de dados | Argumento | Description |
---|---|---|---|---|
permitido | param | todos | matriz | Use este decorador para se certificar de que o usuário fornece valores corretos. Este decorador só é permitido em param declarações. Para declarar que uma propriedade deve ser um de um conjunto de valores predefinidos em uma type instrução or output , use a sintaxe do tipo união. A sintaxe do tipo União também pode ser usada em param instruções. |
batchSize | módulo, recurso | N/A | integer | Configure instâncias para implantar sequencialmente. |
descrição | func, param, módulo, saída, recurso, tipo, var | todos | string | Forneça descrições para os elementos. O texto formatado com marcação pode ser usado para o texto de descrição. |
discriminador | param, tipo, saída | objeto | string | Use este decorador para garantir que a subclasse correta seja identificada e gerenciada. Para obter mais informações, consulte Tipo de dados de união com tags personalizadas. |
exportar | func, tipo, var | todos | nenhum | Indica que o elemento pode ser importado por outro arquivo Bicep. |
maxComprimento | param, saída, tipo | matriz, string | número inteiro | O comprimento máximo para elementos de cadeia de caracteres e matriz. O valor é inclusivo. |
maxValor | param, saída, tipo | número inteiro | número inteiro | O valor máximo para os elementos inteiros. Este valor é inclusivo. |
do IdP | func, saída, param, tipo | todos | objeto | Propriedades personalizadas a serem aplicadas aos elementos. Pode incluir uma propriedade description equivalente ao decorador de descrição. |
minComprimento | param, saída, tipo | matriz, string | número inteiro | O comprimento mínimo para elementos de cadeia de caracteres e matriz. O valor é inclusivo. |
minValor | param, saída, tipo | número inteiro | número inteiro | O valor mínimo para os elementos inteiros. Este valor é inclusivo. |
selado | param, tipo, saída | objeto | nenhum | Eleve o BCP089 de um aviso a um erro quando um nome de propriedade de um tipo de dados de definição de uso for provavelmente um erro de digitação. Para obter mais informações, consulte Elevar o nível de erro. |
segura | param, tipo | string, 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. Para obter mais informações, consulte Proteger cadeias de caracteres e objetos. |
Parâmetros
Use parâmetros para valores que precisam variar para implantações diferentes. Você pode definir um valor padrão para o parâmetro que é usado se nenhum valor for fornecido durante a implantação.
Por exemplo, você pode adicionar um parâmetro SKU para especificar tamanhos diferentes para um recurso. Você pode passar valores diferentes, dependendo se está 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, consulte Usar decoradores.
Para obter mais informações, consulte Parâmetros no Bicep.
Variáveis
Você pode tornar seu 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, consulte Usar decoradores.
Para obter mais informações, consulte Variáveis no Bicep.
Tipos
Você pode usar a type
instrução 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'
}
Você pode adicionar um ou mais decoradores para cada tipo de dados definido pelo usuário. Para obter mais informações, consulte Usar decoradores.
Para obter mais informações, consulte Tipos de dados definidos pelo usuário.
Funções
No seu 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 Bicep. Crie suas próprias funções quando você tiver expressões complicadas que são usadas repetidamente em seus arquivos 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 resource
palavra-chave para definir um recurso a ser implantado. Sua declaração de recurso inclui um nome simbólico para o recurso. Use esse nome simbólico em outras partes do arquivo 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 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, consulte Usar decoradores.
Para obter mais informações, consulte Declaração de recurso no Bicep.
Alguns recursos têm uma relação pai/filho. Você pode definir um recurso filho dentro do recurso pai ou fora dele.
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) que é definido dentro da conta de armazenamento. O serviço de arquivo também tem um recurso filho (compartilhamento) que é definido dentro dele.
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 um recurso filho fora do recurso pai. Você usa a propriedade pai para identificar uma relação pai/filho. São definidos os mesmos três recursos.
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, consulte Definir nome e tipo para 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ê faça referência ao módulo de outro lugar no 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, consulte Usar decoradores.
Para obter mais informações, consulte Usar módulos Bicep.
Saídas
Use 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, consulte Usar decoradores.
Para obter mais informações, consulte Saídas no Bicep.
Ciclos
Você pode adicionar loops iterativos ao seu arquivo Bicep para definir várias cópias de um:
- recurso
- módulo
- variável
- propriedade
- 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: {
}
}]
Você pode iterar sobre uma matriz, objeto ou índice inteiro.
Para obter mais informações, consulte Loops iterativos no Bicep.
Implementação condicional
Você pode adicionar um recurso ou módulo ao seu arquivo Bicep que é implantado condicionalmente. Durante a implantação, a condição é avaliada e o resultado determina se o recurso ou módulo é 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, consulte Implantação condicional no Bicep.
Whitespace
Espaços e guias são ignorados ao criar arquivos Bicep.
O bíceps é 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
Strings 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 dentro da cadeia de caracteres de várias linhas são manipulados como estão. Personagens de fuga são desnecessários. Não é possível incluir '''
na cadeia de caracteres de várias linhas. Atualmente, não há suporte para interpolação de cadeia de caracteres.
Você pode iniciar sua string logo após a abertura '''
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 no arquivo Bicep, as 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 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 várias linhas
Agora você pode usar várias linhas em declarações de função, matriz e objeto. Este recurso requer Bicep CLI versão 0.7.X ou superior.
No exemplo a seguir, a resourceGroup()
definição é dividida em várias linhas.
var foo = resourceGroup(
mySubscription,
myRgName)
Consulte Matrizes e objetos para obter exemplos de declaração 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 conjunto apiVersion para cada tipo de recurso.
- As funções definidas pelo usuário não são suportadas no momento. No entanto, um recurso experimental está atualmente acessível. Para obter mais informações, consulte Funções definidas pelo usuário no Bicep.
- Alguns recursos do Bicep exigem uma alteração correspondente na linguagem intermediária (modelos JSON do Azure Resource Manager). Anunciamos esses recursos como disponíveis quando todas as atualizações necessárias tiverem sido 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ó está disponível quando o idioma intermediário também foi atualizado nesse ambiente.
Próximos passos
Para uma introdução ao Bicep, consulte O que é Bicep?. Para tipos de dados Bicep, consulte Tipos de dados.