Om parametre

  • 8 minutter

Med parametrekan du angive oplysninger til en Bicep-skabelon på udrulningstidspunktet. Du kan gøre en Bicep-skabelon fleksibel og genbruges ved at erklære parametre i skabelonen.

dekoratører gøre det muligt at knytte begrænsninger og metadata til en parameter, hvilket hjælper alle, der bruger dine skabeloner, med at forstå, hvilke oplysninger de skal angive.

I dette undermodul lærer du om parametre og dekoratører.

Deklarer en parameter

I en Bicep-skabelon skal du deklarere en parameter ved hjælp af nøgleordet param. Du kan placere disse erklæringer overalt i skabelonfilen, selvom det normalt er en god idé at placere dem øverst i filen, så din Bicep-kode er let at læse.

Sådan deklarerer du en parameter:

param environmentName string

Lad os se på, hvordan hver del fungerer:

  • param angiver over for Bicep, at du erklærer en parameter.

  • environmentName henviser til navnet på parameteren. Selvom parameternavnet kan være alt, skal du gøre navnet klart og forståeligt for skabelonbrugerne. I den samme skabelon kan du også referere til parameteren ved hjælp af dens navn. Parameternavne skal være entydige. De kan ikke have det samme navn som en variabel eller en ressource i den samme Bicep-fil.

    Drikkepenge

    Brug navngivningskonventioner for bedste praksis for parametererklæringer. Gode navngivningskonventioner gør det nemt at læse og forstå dine skabeloner. Sørg for, at du bruger tydelige, beskrivende navne, og brug en konsekvent navngivningsstrategi.

  • string henviser til parameterens type.

    Drikkepenge

    Tænk nøje over de parametre, skabelonen bruger. Prøv at bruge parametre til indstillinger, der ændres mellem installationer. Variabler og hard-coded værdier kan bruges til indstillinger, der ikke ændres mellem installationer.

Tilføj en standardværdi

Du kan tildele standardværdier til parametre i dine skabeloner. Når du tildeler en standardværdi, gør du parameteren valgfri. Hvis skabelonen installeres uden en angivet værdi for parameteren, tildeles standardværdien.

Sådan tilføjer du en standardværdi:

param environmentName string = 'dev'

Parameteren environmentName tildeles standardværdien dev.

Du kan bruge udtryk som standardværdier. Her er et eksempel på en strengparameter med navnet location med en standardværdi angivet til placeringen af den aktuelle ressourcegruppe:

param location string = resourceGroup().location

Drikkepenge

Vær opmærksom på de standardværdier, du bruger. Sørg for, at det er sikkert for nogen at installere Bicep-filen med standardværdierne. Overvej f.eks. at bruge billige prisniveauer og SKU'er, så en person, der udruller skabelonen til et testmiljø, ikke påføres unødigt store omkostninger.

Forstå parametertyper

Når du deklarerer en parameter, skal du fortælle Bicep, hvilken type oplysninger parameteren indeholder. Bicep sikrer, at den værdi, der er tildelt parameteren, er kompatibel med parametertypen.

Parametre i Bicep kan være en af følgende typer:

  • string, hvor du kan angive vilkårlig tekst.
  • int, hvor du kan angive et tal.
  • bool, som repræsenterer en boolesk værdi (sand eller falsk).
  • object og array, der repræsenterer strukturerede data og lister.

Objekter

Du kan bruge objektparametre til at kombinere strukturerede data på ét sted. Et objekt kan have flere egenskaber af forskellige typer. Du kan bruge objekter i ressourcedefinitioner, i variabler eller i udtryk i din Bicep-fil. Her er et eksempel på et objekt:

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

Denne parameter er et objekt med to strengegenskaber, name og tier, og en heltalsegenskab capacity. Bemærk, at hver af egenskaberne er på sin egen linje.

Når du refererer til parameteren i skabelonen, kan du vælge objektets individuelle egenskaber ved hjælp af en prik efterfulgt af navnet på egenskaben, f.eks. i dette eksempel:

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

Vigtig

Vær opmærksom på, at du ikke angiver typen af hver egenskab i et objekt. Men når du bruger en egenskabs værdi, skal dens type svare til det, der forventes. I det forrige eksempel skal både navnet og niveauet for App Service-abonnements-SKU'en være strenge.

Et andet eksempel på, hvor du kan bruge en objektparameter, er til angivelse af ressourcekoder. Du kan vedhæfte brugerdefinerede mærkemetadata til de ressourcer, du udruller, som du kan bruge til at identificere vigtige oplysninger om en ressource.

Mærker er nyttige til scenarier, f.eks. sporing af, hvilket team der ejer en ressource, eller når en ressource tilhører et produktionsmiljø eller et miljø, der ikke er produktionsmiljø. Du bruger typisk forskellige mærker for hvert miljø, men du skal genbruge de samme kodeværdier på alle ressourcerne i skabelonen. Derfor er ressourcekoder en god måde at bruge en objektparameter på, f.eks. i dette eksempel:

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

Når du definerer en ressource i din Bicep-fil, kan du genbruge den, uanset hvor du definerer egenskaben tags:

resource appServicePlan 'Microsoft.Web/serverfarms@2024-04-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
  }
}

Arrays

En matrix er en liste over elementer. Du kan f.eks. bruge en matrix af strengværdier til at deklarere en liste over mailadresser for en handlingsgruppe i Azure Monitor. Du kan også bruge en matrix af objekter til at repræsentere en liste over undernet for et virtuelt netværk.

Seddel

Du kan ikke angive den type enkelte elementer, som en matrix skal indeholde. Du kan f.eks. ikke angive, at en matrix skal indeholde strenge.

Lad os se på et eksempel. Med Azure Cosmos DB kan du oprette databasekonti, der strækker sig over flere områder, og den håndterer automatisk datareplikeringen for dig. Når du udruller en ny databasekonto, skal du angive listen over Azure-områder, som kontoen skal udrulles i. Du skal ofte have en anden liste over placeringer til forskellige miljøer. Hvis du f.eks. vil spare penge i dit testmiljø, kan du kun bruge én eller to placeringer. Men i dit produktionsmiljø kan du bruge flere placeringer.

Du kan oprette en matrixparameter, der angiver en liste over placeringer:

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

Drikkepenge

Det foregående eksempel er en matrix af objekter. Hvert objekt har en locationName egenskab, hvilket er, hvad Azure Cosmos DB forventer. Når du arbejder med en ressourcedefinition i Visual Studio Code, kan du starte med at angive ressourceegenskaber, så du får IntelliSense fra Bicep-værktøjet. Du kan oprette nogle eksempelværdier ved hjælp af denne fremgangsmåde. Når du er tilfreds med konfigurationen, skal du flytte denne del af Bicep-koden til parameteren. På denne måde kan du erstatte en hard-coded egenskab med en parameter, der kan ændres under hver installation, samtidig med at du sikrer, at ressourcen er konfigureret korrekt.

Når du deklarerer din Azure Cosmos DB-ressource, kan du nu referere til matrixparameteren:

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

Det er derefter nemt at bruge en anden parameterværdi for dit udviklingsmiljø ved at ændre værdien af parameteren. Snart lærer du, hvordan du kan angive forskellige parameterværdier uden at ændre den oprindelige skabelon.

Angiv en liste over tilladte værdier

Nogle gange skal du sikre dig, at en parameter har visse værdier. Dit team kan f.eks. beslutte, at App Service-produktionsplaner skal udrulles ved hjælp af Premium v3-SKU'er. Hvis du vil gennemtvinge denne regel, kan du bruge @allowed parameterdekoratøren. En parameterdekoratør er en måde at give Bicep oplysninger om, hvad en parameters værdi skal være. Sådan kan en strengparameter med navnet appServicePlanSkuName begrænses, så der kun kan tildeles nogle få specifikke værdier:

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

Drikkepenge

Brug @allowed dekoratør sparsomt. Hvis du bruger denne dekoratør for bredt, kan du blokere gyldige installationer, hvis du ikke holder listen opdateret. Det foregående eksempel tillader kun Premium v3-SKU'er i produktion. Hvis du har brug for at bruge den samme skabelon til at udrulle nogle billigere ikke-produktionsmiljøer, kan listen over tilladte værdier forhindre dig i at bruge andre SKU'er, som du skal bruge.

Begræns parameterlængde og -værdier

Når du bruger strengparametre, skal du ofte begrænse strengens længde. Lad os se på eksemplet med navngivning af Azure-ressourcer. Alle Azure-ressourcetyper har grænser omkring længden af deres navne. Det er en god idé at angive minimum- og maksimumlængde for tegn for parametre, der styrer navngivning, for at undgå fejl senere under installationen. Du kan bruge @minLength og @maxLength dekoratører til den mindste og maksimale tegnlængde, du vil tillade for en parameter.

Her er et eksempel, der deklarerer en strengparameter med navnet storageAccountName, hvis længde kun kan være mellem 5 og 24 tegn:

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

Denne parameter indeholder to dekoratører. Du kan anvende flere dekoratører på en parameter ved at sætte hver dekoratør på sin egen linje.

Seddel

Du kan også anvende @minLength og @maxLength dekoratører på matrixparametre for at styre, hvor mange elementer der må være i matrixen.

Når du arbejder med numeriske parametre, skal du muligvis have værdier inden for et bestemt område. Dit legetøjsfirma kan f.eks. beslutte, at når nogen udruller en App Service-plan, skal de altid installere mindst én forekomst, men højst 10 forekomster af planen. Hvis du vil opfylde kravene, kan du bruge @minValue og @maxValue dekoratører til at angive de tilladte minimum- og maksimumværdier. I følgende eksempel erklæres heltalsparameteren appServicePlanInstanceCount hvis værdi kun kan være mellem 1 og 10 (inklusive):

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

Føj beskrivelser til parametre

Parametre er en god måde at gøre dine skabeloner genbrugelige for andre. Når de bruger dine skabeloner, skal de forstå, hvad hver parameter gør, så de kan levere de rigtige værdier. Bicep leverer den @description dekoratør, så du kan dokumentere dine parametres formål på en læsevenlig måde.

@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 er en god idé at angive beskrivelser af dine parametre. Prøv at gøre beskrivelserne nyttige, og angiv eventuelle vigtige oplysninger om, hvad skabelonen skal bruge parameterværdierne til.

Seddel

Bicep-skabeloner kan nogle gange gøres tilgængelige på Azure Portal, så brugerne kan installere dem, f.eks. når du bruger skabelonspecifikationer. Portalen bruger beskrivelserne og andre dekoratører til parametre for at hjælpe brugerne med at forstå, hvad en parameterværdi skal være.