Entender os parâmetros

  • 8 minutos

Com os parâmetros, você pode fornecer informações para um modelo Bicep no momento da implantação. É possível tornar um modelo Bicep flexível e reutilizável declarando os parâmetros no seu modelo.

Os decoradores fornecem uma maneira de anexar restrições e metadados a um parâmetro, o que ajuda qualquer pessoa que use os modelos a entender quais informações precisam fornecer.

Nesta unidade, você aprenderá sobre parâmetros e decoradores.

Declarar um parâmetro

Em um modelo Bicep, você declara um parâmetro usando a palavra-chave param. É possível colocar essas declarações em qualquer lugar no arquivo de modelo, embora geralmente seja uma boa ideia colocá-las na parte superior do arquivo para facilitar a leitura do código Bicep.

Veja como declarar um parâmetro:

param environmentName string

Vamos ver como cada parte funciona:

  • param indica ao Bicep que você está declarando um parâmetro.

  • environmentName refere-se ao nome do parâmetro. Embora o nome do parâmetro possa ser qualquer um, é possível deixar o nome claro e compreensível para os usuários do modelo. No mesmo modelo, também é possível consultar o parâmetro usando seu nome. Os nomes de parâmetros devem ser exclusivos. Eles não podem ter o mesmo nome que uma variável ou um recurso no mesmo arquivo Bicep.

    Dica

    Usar convenções de nomenclatura de práticas recomendadas para declarações de parâmetro. Nomes adequados facilitam a leitura e a compreensão dos modelos. Verifique se você está usando nomes descritivos e claros e seja consistente em sua estratégia de nomenclatura.

  • string refere-se ao tipo do parâmetro.

    Dica

    Pense cuidadosamente nos parâmetros usados pelo seu modelo. Tente usar parâmetros para configurações que mudam entre implantações. Variáveis e valores em código podem ser usados em configurações que não mudam entre implantações.

Adicionar um valor padrão

Você pode atribuir valores padrão aos parâmetros em seus modelos. Ao atribuir um valor padrão, você está tornando o parâmetro opcional. Se o modelo for implantado sem um valor especificado para o parâmetro, o valor padrão será atribuído.

Confira como adicionar um valor padrão:

param environmentName string = 'dev'

O parâmetro environmentName é atribuído ao valor padrão de dev.

Você pode usar expressões como valores padrão. Aqui está um exemplo de um parâmetro de cadeia de caracteres chamado location com um valor padrão definido para a localização do grupo de recursos atual:

param location string = resourceGroup().location

Dica

Cuidado com os valores padrão que você utiliza. Garanta que será seguro para qualquer pessoa implantar o arquivo Bicep com os valores padrão. Por exemplo, considere o uso de SKUs e tipos de preços baratos para que a pessoa que implantar o modelo em um ambiente de teste não incorra em um custo grande de forma desnecessária.

Entender os tipos de parâmetros

Ao declarar um parâmetro, você precisa dizer ao Bicep quais tipos de informações o parâmetro conterá. O Bicep garantirá que o valor atribuído ao parâmetro seja compatível com o tipo de parâmetro.

Os parâmetros no Bicep podem ser um dos seguintes tipos:

  • string, que permite inserir texto arbitrário.
  • int, que permite inserir um número.
  • bool, que representa um valor booliano (verdadeiro ou falso).
  • object e array, que representam listas e dados estruturados.

Objetos

Você pode usar parâmetros de objeto para combinar dados estruturados juntos em um só lugar. Um objeto pode ter várias propriedades de tipos diferentes. É possível usar objetos em definições de recursos, em variáveis ou em expressões no arquivo Bicep. Aqui está um exemplo de um objeto:

param appServicePlanSku object = {
  name: 'F1'
  tier: 'Free'
  capacity: 1
}

Esse parâmetro é um objeto com duas propriedades de cadeia de caracteres, name e tier, e uma propriedade de inteiro, capacity. Observe que cada uma das propriedades está em sua própria linha.

Ao fazer referência ao parâmetro no modelo, você pode selecionar as propriedades individuais do objeto usando um ponto seguido pelo nome da propriedade, como neste exemplo:

resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
  name: appServicePlanName
  location: location
  sku: {
    name: appServicePlanSku.name
    tier: appServicePlanSku.tier
    capacity: appServicePlanSku.capacity
  }
}

Importante

Lembre-se que você não especifica o tipo de cada propriedade dentro de um objeto. No entanto, ao usar o valor de uma propriedade, seu tipo deve corresponder ao esperado. No exemplo anterior, o nome e a camada da SKU do Plano do Serviço de Aplicativo devem ser cadeias de caracteres.

Outro exemplo de utilização de um parâmetro de objeto é ao especificar marcas de recursos. Você pode anexar metadados de marca personalizada aos recursos implantados, que podem ser usados para identificar informações importantes sobre um recurso.

As marcas são úteis para cenários como acompanhar qual equipe possui um recurso ou quando um recurso pertence a um ambiente de produção ou não. Normalmente você usará marcas diferentes para cada ambiente, mas precisará reutilizar os mesmos valores de marca em todos os recursos no modelo. Por esse motivo, as marcas de recursos são um bom uso para um parâmetro de objeto, como neste exemplo:

param resourceTags object = {
  EnvironmentName: 'Test'
  CostCenter: '1000100'
  Team: 'Human Resources'
}

Sempre que você definir um recurso no arquivo Bicep, poderá reutilizá-lo sempre que definir a propriedade tags:

resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
  name: appServicePlanName
  location: location
  tags: resourceTags
  sku: {
    name: 'S1'
  }
}

resource appServiceApp 'Microsoft.Web/sites@' = {
  name: appServiceAppName
  location: location
  tags: resourceTags
  kind: 'app'
  properties: {
    serverFarmId: appServicePlan.id
  }
}

Matrizes

Uma matriz é uma lista de itens. Por exemplo, você pode usar uma matriz de valores de cadeia de caracteres para declarar uma lista de endereços de email para um grupo de ação do Azure Monitor. Ou você pode usar uma matriz de objetos para representar uma lista de sub-redes para uma rede virtual.

Observação

Você não pode especificar o tipo de itens individuais que uma matriz precisa conter. Por exemplo, você não pode especificar que uma matriz deve conter cadeias de caracteres.

Vamos considerar um exemplo. O Azure Cosmos DB permite que você crie contas de banco de dados que abrangem várias regiões e trata automaticamente a replicação de dados para você. Ao implantar uma nova conta de banco de dados, é necessário especificar a lista de regiões do Azure na qual você deseja que a conta seja implantada. Muitas vezes você precisará ter uma lista diferente de locais para ambientes diferentes. Por exemplo, para economizar dinheiro em seu ambiente de teste, você pode usar apenas um ou dois locais. Mas, em seu ambiente de produção, você pode usar vários locais.

É possível criar um parâmetro de matriz que especifica uma lista de locais:

param cosmosDBAccountLocations array = [
  {
    locationName: 'australiaeast'
  }
  {
    locationName: 'southcentralus'
  }
  {
    locationName: 'westeurope'
  }
]

Dica

O exemplo anterior é uma matriz de objetos. Cada objeto tem uma propriedade locationName, que é o esperado pelo Azure Cosmos DB. Ao trabalhar com uma definição de recurso no Visual Studio Code, você pode começar inserindo as propriedades do recurso para obter o IntelliSense das ferramentas do Bicep. É possível criar alguns valores de exemplo usando essa abordagem. Quando ficar satisfeito com a configuração, mova essa seção do código do Bicep para o parâmetro. Dessa forma, você pode substituir uma propriedade embutida em código por um parâmetro que pode ser alterado durante cada implantação e, ao mesmo tempo, garantir que o recurso esteja configurado corretamente.

Agora, ao declarar o recurso do Azure Cosmos DB, você pode fazer referência ao parâmetro da matriz:

resource account 'Microsoft.DocumentDB/databaseAccounts@2022-08-15' = {
  name: accountName
  location: location
  properties: {
    locations: cosmosDBAccountLocations
  }
}

Assim é fácil usar um valor de parâmetro diferente para o ambiente de desenvolvimento, alterando o valor do parâmetro. Em breve você aprenderá como é possível fornecer valores de parâmetros diferentes sem modificar o modelo original.

Especificar uma lista de valores permitidos

Às vezes, você precisa garantir que um parâmetro tenha determinados valores. Por exemplo, sua equipe pode decidir que os Planos do Serviço de Aplicativo de produção devem ser implantados usando os SKUs Premium v3. Para impor essa regra, você pode usar o decorador de parâmetro @allowed. Um decorador de parâmetro é uma maneira de fornecer ao Bicep informações sobre qual deve ser o valor de um parâmetro. Veja como o parâmetro de cadeia de caracteres appServicePlanSkuName pode ser restringido para que apenas alguns valores específicos possam ser atribuídos:

@allowed([
  'P1v3'
  'P2v3'
  'P3v3'
])
param appServicePlanSkuName string

Dica

Use o decorador @allowed com moderação. Se você usar muito esse decorador, poderá bloquear implantações válidas se não mantiver a lista atualizada. O exemplo anterior permite apenas SKUs Premium v3 na produção. Se você precisar usar o mesmo modelo para implantar alguns ambientes de não produção mais baratos, a lista de valores permitidos poderá impedir o uso de outras SKUs que você precisa usar.

Restringir comprimento e valores do parâmetro

Ao usar parâmetros de cadeia de caracteres, geralmente é necessário limitar o comprimento da cadeia de caracteres. Vamos considerar o exemplo de nomenclatura de recursos do Azure. Todos os tipos de recursos do Azure têm limites em relação ao comprimento dos nomes. É uma boa prática especificar o comprimento mínimo e máximo de caracteres para parâmetros que controlam a nomenclatura para evitar posteriormente erros durante a implantação. Você pode usar os decoradores @minLength e @maxLength como comprimentos mínimo e máximo dos caracteres que você deseja permitir em um parâmetro.

Aqui está um exemplo que declara o parâmetro de cadeia de caracteres storageAccountName, cujo comprimento pode ficar entre 5 e 24 caracteres:

@minLength(5)
@maxLength(24)
param storageAccountName string

Esse parâmetro inclui dois decoradores. É possível aplicar vários decoradores a um parâmetro colocando cada decorador em sua própria linha.

Observação

Também é possível aplicar os decoradores @minLength e @maxLength aos parâmetros da matriz para controlar quantos itens podem estar na matriz.

Quando você trabalha com parâmetros numéricos, talvez seja necessário que os valores estejam em um intervalo específico. Por exemplo, sua empresa de brinquedos pode decidir que, sempre que alguém implantar um Plano do Serviço de Aplicativo, será obrigatório implantar pelo menos uma instância, mas não mais do que 10 instâncias do plano. Para atender aos requisitos, você pode usar os decoradores @minValue e @maxValue para especificar os valores mínimos e máximos permitidos. O exemplo a seguir declara o parâmetro inteiro appServicePlanInstanceCount, cujo valor pode estar apenas entre 1 e 10 (inclusive):

@minValue(1)
@maxValue(10)
param appServicePlanInstanceCount int

Adicionar descrições aos parâmetros

Os parâmetros são uma ótima maneira de possibilitar que seus modelos sejam reutilizados por outras pessoas. Ao usar seus modelos, elas precisarão entender o que cada parâmetro faz para que possam fornecer os valores corretos. O Bicep fornece o decorador @description para que você possa documentar a finalidade dos parâmetros de forma legível.

@description('The locations into which this Cosmos DB account should be configured. This parameter needs to be a list of objects, each of which has a locationName property.')
param cosmosDBAccountLocations array

É uma boa prática fornecer descrições para os parâmetros. Tente tornar as descrições úteis e forneça informações importantes sobre o que o modelo precisa para os valores de parâmetro.

Observação

Os modelos de Bicep às vezes podem ser disponibilizados no portal do Azure para que os usuários os implantem, da mesma forma que você usa as especificações do modelo. O portal usa as descrições e outros decoradores em parâmetros para ajudar os usuários a entenderem o que é necessário no valor de parâmetro.