Documente seu código adicionando comentários e metadados

  • 4 minutos

Um bom código Bicep é auto-documentável. Isso significa que ele usa nomenclatura clara e uma boa estrutura para que, quando os colegas lerem seu código, eles possam entender rapidamente o que está acontecendo. Se precisarem fazer alterações, podem ter certeza de que estão modificando os lugares certos.

Em algumas situações, no entanto, você pode precisar esclarecer determinado código adicionando documentação extra aos seus arquivos Bicep. Além disso, depois que seu modelo for implantado e os recursos tiverem sido criados no Azure, é importante que qualquer pessoa que examine seu ambiente do Azure entenda o que é cada recurso e para que serve.

Nesta unidade, você aprenderá como adicionar comentários aos seus arquivos Bicep e como usar tags de recursos para adicionar metadados aos seus recursos do Azure. Esta documentação adicional fornece aos seus colegas informações sobre o que o seu código faz, a lógica que utilizou para escrever o código e a finalidade dos seus recursos do Azure.

Adicionar comentários ao seu código

O Bicep permite que você adicione comentários ao seu código. Os comentários são textos legíveis por humanos que documentam seu código, mas são ignorados quando o arquivo é implantado no Azure.

O Bicep suporta dois tipos de comentários:

  • Os comentários de linha única começam com uma sequência de caracteres de barra dupla (//) e continuam até o final da linha, conforme mostrado aqui:

    // We need to define a firewall rule to allow Azure services to access the database.

resource firewallRule 'Microsoft.Sql/servers/firewallRules@2023-08-01-preview' = {
  parent: sqlServer
  name: 'AllowAllAzureIPs'
  properties: {
    startIpAddress: '0.0.0.0' // This combination represents 'all Azure IP addresses'.
    endIpAddress: '0.0.0.0'
  }
}

  • Os comentários de várias linhas usam as /* sequências de caracteres e */ para cercar o comentário e podem abranger várias linhas, conforme mostrado aqui:

    /*
  This Bicep file was developed by the web team.
  It deploys the resources we need for our toy company's website.
*/

Gorjeta

Evite usar comentários para partes óbvias e claras do seu código. Ter muitos comentários realmente reduz a legibilidade do seu código. Além disso, é fácil esquecer de atualizar os comentários quando o código for alterado no futuro. Concentre-se em documentar lógicas únicas e expressões complexas.

Você também pode usar comentários do Bíceps para adicionar um bloco estruturado de várias linhas no início de cada arquivo. Pense nisso como um manifesto. Sua equipe pode decidir que cada modelo e módulo deve ter um manifesto que descreva a finalidade do modelo e o que ele contém, como neste exemplo:

/*
  SYNOPSIS: Module for provisioning Azure SQL server and database.
  DESCRIPTION: This module provisions an Azure SQL server and a database, and configures the server to accept connections from within Azure.
  VERSION: 1.0.0
  OWNER TEAM: Website
*/

Adicionar comentários a arquivos de parâmetros

Os arquivos de parâmetro permitem que você crie um arquivo JSON para especificar um conjunto de valores de parâmetro para sua implantação. Os valores dos parâmetros precisam corresponder aos parâmetros declarados no modelo Bicep.

Os valores especificados em arquivos de parâmetros também geralmente se beneficiam de serem documentados. É uma boa prática adicionar comentários a arquivos de parâmetros quando você trabalha com valores de parâmetros que podem não estar imediatamente claros para alguém que lê o arquivo.

Por exemplo, o modelo Bicep do seu site pode incluir um parâmetro para o URL para acessar a API de estoque de produtos da sua empresa para que seu site possa exibir se seus brinquedos estão em estoque no seu armazém. As URLs para acessar a API de estoque para cada ambiente não são fáceis de entender, por isso são um bom candidato para um comentário:

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
      "productStockCheckApiUrl": {
        "value": "https://x73.mytoycompany.com/e4/j7" // This is the URL to the product stock API in the development environment.
      }
    }
  }

Gorjeta

Quando você trabalha com arquivos de parâmetro e outros arquivos JSON que incluem comentários, você geralmente precisa usar a extensão de arquivo .jsonc em vez de .json. Isso ajuda o Visual Studio Code e outras ferramentas a entender que os comentários são permitidos.

Adicionar descrições a parâmetros, variáveis e saídas

Ao criar um parâmetro, variável ou saída, você pode aplicar o @description() decorador para ajudar a explicar sua finalidade:

@description('The Azure region into which the resources should be deployed.')
param location string = resourceGroup().location

@description('Indicates whether the web application firewall policy should be enabled.')
var enableWafPolicy = (environmentType == 'prod')

@description('The default host name of the App Service app.')
output hostName string = app.properties.defaultHostName

As descrições são mais poderosas do que os comentários porque, quando alguém usa a extensão Visual Studio Code para Bicep, as descrições são mostradas sempre que alguém passa o mouse sobre um nome simbólico. Além disso, quando alguém usa seu arquivo Bicep como um módulo, verá as descrições que você aplica aos seus parâmetros.

Adicionar descrições aos recursos

Também pode ser útil adicionar descrições aos recursos que você definir. Você também pode aplicar o @description() decorador aos recursos.

Além disso, alguns recursos suportam a adição de descrições ou outras informações legíveis por humanos no próprio recurso. Por exemplo, muitos recursos da Política do Azure e atribuições de função RBAC (controle de acesso baseado em função) do Azure incluem uma propriedade description, como esta:

resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  scope: storageAccount
  name: guid(roleDefinitionId, resourceGroup().id)
  properties: {
    principalType: 'ServicePrincipal'
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionId)
    principalId: principalId
    description: 'Contributor access on the storage account is required to enable the application to create blob containers and upload blobs.'
  }
}

É uma boa ideia usar essa propriedade para explicar por que você criou cada atribuição de função. A descrição é implantada no Azure com o recurso, portanto, qualquer pessoa que audite a configuração RBAC do seu ambiente do Azure entenderá imediatamente a finalidade da atribuição de função.

Aplicar tags de recursos

Os comentários no arquivo Bicep não aparecem em nenhum lugar nos recursos implantados. Eles estão lá apenas para ajudá-lo a documentar seus arquivos Bicep. No entanto, há muitas situações em que você precisa controlar informações sobre seus recursos implantados do Azure, incluindo:

  • Alocar seus custos do Azure para centros de custo específicos.
  • Compreender como os dados contidos em bancos de dados e contas de armazenamento devem ser classificados e protegidos.
  • Registar o nome da equipa ou pessoa responsável pela gestão do recurso.
  • Controlar o nome do ambiente ao qual o recurso se relaciona, como produção ou desenvolvimento.

As tags de recursos permitem armazenar metadados importantes sobre recursos. Você define marcas de recurso em seu código Bicep e o Azure armazena as informações com o recurso quando ele é implantado:

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = {
  name: storageAccountName
  location: location
  tags: {
    CostCenter: 'Marketing'
    DataClassification: 'Public'
    Owner: 'WebsiteTeam'
    Environment: 'Production'
  }
  sku: {
    name: storageAccountSkuName
  }
  kind: 'StorageV2'
  properties: {
    accessTier: 'Hot'
  }
}

Você pode consultar as tags de um recurso usando ferramentas como o Azure PowerShell e a CLI do Azure e pode ver as tags no portal do Azure:

Captura de ecrã do portal do Azure para uma conta de armazenamento, mostrando a localização das etiquetas.

É comum usar o mesmo conjunto de tags para todos os seus recursos, por isso, geralmente é uma boa ideia definir suas tags como parâmetros ou variáveis e, em seguida, reutilizá-las em cada recurso:

param tags object = {
  CostCenter: 'Marketing'
  DataClassification: 'Public'
  Owner: 'WebsiteTeam'
  Environment: 'Production'
}

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = {
  tags: tags
}

resource appServiceApp 'Microsoft.Web/sites@2023-12-01' = {
  tags: tags
}