Compreender os parâmetros

  • 8 minutos

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

Os decoradores fornecem uma maneira de anexar restrições e metadados a um parâmetro, o que ajuda qualquer pessoa que use seus 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 . Você pode 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 que seu código Bicep seja fácil de ler.

Veja como você declara um parâmetro:

param environmentName string

Vejamos como funciona cada parte:

  • 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 coisa, você deve deixar o nome claro e compreensível para os usuários do modelo. Dentro do mesmo modelo, você também pode fazer referência ao parâmetro usando seu nome. Os nomes dos parâmetros devem ser exclusivos. Eles não podem ter o mesmo nome que uma variável ou um recurso no mesmo arquivo Bicep.

    Gorjeta

    Use convenções de nomenclatura de práticas recomendadas para declarações de parâmetro. Boas convenções de nomenclatura tornam seus modelos fáceis de ler e entender. Certifique-se de que está a utilizar nomes claros e descritivos e adote uma estratégia de nomenclatura consistente.

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

    Gorjeta

    Pense cuidadosamente sobre os parâmetros que seu modelo usa. Tente usar parâmetros para configurações que mudam entre implantações. Variáveis e valores codificados podem ser usados para configurações que não mudam entre implantações.

Adicionar um valor padrão

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

Veja como adicionar um valor padrão:

param environmentName string = 'dev'

O parâmetro environmentName recebe um 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 nomeado location com um valor padrão definido para o local do grupo de recursos atual:

param location string = resourceGroup().location

Gorjeta

Esteja atento aos valores padrão que você usa. Certifique-se de que será seguro para alguém implantar o arquivo Bicep com os valores padrão. Por exemplo, considere o uso de níveis de preços e SKUs baratos para que alguém implantando o modelo em um ambiente de teste não incorra em um grande custo desnecessariamente.

Compreender os tipos de parâmetros

Quando você declara um parâmetro, você precisa dizer ao Bicep que tipo de informação o parâmetro conterá. O bíceps 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 lhe permite introduzir um número.
  • bool, que representa um valor booleano (verdadeiro ou falso).
  • object e array, que representam dados estruturados e listas.

Objetos

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

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

Este parâmetro é um objeto com duas propriedades name de cadeia de caracteres e , e tieruma propriedade inteira, 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 do 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 de que você não especifica o tipo de cada propriedade dentro de um objeto. No entanto, quando você usa 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 onde você pode usar um parâmetro de objeto é para especificar tags de recurso. Você pode anexar metadados de tag personalizados aos recursos implantados, que podem ser usados para identificar informações importantes sobre um recurso.

As tags são úteis para cenários como controlar qual equipe possui um recurso ou quando um recurso pertence a um ambiente de produção ou não-produção. Normalmente, você usará tags diferentes para cada ambiente, mas desejará reutilizar os mesmos valores de tag em todos os recursos do seu modelo. Por esse motivo, as tags 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 em seu arquivo Bicep, poderá reutilizá-lo onde quer que defina a tags propriedade:

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. Como 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ções do Azure Monitor. Ou você pode usar uma matriz de objetos para representar uma lista de sub-redes para uma rede virtual.

Nota

Não é possível 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 criar contas de banco de dados que abrangem várias regiões e lida automaticamente com a replicação de dados para você. Ao implantar uma nova conta de banco de dados, você precisa especificar a lista de regiões do Azure nas quais 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.

Você pode criar um parâmetro de matriz que especifica uma lista de locais:

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

Gorjeta

O exemplo anterior é uma matriz de objetos. Cada objeto tem uma locationName propriedade, que é o que o Azure Cosmos DB espera. Quando você trabalha com uma definição de recurso no Visual Studio Code, você pode começar inserindo propriedades de recurso para obter IntelliSense a partir das ferramentas Bicep. Você pode criar alguns valores de exemplo usando essa abordagem. Depois de estar satisfeito com a configuração, mova essa seção do código Bicep para o parâmetro. Dessa forma, você pode substituir uma propriedade codificada por um parâmetro que pode ser alterado durante cada implantação, garantindo ainda que o recurso esteja configurado corretamente.

Ao declarar seu recurso do Azure Cosmos DB, agora você pode fazer referência ao parâmetro de matriz:

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

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

Especificar uma lista de valores permitidos

Às vezes, você precisa se certificar de que um parâmetro tem certos valores. Por exemplo, sua equipe pode decidir que os planos do Serviço de Aplicativo de produção devem ser implantados usando as SKUs Premium v3. Para aplicar essa regra, você pode usar o decorador de @allowed parâmetros. Um decorador de parâmetros é uma forma de dar ao Bicep informações sobre qual deve ser o valor de um parâmetro. Veja como um parâmetro de cadeia de caracteres chamado appServicePlanSkuName pode ser restrito para que apenas alguns valores específicos possam ser atribuídos:

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

Gorjeta

Use o decorador @allowed com moderação. Se você usar esse decorador de forma muito ampla, poderá bloquear implantações válidas se não mantiver a lista atualizada. O exemplo anterior permite apenas SKUs Premium v3 em 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 pode impedi-lo de usar outras SKUs que você precisa usar.

Restringir o comprimento e os valores dos parâmetros

Quando você usa parâmetros de cadeia de caracteres, geralmente precisa 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 torno do comprimento de seus nomes. É uma boa prática especificar o comprimento mínimo e máximo de caracteres para parâmetros que controlam a nomenclatura, para evitar erros posteriormente durante a implantação. Você pode usar o @minLength e @maxLength decoradores para os comprimentos mínimo e máximo de caracteres que você deseja permitir para um parâmetro.

Aqui está um exemplo que declara um parâmetro de cadeia de caracteres chamado storageAccountName, cujo comprimento só pode ser entre 5 e 24 caracteres:

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

Este parâmetro inclui dois decoradores. Você pode aplicar vários decoradores a um parâmetro colocando cada decorador em sua própria linha.

Nota

Você também pode aplicar os @minLength e @maxLength decoradores aos parâmetros da matriz, para controlar quantos itens podem estar na matriz.

Quando você trabalha com parâmetros numéricos, talvez precise 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, sempre implantará pelo menos uma instância, mas não mais de 10 instâncias do plano. Para atender aos requisitos, você pode usar os @minValue decoradores e @maxValue para especificar os valores mínimos e máximos permitidos. O exemplo a seguir declara o parâmetro appServicePlanInstanceCount inteiro cujo valor só pode estar 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 tornar seus modelos reutilizáveis por outras pessoas. Quando eles usam seus modelos, eles precisarão entender o que cada parâmetro faz para que possam fornecer os valores certos. O Bicep fornece o decorador para que você possa documentar o @description propósito de seus parâmetros de uma forma legível por humanos.

@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 seus parâmetros. Tente tornar as descrições úteis e forneça informações importantes sobre o que o modelo precisa que os valores de parâmetro sejam.

Nota

Às vezes, os modelos do Bíceps podem ser disponibilizados no portal do Azure para que os usuários implantem, como quando você usa especificações de modelo. O portal usa as descrições e outros decoradores em parâmetros para ajudar os usuários a entender o que um valor de parâmetro precisa ser.