Planeje a estrutura do seu arquivo Bicep

Concluído

O Bicep lhe dá a flexibilidade de decidir como estruturar seu código. Nesta unidade, você aprenderá sobre as maneiras de estruturar seu código Bicep e a importância de um estilo consistente e código Bicep claro e compreensível.

Que ordem deve seguir o seu código Bicep?

Seus modelos Bicep podem conter muitos elementos, incluindo parâmetros, variáveis, recursos, módulos, saídas e um targetScope para todo o modelo. O Bíceps não impõe uma ordem para que seus elementos sejam seguidos. No entanto, é importante considerar a ordem dos elementos para garantir que o modelo seja claro e compreensível.

Há duas abordagens principais para ordenar seu código:

• Agrupar elementos por tipo de elemento
• Agrupar elementos por recurso

Você e sua equipe devem concordar com um e usá-lo de forma consistente.

Agrupar elementos por tipo de elemento

Você pode agrupar todos os elementos do mesmo tipo. Todos os seus parâmetros iriam em um só lugar, geralmente na parte superior do arquivo. As variáveis vêm em seguida, seguidas por recursos e módulos, e as saídas estão na parte inferior. Por exemplo, você pode ter um arquivo Bicep que implanta um banco de dados SQL do Azure e uma conta de armazenamento.

Quando você agrupa seus elementos por tipo, eles podem ter esta aparência:

Gorjeta

Se você seguir esta convenção, considere colocar o targetScope no topo do arquivo.

Essa ordenação faz sentido quando você está acostumado com outras infraestruturas como linguagens de código (por exemplo, o idioma nos modelos do Azure Resource Manager). Ele também pode tornar seu modelo fácil de entender, porque é claro onde procurar tipos específicos de elementos. Em modelos mais longos, porém, pode ser difícil navegar e saltar entre os elementos.

Você ainda tem que decidir como ordenar os elementos dentro dessas categorias. É uma boa ideia agrupar parâmetros relacionados. Por exemplo, todos os parâmetros que são sobre uma conta de armazenamento pertencem juntos e, dentro disso, os parâmetros SKU da conta de armazenamento pertencem juntos.

Da mesma forma, você pode agrupar recursos relacionados. Isso ajuda qualquer pessoa que use seu modelo a navegar rapidamente nele e a entender as partes importantes do modelo.

Às vezes, você cria um modelo que implanta um recurso primário com vários recursos de suporte secundários. Por exemplo, você pode criar um modelo para implantar um site hospedado no Serviço de Aplicativo do Azure. O recurso principal é o aplicativo do Serviço de Aplicativo. Os recursos secundários no mesmo modelo podem incluir o plano do Serviço de Aplicativo, a conta de armazenamento, a instância do Application Insights e outros. Quando você tem um modelo como este, é uma boa ideia colocar o recurso ou recursos primários na parte superior da seção de recursos do modelo, para que qualquer pessoa que abra o modelo possa identificar rapidamente a finalidade do modelo e possa encontrar os recursos importantes.

Agrupar elementos por recurso

Como alternativa, você pode agrupar seus elementos com base no tipo de recursos que está implantando. Continuando o exemplo anterior, você pode agrupar todos os parâmetros, variáveis, recursos e saídas relacionados aos recursos do banco de dados SQL do Azure. Em seguida, você pode adicionar os parâmetros, variáveis, recursos e saídas para a conta de armazenamento, conforme mostrado aqui:

O agrupamento por recurso pode facilitar a leitura do modelo, porque todos os elementos necessários para um recurso específico estão em um só lugar. No entanto, torna mais difícil verificar rapidamente como tipos específicos de elementos são declarados quando, por exemplo, você deseja revisar todos os parâmetros.

Você também precisa considerar como lidar com parâmetros e variáveis que são comuns a vários recursos, como um environmentType parâmetro quando você usa um mapa de configuração. Parâmetros e variáveis comuns devem ser colocados juntos, geralmente na parte superior do arquivo Bicep.

Gorjeta

Considere se pode fazer mais sentido criar módulos para grupos de recursos relacionados e, em seguida, usar um modelo mais simples para combinar os módulos. Cobrimos os módulos do Bicep com mais detalhes ao longo dos caminhos de aprendizagem do Bicep.

Como o espaço em branco pode ajudar a criar estrutura?

Linhas em branco, ou espaço em branco, podem ajudá-lo a adicionar estrutura visual ao seu modelo. Usando o espaço em branco cuidadosamente, você pode agrupar as seções do seu código Bicep logicamente, o que, por sua vez, pode ajudar a esclarecer as relações entre os recursos. Para fazer isso, considere adicionar uma linha em branco entre as seções principais, independentemente do estilo de agrupamento de sua preferência.

Como você define vários recursos semelhantes?

Com o Bicep, você pode usar loops para implantar recursos semelhantes a partir de uma única definição. Usando a for palavra-chave para definir loops de recursos, você pode tornar seu código Bicep mais limpo e reduzir a duplicação desnecessária de definições de recursos. No futuro, quando você precisar alterar a definição de seus recursos, basta atualizar um lugar. Por padrão, quando o Azure Resource Manager implanta seus recursos, ele implanta todos os recursos no loop ao mesmo tempo, para que sua implantação seja o mais eficiente possível.

Procure locais onde você define vários recursos que são idênticos ou que têm poucas diferenças em suas propriedades. Em seguida, adicione uma variável para listar os recursos a serem criados, juntamente com as propriedades que diferem dos outros recursos. O exemplo a seguir usa um loop para definir um conjunto de contêineres do Azure Cosmos DB, cada um dos quais tem seu próprio nome e chave de partição:

var cosmosDBContainerDefinitions = [
  {
    name: 'customers'
    partitionKey: '/customerId'
  }
  {
    name: 'orders'
    partitionKey: '/orderId'
  }
  {
    name: 'products'
    partitionKey: '/productId'
  }
]

resource cosmosDBContainers 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers@2024-05-15' = [for cosmosDBContainerDefinition in cosmosDBContainerDefinitions: {
  parent: cosmosDBDatabase
  name: cosmosDBContainerDefinition.name
  properties: {
    resource: {
      id: cosmosDBContainerDefinition.name
      partitionKey: {
        kind: 'Hash'
        paths: [
          cosmosDBContainerDefinition.partitionKey
        ]
      }
    }
    options: {}
  }
}]

Como você implanta recursos apenas em determinados ambientes?

Às vezes, você define recursos que devem ser implantados apenas em ambientes específicos ou sob determinadas condições. Usando a palavra-chave if , você pode implantar seletivamente recursos com base em um valor de parâmetro, uma variável de mapa de configuração ou outra condição. O exemplo a seguir usa um mapa de configuração para implantar recursos de log para ambientes de produção, mas não para ambientes de teste:

var environmentConfigurationMap = {
  Production: {
    enableLogging: true
  }
  Test: {
    enableLogging: false
  }
}

resource logAnalyticsWorkspace 'Microsoft.OperationalInsights/workspaces@2023-09-01' = if (environmentConfigurationMap[environmentType].enableLogging) {
  name: logAnalyticsWorkspaceName
  location: location
}

resource cosmosDBAccountDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = if (environmentConfigurationMap[environmentType].enableLogging) {
  scope: cosmosDBAccount
  name: cosmosDBAccountDiagnosticSettingsName
  properties: {
    workspaceId: logAnalyticsWorkspace.id
    // ...
  }
}

Como você expressa as dependências entre seus recursos?

Em qualquer modelo complexo do Bíceps, você precisa expressar dependências entre seus recursos. Quando o Bicep entende as dependências entre seus recursos, ele as implanta na ordem correta.

O Bicep permite especificar explicitamente uma dependência usando a dependsOn propriedade. No entanto, na maioria dos casos, é possível permitir que o Bicep detete automaticamente dependências. Quando você usa o nome simbólico de um recurso dentro de uma propriedade de outro, o Bicep deteta a relação. É melhor deixar o Bicep gerenciá-los sempre que puder. Dessa forma, quando você alterar seu modelo, o Bicep garantirá que as dependências estejam sempre corretas e você não adicionará código desnecessário que torna seu modelo mais complicado e difícil de ler.

Como você expressa as relações entre pais e filhos?

O Azure Resource Manager e o Bicep têm o conceito de recursos filho, o que só faz sentido quando são implantados no contexto do pai. Por exemplo, um banco de dados SQL do Azure é filho de uma instância do SQL Server. Há várias maneiras de definir recursos filho, mas, na maioria dos casos, é uma boa ideia usar a parent propriedade. Isso ajuda o Bicep a entender a relação para que possa fornecer validação no Visual Studio Code e deixa a relação clara para qualquer outra pessoa que leia o modelo.

Como definir as propriedades do recurso?

Você precisa especificar os valores para as propriedades do recurso em seus arquivos Bicep. É uma boa ideia ser cuidadoso quando você codifica valores em suas definições de recursos. Se você sabe que os valores não serão alterados, codificá-los pode ser melhor do que usar outro parâmetro que torna seu modelo mais difícil de testar e trabalhar. No entanto, se os valores mudarem, considere defini-los como parâmetros ou variáveis para tornar seu código Bicep mais dinâmico e reutilizável.

Quando você faz valores de código rígido, é bom garantir que eles sejam compreensíveis para os outros. Por exemplo, se uma propriedade tiver que ser definida como um valor específico para que o recurso se comporte corretamente para sua solução, considere criar uma variável bem nomeada que forneça uma explicação e, em seguida, atribuir o valor usando a variável. Para situações em que um nome de variável não conta toda a história, considere adicionar um comentário. Você aprenderá mais sobre comentários mais adiante neste módulo.

Para algumas propriedades de recurso, para construir valores automaticamente, você precisa criar expressões complexas que incluam funções e interpolação de cadeia de caracteres. Seu código Bicep geralmente é mais claro quando você declara variáveis e faz referência a elas nos blocos de código de recurso.

Gorjeta

Ao criar saídas, tente usar propriedades de recursos sempre que puder. Evite incorporar suas próprias suposições sobre como os recursos funcionam, porque essas suposições podem mudar ao longo do tempo.

Por exemplo, se você precisar gerar a URL de um aplicativo do Serviço de Aplicativo, evite construir uma URL:

output hostname string = '${app.name}.azurewebsites.net'

A abordagem anterior será interrompida se o Serviço de Aplicativo alterar a maneira como eles atribuem nomes de host a aplicativos ou se você implantar em ambientes do Azure que usam URLs diferentes.

Em vez disso, use a defaultHostname propriedade do recurso do aplicativo:

output hostname string = app.properties.defaultHostname

Como você usa o controle de versão de forma eficaz?

Sistemas de controle de versão, como o Git, podem ajudar a simplificar seu trabalho quando você está refatoração de código.

Como os sistemas de controle de versão são projetados para acompanhar as alterações em seus arquivos, você pode usá-los para retornar facilmente a uma versão mais antiga do seu código se cometer um erro. É uma boa ideia dedicar seu trabalho com frequência para que você possa voltar ao ponto exato no tempo que você precisa.

O controle de versão também ajuda você a remover o código antigo de seus arquivos Bicep. E se o seu código Bicep incluir uma definição de recurso de que você não precisa mais? Você pode precisar da definição novamente no futuro, e é tentador simplesmente comentá-la e mantê-la no arquivo. Mas, na verdade, mantê-lo lá apenas bagunça seu arquivo Bicep, tornando difícil para os outros entenderem por que os recursos comentados ainda estão lá.

Outra consideração é que é possível que alguém acidentalmente descomente a definição, com resultados imprevisíveis ou potencialmente adversos. Quando você usa um sistema de controle de versão, você pode simplesmente remover a definição de recurso antiga. Se você precisar da definição novamente no futuro, poderá recuperá-la do histórico de arquivos.