Fornecer valores usando arquivos de parâmetro

  • 4 minutos

Nas unidades anteriores, você forneceu os valores de parâmetro na linha de comando quando criou uma implantação. Essa abordagem funciona bem quando você está escrevendo e testando seus arquivos Bicep, mas não funciona bem quando você tem muitos parâmetros ou quando precisa automatizar suas implantações. Nesta unidade, você aprenderá sobre diferentes maneiras pelas quais os valores dos parâmetros podem ser especificados.

Nota

Os comandos nesta unidade são mostrados para ilustrar conceitos. Não execute os comandos ainda. Você vai praticar o que você aprende aqui em breve.

Criar arquivos de parâmetros

Os arquivos de parâmetros facilitam a especificação de valores de parâmetros juntos como um conjunto. Dentro do arquivo de parâmetros, você fornece valores para os parâmetros em seu arquivo Bicep. Os arquivos de parâmetro são criados usando a linguagem JSON (JavaScript Object Notation). Você pode fornecer um arquivo de parâmetro ao implantar seu modelo Bicep. Veja a aparência de um arquivo de parâmetro:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "appServicePlanInstanceCount": {
      "value": 3
    },
    "appServicePlanSku": {
      "value": {
        "name": "P1v3",
        "tier": "PremiumV3"
      }
    },
    "cosmosDBAccountLocations": {
      "value": [
        {
          "locationName": "australiaeast"
        },
        {
          "locationName": "southcentralus"
        },
        {
          "locationName": "westeurope"
        }
      ]
    }
  }
}

Vamos examinar cada parte do arquivo de parâmetros com mais detalhes:

  • $schema ajuda o Azure Resource Manager a entender que esse arquivo é um arquivo de parâmetro.
  • contentVersion é uma propriedade que você pode usar para acompanhar alterações significativas em seu arquivo de parâmetros, se desejar. Normalmente, ele é definido como seu valor padrão de 1.0.0.0.
  • A parameters seção lista cada parâmetro e o valor que você deseja usar. O valor do parâmetro deve ser especificado como um objeto. O objeto tem uma propriedade chamada value que define o valor real do parâmetro a ser usado.

Geralmente, você criará um arquivo de parâmetros para cada ambiente. É uma boa prática incluir o nome do ambiente no nome do arquivo de parâmetro. Por exemplo, você pode ter um arquivo de parâmetro chamado main.parameters.dev.json para seu ambiente de desenvolvimento e um chamado main.parameters.production.json para seu ambiente de produção.

Nota

Certifique-se de especificar apenas valores para parâmetros que existem no seu modelo Bicep. Quando você cria uma implantação, o Azure verifica seus parâmetros e fornece um erro se você tentou especificar um valor para um parâmetro que não está no arquivo Bicep.

Usar arquivos de parâmetros no momento da implantação

Ao criar uma nova implantação usando o comando, você pode especificar o nome do arquivo de parâmetro que deseja usar com o az deployment group create --parameters argumento:

az deployment group create \
  --template-file main.bicep \
  --parameters main.parameters.json

Ao criar uma nova implantação usando o cmdlet, você pode especificar o nome do arquivo de parâmetro que deseja usar com o New-AzResourceGroupDeployment -TemplateParameterFile argumento:

New-AzResourceGroupDeployment `
  -TemplateFile main.bicep `
  -TemplateParameterFile main.parameters.json

Substituir valores de parâmetros

Agora você aprendeu sobre três maneiras de especificar valores de parâmetro: valores padrão, a linha de comando e arquivos de parâmetro. É comum usar abordagens diferentes para especificar valores diferentes para o mesmo parâmetro. Você já viu essa abordagem quando trabalhou com valores padrão. Quando você cria um valor padrão para um parâmetro, mas depois especifica um valor diferente usando a linha de comando, o valor da linha de comando tem precedência. Vejamos como os arquivos de parâmetros se encaixam nessa ordem de precedência.

Diagram that shows the order of precedence for parameter values. Parameter files override default values, and command-line parameter values override parameter files.

Você pode ver que os arquivos de parâmetro substituem os valores padrão e os valores de parâmetro de linha de comando substituem os arquivos de parâmetro.

Vamos ver como funciona essa abordagem. Aqui está um exemplo de arquivo Bicep que define três parâmetros, cada um com valores padrão:

param location string = resourceGroup().location
param appServicePlanInstanceCount int = 1
param appServicePlanSku object = {
  name: 'F1'
  tier: 'Free'
}

Vamos examinar um arquivo de parâmetro que substitui o valor de dois dos parâmetros, mas não especifica um valor para o location parâmetro:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "appServicePlanInstanceCount": {
      "value": 3
    },
    "appServicePlanSku": {
      "value": {
        "name": "P1v3",
        "tier": "PremiumV3"
      }
    }
  }
}

Quando você cria a implantação, também substituímos o valor de appServicePlanInstanceCount. Como nos arquivos de parâmetro, você usa o argumento, mas adiciona o --parameters valor que deseja substituir como seu próprio valor:

az deployment group create \
  --template-file main.bicep \
  --parameters main.parameters.json \
               appServicePlanInstanceCount=5

Ao criar a implantação, você substitui um dos valores de parâmetro. Você especifica o nome do parâmetro como se fosse um argumento para o cmdlet:

New-AzResourceGroupDeployment `
  -TemplateFile main.bicep `
  -TemplateParameterFile main.parameters.json `
  -appServicePlanInstanceCount 5

Vejamos quais serão os valores.

Parâmetro Valor Explicação
location A localização do grupo de recursos. O arquivo Bicep especifica esse parâmetro como um valor padrão e não é substituído.
appServicePlanSku Um objeto com uma name propriedade definida como P1v3 e a tier de PremiumV3. O valor padrão no arquivo Bicep é substituído pelo arquivo de parâmetro.
appServicePlanInstanceCount 5 O valor especificado no momento da implantação substitui o valor padrão e o valor no arquivo de parâmetro.

Usando uma mistura de abordagens para especificar valores de parâmetro, você pode evitar ter que duplicar valores de parâmetro em muitos lugares, enquanto ainda obtém a flexibilidade para substituir onde você precisa.