Fornecer valores usando arquivos de parâmetro

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 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

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. arquivos de parâmetros são criados usando um arquivo de parâmetros Bicep com a extensão de arquivo .bicepparam ou um arquivo de parâmetros JSON que contém os valores de parâmetro. Você pode fornecer um arquivo de parâmetros ao implantar seu modelo Bicep. Veja como é um arquivo de parâmetros JSON:

{
  "$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âmetros.
• 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â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.

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 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 \
  --name main \
  --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 `
  -Name main `
  -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â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 depois 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 encaixam nessa 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 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â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"
      }
    }
  }
}

Quando você cria a implantação, também substituímos o valor de appServicePlanInstanceCount. 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 \
  --name main \
  --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 `
  -Name main `
  -TemplateFile main.bicep `
  -TemplateParameterFile main.parameters.json `
  -appServicePlanInstanceCount 5

Vejamos quais serão os valores.

Parâmetro	Value	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â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 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.