Adicione flexibilidade usando parâmetros e variáveis

  • 10 minutos

Os modelos são poderosos devido à sua reutilização. Você pode usar o Bicep para escrever modelos que implantam vários ambientes ou cópias de seus recursos.

Sua empresa de brinquedos lança novos produtos regularmente e você precisa usar os modelos do Bicep para criar os recursos do Azure necessários para cada lançamento de produto. Você precisa evitar o uso de nomes de recursos fixos. Muitos tipos de recursos do Azure precisam de nomes exclusivos, portanto, incorporar nomes em seu modelo significa que você não pode reutilizar o modelo para vários lançamentos de produtos. Você também precisa implantar os recursos em locais diferentes, dependendo de onde os brinquedos serão lançados, o que significa que você também não pode incorporar os locais de recursos em seu modelo.

Nesta unidade, você aprenderá sobre parâmetros e variáveis, que são dois recursos do Bíceps que podem tornar seus modelos flexíveis e reutilizáveis. Você também será apresentado às expressões.

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.

Parâmetros e variáveis

Um parâmetro permite trazer valores de fora do arquivo de modelo. Por exemplo, se você estiver implantando manualmente o modelo usando a CLI do Azure ou o Azure PowerShell, será solicitado que forneça valores para cada parâmetro. Você também pode criar um arquivo de parâmetro, que lista todos os parâmetros e valores que você deseja usar para a implantação. Se o modelo for implantado a partir de um processo automatizado, como um pipeline de implantação, o pipeline poderá fornecer os valores dos parâmetros.

Uma variável é definida e definida dentro do modelo. As variáveis permitem armazenar informações importantes em um só lugar e consultá-las em todo o modelo sem precisar copiá-las e colá-las.

Geralmente, é uma boa ideia usar parâmetros para coisas que mudarão entre cada implantação, como:

  • Nomes de recursos que precisam ser exclusivos.
  • Locais nos quais implantar os recursos.
  • Configurações que afetam a definição de preço dos recursos, como suas SKUs, níveis de preços e contagens de instâncias.
  • Credenciais e informações necessárias para acessar outros sistemas que não estão definidos no modelo.

As variáveis geralmente são uma boa opção quando você usa os mesmos valores para cada implantação, mas deseja tornar um valor reutilizável dentro do modelo ou quando deseja usar expressões para criar um valor complexo. Você também pode usar variáveis para recursos que não precisam de nomes exclusivos.

Gorjeta

É importante usar uma boa nomenclatura para parâmetros e variáveis, para que seus modelos sejam fáceis de ler e entender. Certifique-se de que está a utilizar nomes claros, descritivos e consistentes.

Adicionar um parâmetro

No Bicep, você pode definir um parâmetro como este:

param appServiceAppName string

Vejamos como funciona cada parte desta definição:

  • param informa ao Bicep que você está definindo um parâmetro.
  • appServiceAppName é o nome do parâmetro. Se você estiver implantando o modelo manualmente, poderá ser solicitado que insira um valor, por isso é importante que o nome seja claro e compreensível. O nome também é como você se refere ao valor do parâmetro dentro do modelo, assim como com nomes simbólicos de recurso.
  • string é o tipo do parâmetro. Você pode especificar vários tipos diferentes para parâmetros do Bíceps, incluindo string texto, int números e bool valores booleanos verdadeiros ou falsos. Você também pode passar parâmetros mais complexos usando os array tipos e object .

Gorjeta

Tente não generalizar demais os modelos usando muitos parâmetros. Você deve usar o número mínimo de parâmetros necessários para seu cenário de negócios. Lembre-se, você sempre pode alterar modelos no futuro se seus requisitos mudarem.

Fornecer valores padrão

Opcionalmente, você pode fornecer um valor padrão para um parâmetro. Quando você especifica um valor padrão, o parâmetro se torna opcional. A pessoa que está implantando o modelo pode especificar um valor se desejar, mas se não quiser, o Bicep usa o valor padrão.

Veja como você pode adicionar um valor padrão:

param appServiceAppName string = 'toy-product-launch-1'

Nota

Neste exemplo, o nome do aplicativo do Serviço de Aplicativo do Azure tem um valor padrão codificado. Isso não é uma boa ideia, porque os aplicativos do Serviço de Aplicativo precisam de nomes exclusivos. Você corrigirá isso em breve.

Usar valores de parâmetro no modelo

Depois de declarar um parâmetro, você pode consultá-lo em todo o restante do modelo. Vamos ver como você pode usar seu novo parâmetro dentro da definição de recurso:

resource appServiceApp 'Microsoft.Web/sites@2022-03-01' = {
  name: appServiceAppName
  location: 'eastus'
  properties: {
    serverFarmId: appServicePlan.id
    httpsOnly: true
  }
}

Observe que o modelo agora usa o valor do parâmetro para definir o nome do recurso para o recurso do aplicativo, em vez de um valor codificado.

Gorjeta

A extensão Bicep para Visual Studio Code mostra indicadores visuais para que você saiba quando você não está seguindo as práticas recomendadas. Por exemplo, ele avisa se você definir um parâmetro que você não usa. O Linter Bicep executa continuamente essas verificações enquanto você trabalha.

Adicionar uma variável

Você pode definir uma variável como esta:

var appServicePlanName = 'toy-product-launch-plan'

As variáveis são definidas de forma semelhante aos parâmetros, mas existem algumas diferenças:

  • Use a var palavra-chave para dizer ao Bicep que você está declarando uma variável.
  • Você deve fornecer um valor para uma variável.
  • As variáveis não precisam de tipos. O bíceps pode determinar o tipo com base no valor definido.

Expressões

Quando você está escrevendo modelos, muitas vezes não quer codificar valores ou até mesmo pedir que eles sejam especificados em um parâmetro. Em vez disso, você deseja descobrir valores quando o modelo é executado. Por exemplo, você provavelmente deseja implantar todos os recursos em um modelo em uma única região do Azure: a região onde você criou o grupo de recursos. Ou, você pode querer criar automaticamente um nome exclusivo para um recurso com base em uma estratégia de nomenclatura específica que sua empresa usa.

As expressões no Bicep são um recurso poderoso que ajuda você a lidar com todos os tipos de cenários interessantes. Vamos dar uma olhada em alguns lugares onde você pode usar expressões em um modelo de bíceps.

Locais de recursos

Quando você está escrevendo e implantando um modelo, geralmente não quer ter que especificar o local de cada recurso individualmente. Em vez disso, você pode ter uma regra de negócios simples que diz, por padrão, implantar todos os recursos no mesmo local em que o grupo de recursos foi criado.

No Bicep, você pode criar um parâmetro chamado e, em locationseguida, usar uma expressão para definir seu valor:

param location string = resourceGroup().location

Observe o valor padrão desse parâmetro. Ele usa uma função chamada resourceGroup() que lhe dá acesso a informações sobre o grupo de recursos no qual o modelo está sendo implantado. Neste exemplo, o modelo usa a location propriedade. É comum usar essa abordagem para implantar seus recursos na mesma região do Azure que o grupo de recursos.

Se alguém estiver implantando esse modelo, poderá optar por substituir o valor padrão aqui e usar um local diferente.

Nota

Alguns recursos no Azure podem ser implantados apenas em determinados locais. Talvez você precise de parâmetros separados para definir os locais desses recursos.

Agora você pode usar o parâmetro resource location dentro do modelo, da seguinte forma:

resource appServiceApp 'Microsoft.Web/sites@2022-03-01' = {
  name: appServiceAppName
  location: location
  properties: {
    serverFarmId: appServicePlan.id
    httpsOnly: true
  }
}

Nomes de recursos

Muitos recursos do Azure precisam de nomes exclusivos. No seu cenário, você tem dois recursos que precisam de nomes exclusivos: a conta de armazenamento e o aplicativo do Serviço de Aplicativo. Pedir que esses valores sejam definidos como parâmetros pode dificultar para quem usa o modelo, porque eles precisam encontrar um nome que ninguém mais usou.

O bíceps tem outra função chamada uniqueString() que é útil quando você está criando nomes de recursos. Ao usar essa função, você precisa fornecer um valor semente, que deve ser diferente em diferentes implantações, mas consistente em todas as implantações dos mesmos recursos.

Se você escolher um bom valor de semente, poderá obter o mesmo nome sempre que implantar o mesmo conjunto de recursos, mas obterá um nome diferente sempre que implantar um conjunto diferente de recursos usando o mesmo modelo. Vamos ver como você pode usar a uniqueString() função:

param storageAccountName string = uniqueString(resourceGroup().id)

O valor padrão desse parâmetro usa a resourceGroup() função novamente, como você fez quando definiu o local do recurso. Desta vez, porém, você está recebendo a ID de um grupo de recursos. Eis o aspeto de um ID de grupo de recursos:

/subscriptions/3e57e557-826f-460b-8f1c-4ce38fd53b32/resourceGroups/MyResourceGroup

A ID do grupo de recursos inclui a ID da assinatura do Azure () e o nome do grupo de recursos (3e57e557-826f-460b-8f1c-4ce38fd53b32MyResourceGroup). O ID do grupo de recursos geralmente é um bom candidato para um valor de semente para nomes de recursos, porque:

  • Sempre que você implantar os mesmos recursos, eles entrarão no mesmo grupo de recursos. A uniqueString() função retornará o mesmo valor todas as vezes.
  • Se você implantar em dois grupos de recursos diferentes na assinatura do Azure, o resourceGroup().id valor será diferente, porque os nomes dos grupos de recursos serão diferentes. A uniqueString() função dará valores diferentes para cada conjunto de recursos.
  • Se você implantar em duas assinaturas diferentes do Azure, mesmo que use o mesmo nome de grupo de recursos, o resourceGroup().id valor será diferente porque a ID da assinatura do Azure será diferente. A uniqueString() função dará novamente valores diferentes para cada conjunto de recursos.

Gorjeta

Muitas vezes, é uma boa ideia usar expressões de modelo para criar nomes de recursos. Muitos tipos de recursos do Azure têm regras sobre os caracteres permitidos e o comprimento de seus nomes. Incorporar a criação de nomes de recursos no modelo significa que qualquer pessoa que use o modelo não precisa se lembrar de seguir essas regras.

Strings combinadas

Se você usar apenas a uniqueString() função para definir nomes de recursos, provavelmente obterá nomes exclusivos, mas eles não serão significativos. Um bom nome de recurso também deve ser descritivo, para que fique claro para que serve o recurso. Muitas vezes, você desejará criar um nome combinando uma palavra ou cadeia de caracteres significativa com um valor exclusivo. Dessa forma, você terá recursos com nomes significativos e exclusivos.

O bíceps tem um recurso chamado interpolação de cadeias de caracteres que permite combinar cadeias de caracteres. Vamos ver como funciona:

param storageAccountName string = 'toylaunch${uniqueString(resourceGroup().id)}'

O valor padrão para o storageAccountName parâmetro agora tem duas partes:

  • toylaunch é uma cadeia de caracteres codificada que ajuda qualquer pessoa que examine o recurso implantado no Azure a entender a finalidade da conta de armazenamento.
  • ${uniqueString(resourceGroup().id)} é uma maneira de dizer ao Bicep para avaliar a uniqueString(resourceGroup().id) saída da função e, em seguida, concatená-la na string.

Gorjeta

Às vezes, a uniqueString() função criará cadeias de caracteres que começam com um número. Alguns recursos do Azure, como contas de armazenamento, não permitem que seus nomes comecem com números. Isso significa que é uma boa ideia usar a interpolação de cadeia de caracteres para criar nomes de recursos, como no exemplo anterior.

Seleção de SKUs para recursos

Os outros membros da sua equipe ficaram impressionados com o código Bicep que você criou até agora. Você decidiu em conjunto que usará seu modelo para implantar os recursos para dar suporte a todos os lançamentos de novos brinquedos.

Um de seus colegas sugeriu que você crie ambientes de não produção para cada lançamento de produto para ajudar a equipe de marketing a testar os sites antes que eles estejam disponíveis para os clientes. No entanto, você quer ter certeza de que não gasta muito dinheiro em seus ambientes que não são de produção, então você decide sobre algumas políticas em conjunto:

  • Em ambientes de produção, as contas de armazenamento serão implantadas no Standard_GRS SKU (armazenamento com redundância geográfica) para alta resiliência. Os planos do P2v3 Serviço de Aplicativo serão implantados no SKU para alto desempenho.
  • Em ambientes que não sejam de produção, as contas de armazenamento serão implantadas na Standard_LRS SKU (armazenamento com redundância local). Os planos do Serviço de Aplicativo serão implantados no SKU gratuito F1 .

Uma maneira de implementar esses requisitos de negócios é usar parâmetros para especificar cada SKU. No entanto, especificar cada SKU como um parâmetro pode se tornar difícil de gerenciar, especialmente quando você tem modelos maiores. Outra opção é incorporar as regras de negócios no modelo usando uma combinação de parâmetros, variáveis e expressões.

Primeiro, você pode especificar um parâmetro que indique se a implantação é para um ambiente de produção ou não:

@allowed([
  'nonprod'
  'prod'
])
param environmentType string

Observe que esse código usa uma sintaxe nova para especificar uma lista de valores permitidos para o environmentType parâmetro. O Bicep não permitirá que ninguém implante o modelo, a menos que forneça um desses valores.

Em seguida, você pode criar variáveis que determinam as SKUs a serem usadas para a conta de armazenamento e o plano do Serviço de Aplicativo com base no ambiente:

var storageAccountSkuName = (environmentType == 'prod') ? 'Standard_GRS' : 'Standard_LRS'
var appServicePlanSkuName = (environmentType == 'prod') ? 'P2V3' : 'F1'

Observe também uma sintaxe nova. Vamos detalhar:

  • (environmentType == 'prod') avalia como um valor booleano (verdadeiro ou falso), dependendo de qual valor permitido é usado para environmentType o parâmetro.
  • ? é chamado de operador ternário e avalia uma if/then instrução. O valor após o ? operador é usado se a expressão for true. Se a expressão for avaliada como false, o valor após os dois pontos (:) será usado.

Podemos traduzir estas regras para:

  • Para a variável, se o environmentType parâmetro estiver definido como prod, use a storageAccountSkuNameStandard_GRS SKU. Caso contrário, use a Standard_LRS SKU.
  • Para a variável, se o environmentType parâmetro estiver definido como prod, use a SKU e a appServicePlanSkuNameP2V3PremiumV3 camada. Caso contrário, use a F1 SKU.

Gorjeta

Quando você cria expressões com várias partes como esta, é melhor usar variáveis em vez de incorporar as expressões diretamente nas propriedades do recurso. Isso torna seus modelos mais fáceis de ler e entender, porque evita sobrecarregar suas definições de recursos com lógica.

Ao usar parâmetros, variáveis e expressões em seu modelo, você pode reutilizá-lo e implantar rapidamente um novo conjunto de recursos. Por exemplo, cada vez que seu departamento de marketing solicita que você implante um novo site para o próximo lançamento de brinquedo, você fornece novos valores de parâmetro para cada ambiente que implanta e você será definido!