Fornecer valores usando arquivos de parâmetros

Concluído

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 do Bicep, mas não funciona bem quando tem muitos parâmetros ou quando precisa automatizar suas implantações. Nesta unidade, você aprenderá sobre diferentes maneiras pelas quais os valores de parâmetros podem ser especificados.

Observação

Os comandos nesta unidade são mostrados para ilustrar conceitos. Não execute os comandos ainda. Você praticará o que aprendeu 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. No arquivo de parâmetros, forneça valores para os parâmetros em seu arquivo Bicep. Os arquivos de parâmetros são criados usando a linguagem JSON (JavaScript Object Notation). Você pode fornecer um arquivo de parâmetros ao implantar seu modelo do Bicep. Esta é a aparência de um arquivo de parâmetros:

{
  "$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 ver 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âmetros.
• contentVersion é uma propriedade que você pode usar para acompanhar as alterações significativas no arquivo de parâmetros, se quiser. Normalmente ela é definida com seu valor padrão de 1.0.0.0.
• A seção parameters 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.

Em geral, 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âmetros. Por exemplo, você pode ter um arquivo de parâmetros chamado main.parameters.dev.json para seu ambiente de desenvolvimento e um chamado main.parameters.production.json para seu ambiente de produção.

Observação

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

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

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

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

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

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

Substituir os valores de parâmetros

Agora você aprendeu três maneiras de especificar os valores de parâmetros: valores padrão, a linha de comando e os arquivos de parâmetros. É 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 especifica um valor diferente usando a linha de comando, o valor da linha de comando tem precedência. Vamos ver como os arquivos de parâmetros se ajustam a essa ordem de precedência.

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

Vamos ver como essa abordagem funciona. Veja um exemplo de arquivo do 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 ver um arquivo de parâmetros que substitui o valor de dois dos parâmetros, mas não especifica um valor para o parâmetro location:

{
  "$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"
      }
    }
  }
}

Ao criar a implantação, também substituímos o valor de appServicePlanInstanceCount. Assim como nos arquivos de parâmetros, você usa o argumento --parameters, mas adiciona o 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âmetros. Especifique o nome do parâmetro como se fosse um argumento para o cmdlet:

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

Vamos ver quais serão os valores.

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

Usando uma combinação das abordagens para especificar os valores de parâmetros, você pode evitar a necessidade de duplicar os valores de parâmetros em muitos locais, enquanto ainda tem a flexibilidade para substituir onde você precisa.