Förstå parametrar

  • 8 minuter

Med parametrar kan du ange information till en Bicep-mall vid distributionstillfället. Du kan göra en Bicep-mall flexibel och återanvändbar genom att deklarera parametrar i mallen.

Dekoratörer tillhandahåller ett sätt att koppla begränsningar och metadata till en parameter, vilket hjälper alla som använder dina mallar att förstå vilken information de behöver tillhandahålla.

I den här lektionen får du lära dig mer om parametrar och dekoratörer.

Deklarera en parameter

I en Bicep-mall deklarerar du en parameter med hjälp av nyckelordet param . Du kan placera dessa deklarationer var som helst i mallfilen, även om det vanligtvis är en bra idé att placera dem överst i filen så att din Bicep-kod är lätt att läsa.

Så här deklarerar du en parameter:

param environmentName string

Nu ska vi titta på hur varje del fungerar:

  • param anger för Bicep att du deklarerar en parameter.

  • environmentName refererar till namnet på parametern. Även om parameternamnet kan vara vad som helst bör du göra namnet tydligt och begripligt för mallanvändare. I samma mall kan du även referera till parametern med hjälp av dess namn. Parameternamn måste vara unika. De kan inte ha samma namn som en variabel eller en resurs i samma Bicep-fil.

    Dricks

    Använd namngivningskonventioner för bästa praxis för parameterdeklarationer. Bra namngivningskonventioner gör dina mallar lätta att läsa och förstå. Se till att du använder tydliga, beskrivande namn och anta konsekvent namngivningsstrategi.

  • string refererar till parametertypen.

    Dricks

    Tänk noga på de parametrar som mallen använder. Försök att använda parametrar för inställningar som ändras mellan distributioner. Variabler och hårdkodade värden kan användas för inställningar som inte ändras mellan distributioner.

Lägg till ett standardvärde

Du kan tilldela standardvärden till parametrar i dina mallar. Genom att tilldela ett standardvärde gör du parametern valfri. Om mallen distribueras utan ett angivet värde för parametern tilldelas standardvärdet.

Så här lägger du till ett standardvärde:

param environmentName string = 'dev'

Parametern environmentName tilldelas ett standardvärde på dev.

Du kan använda uttryck som standardvärden. Här är ett exempel på en strängparameter med namnet location med ett standardvärde inställt på platsen för den aktuella resursgruppen:

param location string = resourceGroup().location

Dricks

Tänk på de standardvärden som du använder. Se till att det är säkert för någon att distribuera Bicep-filen med standardvärdena. Överväg till exempel att använda billiga prisnivåer och SKU:er så att någon som distribuerar mallen till en testmiljö inte medför stora kostnader i onödan.

Förstå parametertyper

När du deklarerar en parameter måste du tala om för Bicep vilken typ av information parametern ska innehålla. Bicep ser till att värdet som tilldelats parametern är kompatibelt med parametertypen.

Parametrar i Bicep kan vara en av följande typer:

  • string, vilket gör att du kan ange godtycklig text.
  • int, vilket gör att du kan ange ett tal.
  • bool, som representerar ett booleskt värde (sant eller falskt).
  • object och array, som representerar strukturerade data och listor.

Objekt

Du kan använda objektparametrar för att kombinera strukturerade data på ett och samma ställe. Ett objekt kan ha flera egenskaper av olika typer. Du kan använda objekt i resursdefinitioner, i variabler eller i uttryck i Bicep-filen. Här är ett exempel på ett objekt:

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

Den här parametern är ett objekt med två strängegenskaper, name och tier, och en heltalsegenskap, capacity. Observera att var och en av egenskaperna finns på sin egen rad.

När du refererar till parametern i mallen kan du välja objektets enskilda egenskaper med hjälp av en punkt följt av namnet på egenskapen, som i det här exemplet:

resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
  name: appServicePlanName
  location: location
  sku: {
    name: appServicePlanSku.name
    tier: appServicePlanSku.tier
    capacity: appServicePlanSku.capacity
  }
}

Viktigt!

Tänk på att du inte anger typen av varje egenskap i ett objekt. Men när du använder en egenskaps värde måste dess typ matcha vad som förväntas. I föregående exempel måste både namnet och nivån för App Service-plan-SKU:n vara strängar.

Ett annat exempel på var du kan använda en objektparameter är för att ange resurstaggar. Du kan koppla anpassade taggmetadata till de resurser som du distribuerar, som du kan använda för att identifiera viktig information om en resurs.

Taggar är användbara för scenarier som att spåra vilket team som äger en resurs eller när en resurs tillhör en produktions- eller icke-produktionsmiljö. Vanligtvis använder du olika taggar för varje miljö, men du vill återanvända samma taggvärden på alla resurser i mallen. Därför är resurstaggar en bra användning för en objektparameter, som i det här exemplet:

param resourceTags object = {
  EnvironmentName: 'Test'
  CostCenter: '1000100'
  Team: 'Human Resources'
}

När du definierar en resurs i Bicep-filen kan du återanvända den var du än definierar tags egenskapen:

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

Matriser

En matris är en lista över objekt. Du kan till exempel använda en matris med strängvärden för att deklarera en lista med e-postadresser för en Azure Monitor-åtgärdsgrupp. Eller så kan du använda en matris med objekt för att representera en lista över undernät för ett virtuellt nätverk.

Kommentar

Du kan inte ange vilken typ av enskilda objekt som en matris måste innehålla. Du kan till exempel inte ange att en matris måste innehålla strängar.

Vi tar ett exempel. Med Azure Cosmos DB kan du skapa databaskonton som sträcker sig över flera regioner och automatiskt hanterar datareplikeringen åt dig. När du distribuerar ett nytt databaskonto måste du ange listan över Azure-regioner som du vill att kontot ska distribueras till. Ofta behöver du ha en annan lista över platser för olika miljöer. Om du till exempel vill spara pengar i testmiljön kanske du bara använder en eller två platser. Men i produktionsmiljön kan du använda flera platser.

Du kan skapa en matrisparameter som anger en lista över platser:

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

Dricks

Föregående exempel är en matris med objekt. Varje objekt har en locationName egenskap, vilket är vad Azure Cosmos DB förväntar sig. När du arbetar med en resursdefinition i Visual Studio Code kan du börja med att ange resursegenskaper så att du får IntelliSense från Bicep-verktyget. Du kan skapa några exempelvärden med den här metoden. När du är nöjd med konfigurationen flyttar du avsnittet med Bicep-kod till parametern. På så sätt kan du ersätta en hårdkodad egenskap med en parameter som kan ändras under varje distribution, samtidigt som du ser till att resursen är korrekt konfigurerad.

När du deklarerar din Azure Cosmos DB-resurs kan du nu referera till matrisparametern:

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

Det är sedan enkelt att använda ett annat parametervärde för utvecklingsmiljön genom att ändra värdet för parametern. Snart får du lära dig hur du kan ange olika parametervärden utan att ändra den ursprungliga mallen.

Ange en lista över tillåtna värden

Ibland måste du se till att en parameter har vissa värden. Ditt team kan till exempel bestämma att apptjänstplaner för produktion ska distribueras med hjälp av Premium v3-SKU:er. Om du vill tillämpa den här regeln kan du använda parameterdekoratören @allowed . En parameterdekoratör är ett sätt att ge Bicep information om vad en parameters värde måste vara. Så här kan en strängparameter med namnet appServicePlanSkuName begränsas så att endast några få specifika värden kan tilldelas:

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

Dricks

Använd dekoratören @allowed sparsamt. Om du använder den här dekoratören för brett kan du blockera giltiga distributioner om du inte håller listan uppdaterad. Föregående exempel tillåter endast Premium v3 SKU:er i produktion. Om du behöver använda samma mall för att distribuera några billigare icke-produktionsmiljöer kan listan med tillåtna värden hindra dig från att använda andra SKU:er som du behöver använda.

Begränsa parameterlängd och -värden

När du använder strängparametrar måste du ofta begränsa längden på strängen. Låt oss ta ett exempel på namngivning av Azure-resurser. Alla Azure-resurstyper har gränser runt längden på deras namn. Det är en bra idé att ange minsta och högsta teckenlängd för parametrar som styr namngivning för att undvika fel senare under distributionen. Du kan använda @minLength dekoratörer och @maxLength till de minsta och högsta teckenlängder som du vill tillåta för en parameter.

Här är ett exempel som deklarerar en strängparameter med namnet storageAccountName, vars längd bara kan vara mellan 5 och 24 tecken:

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

Den här parametern innehåller två dekoratörer. Du kan använda flera dekoratörer för en parameter genom att placera varje dekoratör på sin egen rad.

Kommentar

Du kan också använda dekoratörerna @minLength och @maxLength för matrisparametrar för att styra hur många objekt som tillåts finnas i matrisen.

När du arbetar med numeriska parametrar kan du behöva värden i ett visst intervall. Ditt leksaksföretag kan till exempel besluta att när någon distribuerar en App Service-plan bör de alltid distribuera minst en instans, men inte fler än 10 instanser av planen. För att uppfylla kraven kan du använda dekoratörerna @minValue och @maxValue för att ange lägsta och högsta tillåtna värden. I följande exempel deklareras heltalsparametern appServicePlanInstanceCount vars värde bara kan vara mellan 1 och 10 (inklusive):

@minValue(1)
@maxValue(10)
param appServicePlanInstanceCount int

Lägga till beskrivningar i parametrar

Parametrar är ett bra sätt att göra dina mallar återanvändbara av andra. När de använder dina mallar måste de förstå vad varje parameter gör så att de kan tillhandahålla rätt värden. Bicep tillhandahåller dekoratören @description så att du kan dokumentera parametrarnas syfte på ett sätt som kan läsas av människor.

@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

Det är en bra idé att ange beskrivningar för dina parametrar. Försök att göra beskrivningarna användbara och ange viktig information om vilken mall som behöver parametervärdena.

Kommentar

Bicep-mallar kan ibland göras tillgängliga i Azure Portal för användare att distribuera, till exempel när du använder mallspecifikationer. Portalen använder beskrivningarna och andra dekoratörer på parametrar för att hjälpa användarna att förstå vad ett parametervärde behöver vara.