Compreender a estrutura e a sintaxe dos ficheiros Bicep

  • 5 minutos

O Azure Bicep vem com sua própria sintaxe. No entanto, é fácil de entender e seguir. Não vamos nos aprofundar na sintaxe e na estrutura, mas vamos analisar os principais conceitos usando um exemplo.

Exemplo de arquivo Bicep

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

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

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

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

output storageEndpoint object = stg.properties.primaryEndpoints

Âmbito de aplicação

O escopo define a assinatura ou o nível de gerenciamento no qual você está implantando. Você pode escolher entre um subscription, resourceGroup, managementGroup, e tenant. No arquivo de exemplo, o escopo de destino é um grupo de recursos, que é o escopo de implantação padrão.

Âmbitos disponíveis:

  • Grupo de recursos: Escopo padrão para a maioria das implantações.
  • Subscrição: Para recursos que precisam de acesso em nível de assinatura.
  • Grupo de gestão: Para implantações em escala empresarial.
  • Locatário: Para configurações de todo o locatário.

Parâmetros

Os parâmetros são usados para tornar os modelos mais reutilizáveis, fornecendo valores durante a implantação. Se consultar o ficheiro de exemplo, encontrará storagePrefix, storageSKU e location, todos os quais são usados mais tarde no ficheiro.

Os parâmetros podem ter valores padrão para simplificar o processo. No arquivo de exemplo, o location padrão é o local do grupo de recursos de destino.

Decoradores

Além dos valores padrão, os decoradores são usados para fornecer controle extra sobre o uso dos parâmetros. Um exemplo é o allowed decorador, que restringe o fornecimento de certos valores. Bicep também suporta outros decoradores comuns, como maxLength, minLength, maxValue, e minValue.

Decoradores comuns:

  • @allowed: Restringe valores a uma lista específica.
  • **@minLength / @maxLength:** Impõe restrições de comprimento de cadeia de caracteres.
  • **@minValue / @maxValue:** Impõe restrições de intervalo numérico.
  • @description: Documenta a finalidade do parâmetro.
  • @secure: Marca valores confidenciais como senhas.

Variáveis

Como qualquer outra linguagem de programação, as variáveis também são suportadas no Bicep. Eles fornecem pares nome-valor simples com escopos globais, o que significa que eles podem ser acessados em qualquer lugar no arquivo Bicep .

As variáveis ajudam:

  • Evite a repetição em modelos.
  • Calcule valores com base em parâmetros.
  • Melhore a legibilidade do modelo.

Recursos

Agora vem a parte essencial do modelo: o recurso. É aqui que você define os recursos do Azure a serem implantados ou modificados como parte do processo de implantação. No arquivo de exemplo, o bloco de recursos implanta uma conta de armazenamento com serviços de arquivo e um compartilhamento de arquivos como recursos subordinados.

Relações entre pais e filhos

Com os recursos filho sendo exibidos de forma diferente dos modelos JSON , torna-se mais fácil entender as relações pai-filho nos grupos de recursos e na implantação. No modelo de exemplo, você pode ver que o serviço de arquivo e o compartilhamento de arquivos são definidos como filhos da conta de armazenamento, criando uma hierarquia clara.

Sintaxe do recurso filho:

resource parent 'Microsoft.Provider/type@version' = {
  name: 'parentName'

  resource child 'childType' = {
    name: 'childName'
  }
}

Implementação condicional

Definir recursos com Bicep também permite condições. Você pode implantar recursos condicionalmente com base em valores de parâmetros ou outras condições.

Sintaxe condicional:

resource conditionalResource 'type@version' = if (condition) {
  // resource definition
}

Módulos

Para melhorar a reutilização e a capacidade de gestão do código, pode-se referir-se a outro modelo Bicep como um módulo. Assim como qualquer outro recurso, você pode adicionar uma condição a um módulo, que será avaliado como verdadeiro antes de implantá-lo.

Observação

Os módulos permitem que você reutilize o código de um arquivo Bicep em outros arquivos Bicep . Um módulo é um arquivo Bicep que é implantado a partir de outro arquivo Bicep .

Sintaxe do módulo:

module moduleName 'path/to/module.bicep' = {
  name: 'deploymentName'
  params: {
    parameterName: parameterValue
  }
}

Benefícios dos módulos:

  • Reutilização de código em vários modelos.
  • Manutenção e atualizações simplificadas.
  • Separação lógica dos componentes da infraestrutura.
  • Testes e validação mais fáceis.

Saídas

As saídas são usadas para retornar valores de uma implantação, como nomes de host ou endereços IP. Eles serão retornados assim que uma implantação for concluída.

Sintaxe de saída:

output outputName string = resourceName.properties.hostname

Utilizações comuns para saídas:

  • Retornar cadeias de conexão.
  • Recupere IDs de recursos para uso em outras implantações.
  • Obtenha valores atribuídos dinamicamente, como endereços IP.
  • Passe valores para estágios de implantação subsequentes.

Utilização dos módulos na prática

Se você quiser modelos verdadeiramente reutilizáveis, não pode evitar o uso de um módulo. Os módulos permitem que você reutilize um arquivo Bicep em outros arquivos Bicep . Em um módulo, você define o que precisa implantar e os parâmetros necessários. Quando você o reutiliza em outro arquivo, tudo o que você precisa fazer é referenciar o arquivo e fornecer os parâmetros. O resto é cuidado pelo Azure Bicep.

No arquivo de exemplo, você está usando um módulo que presumivelmente está implantando um aplicativo Web (webModule). O módulo faz referência ./webApp.bicep e passa parâmetros como skuName e location.

Para mais informações, consulte Utilização de módulos no Bicep.

Trabalhar com resultados

Você pode usar saídas para passar valores de sua implantação para o mundo exterior, seja dentro de um pipeline de CI/CD ou em um terminal local ou Cloud Shell. Isso permite que você acesse valores como pontos de extremidade de armazenamento ou URLs de aplicativos após a conclusão da implantação.

Tudo o que precisa é da palavra-chave output e da propriedade a que gostaria de aceder:

output storageEndpoint object = stg.properties.primaryEndpoints

No arquivo de exemplo, a saída retorna os pontos de extremidade primários da conta de armazenamento implantada, que inclui pontos de extremidade de blob, arquivo, fila e tabela.

Para obter mais informações, veja Saídas em Bicep.

Outras características

Existem muitos outros recursos disponíveis dentro de um arquivo Bicep , tais como:

  • Loops: Itere sobre matrizes para criar vários recursos.
  • Implantação condicional: Implante recursos com base em condições.
  • Strings de várias linhas: Defina cadeias de caracteres longas em várias linhas.
  • Recursos existentes: Faça referência aos recursos existentes do Azure .
  • Funções: Qualquer função válida dentro de um modelo ARM também é válida dentro de um arquivo Bicep .

Próximos passos

Na próxima unidade, você aprenderá como implantar arquivos Bicep usando o Azure Pipelines.