Parametrien ymmärtäminen

Parametrien avulla voit antaa tietoja Bicep-malliin käyttöönoton yhteydessä. Voit tehdä Bicep-mallista joustavan ja uudelleenkäytettävän ilmoittamalla parametrit mallissasi.

Sisustajat tarjoavat tavan liittää rajoituksia ja metatietoja parametriin, mikä auttaa kaikkia mallejasi käyttäviä ymmärtämään, mitä tietoja heidän on annettava.

Tässä osiossa opit lisää parametreista ja decorator-elementneistä.

Parametrin ilmoittaminen

Bicep-mallissa voit määrittää parametrin param avainsanan avulla. Voit sijoittaa nämä esittelyt mihin tahansa mallitiedostoon, mutta yleensä ne kannattaa sijoittaa tiedoston yläosaan, jotta Bicep-koodisi on helppo lukea.

Voit määrittää parametrin näin:

param environmentName string

Katsotaan seuraavaksi, miten kukin osa toimii:

• param ilmaisee Bicepille, että määrität parametrin.

• environmentName viittaa parametrin nimeen. Vaikka parametrin nimi voi olla mikä tahansa, sinun tulee selkeyttää mallin käyttäjien nimeä ja ymmärtää sitä. Samassa mallissa voit myös viitata parametriin käyttämällä sen nimeä. Parametrien nimien on oltava yksilöllisiä. Heillä ei voi olla samaa nimeä kuin muuttujalla tai resurssilla samassa Bicep-tiedostossa.

  Tip

  Käytä parametrimääritysten parhaiden käytäntöjen nimeämiskäytäntöjä. Hyvät nimeämiskäytännöt helpottavat mallien lukemista ja ymmärtämistä. Varmista, että käytät selkeitä, kuvaavia nimiä, ja valitse johdonmukainen nimeämisstrategia.

• string viittaa parametrin tyyppiin.

  Tip

  Harkitse tarkkaan mallisi käyttämiä parametreja. Yritä käyttää parametreja asetuksiin, jotka muuttuvat käyttöönottojen välillä. Muuttujia ja pysyväiskoodaisia arvoja voidaan käyttää asetuksissa, jotka eivät muutu käyttöönottojen välillä.

Oletusarvon lisääminen

Voit määrittää mallien parametreille oletusarvot. Määrittämällä oletusarvon teet parametrista valinnaisen. Jos malli otetaan käyttöön ilman määritettyä arvoa parametrille, oletusarvo määritetään.

Voit lisätä oletusarvon näin:

param environmentName string = 'dev'

environmentName parametrille määritetään oletusarvoksi dev.

Lausekkeita voidaan käyttää oletusarvoina. Tässä on esimerkki merkkijonoparametrista nimeltä location, jonka oletusarvoksi on määritetty nykyisen resurssiryhmän sijainti:

param location string = resourceGroup().location

Tutustu parametrityyppeihin

Kun määrität parametrin, sinun täytyy kertoa Bicepille, minkä tyyppisiä tietoja parametri sisältää. Bicep varmistaa, että parametrille määritetty arvo on yhteensopiva parametrityypin kanssa.

Bicep-parametrit voivat olla jokin seuraavista tyypeistä:

• string, jonka avulla voit syöttää satunnaista tekstiä.
• int, jonka avulla voit antaa luvun.
• bool, joka edustaa totuusarvoa (tosi tai epätosi).
• object ja array, jotka edustavat jäsennettyjä tietoja ja luetteloita.

Objects

Objektiparametrien avulla voit yhdistää jäsennettyjä tietoja yhteen paikkaan. Objektilla voi olla useita erityyppisiä ominaisuuksia. Voit käyttää objekteja resurssimääritelmissä, muuttujien sisällä tai Bicep-tiedoston lausekkeissa. Tässä on esimerkki objektista:

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

Tämä parametri on objekti, jolla on kaksi merkkijono-ominaisuutta: name ja tier, ja kokonaislukuominaisuus capacity. Huomaa, että kukin ominaisuuksista on omalla rivillään.

Kun viittaat parametriin mallissa, voit valita objektin yksittäiset ominaisuudet käyttämällä pistettä, jota seuraa ominaisuuden nimi, kuten tässä esimerkissä:

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

Toinen esimerkki siitä, missä saatat käyttää objektiparametria, on resurssitunnisteiden määrittäminen. Voit liittää mukautettujen tunnisteiden metatiedot resursseihin, joita voit käyttää resurssin tärkeiden tietojen tunnistamiseen.

Tunnisteet ovat hyödyllisiä skenaarioissa, kuten resurssin omistavan tiimin seurannassa tai resurssin kuulumisessa tuotantoympäristöön tai muuhun kuin tuotantoympäristöön. Yleensä käytät eri tunnisteita kullekin ympäristölle, mutta haluat käyttää samoja tunnistearvoja uudelleen kaikissa mallisi resursseissa. Tästä syystä resurssitunnisteet ovat hyvä käyttökohdeparametrille, kuten tässä esimerkissä:

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

Aina, kun määrität resurssin Bicep-tiedostossa, voit käyttää sitä uudelleen missä tahansa määrität tags -ominaisuuden:

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

Matriisi on kohteiden luettelo. Saatat esimerkiksi käyttää merkkijonoarvomatriisia sähköpostiosoitteiden luettelon ilmoittamiseen Azure Monitor -toimintoryhmälle. Voit myös käyttää -objektimatriisia edustamaan näennäisverkon aliverkkojen luetteloa.

Käsitellään esimerkkiä. Azure Cosmos DB:n avulla voit luoda tietokantatilejä useille alueille, ja se käsittelee tietojen replikoinnin automaattisesti puolestasi. Kun otat käyttöön uuden tietokantatilin, sinun on määritettävä luettelo Azure-alueista, joilla haluat tilin käyttöön. Usein eri ympäristöjen sijainnit on luetteloitava eri tavalla. Jos esimerkiksi haluat säästää rahaa testiympäristössäsi, saatat käyttää vain yhtä tai kahta sijaintia. Tuotantoympäristössäsi saatat kuitenkin käyttää useita sijainteja.

Voit luoda matriisiparametrin, joka määrittää sijaintiluettelon:

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

Kun olet ilmoittanut Azure Cosmos DB -resurssisi, voit nyt viitata matriisiparametriin:

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

Kehitysympäristössä on helppo käyttää eri parametriarvoa muuttamalla parametrin arvoa. Pian opit tarjoamaan erilaisia parametriarvoja muokkaamatta alkuperäistä malliasi.

Sallittujen arvojen luettelon määrittäminen

Joskus on varmistettava, että parametrilla on tiettyjä arvoja. Tiimisi saattaa esimerkiksi päättää, että tuotannon sovelluspalvelusopimukset otetaan käyttöön Premium v3 -varastointiyksiköillä. Voit pakottaa tämän säännön käyttöön @allowed parametrin decoratorilla. Parametrien sisustaja on tapa antaa Bicepille tietoa siitä, mikä parametrin arvon on oltava. appServicePlanSkuName -nimistä merkkijonoparametria voidaan rajoittaa siten, että vain muutama tietty arvo voidaan määrittää:

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

Rajoita parametrin pituutta ja arvoja

Kun käytät merkkijonoparametreja, sinun on usein rajoitettava merkkijonon pituutta. Käsitellään esimerkkiä Azure-resurssien nimeämisestä. Kaikilla Azure-resurssityypeillä on rajat nimien pituuden mukaan. Hyvänä käytäntönä on määrittää nimeämistä ohjaavien parametrien vähimmäis- ja enimmäispituus, jotta vältetään virheet myöhemmin käyttöönoton aikana. Voit käyttää @minLength- ja @maxLength-decorator-elementit parametrin sallimaan vähimmäis- ja enimmäispituuteen.

Tässä on esimerkki, jossa esitellään merkkijonoparametri nimeltä storageAccountName, jonka pituus voi olla vain 5–24 merkkiä:

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

Tämä parametri sisältää kaksi decoratoria. Voit käyttää useita decorator-elementit parametriin asettamalla kunkin decoratorin omalle rivilleen.

Kun käsittelet numeerisia parametreja, saatat tarvita arvoja tietyllä alueella. Leluyritys saattaa esimerkiksi päättää, että aina, kun joku ottaa käyttöön sovelluspalvelupaketin, sen on aina otettava käyttöön vähintään yksi esiintymä, mutta enintään 10 palvelupaketin esiintymää. Jotta voit täyttää vaatimukset, voit määrittää pienimmän ja suurimman sallitun arvon @minValue ja @maxValue decorator-elementillä. Seuraavassa esimerkissä esitellään kokonaislukuparametrin appServicePlanInstanceCount, jonka arvo voi olla vain välillä 1–10 (mukaan lukien):

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

Lisää parametreihin kuvauksia

Parametrien avulla muut käyttäjät voivat kätevästi käyttää mallejasi uudelleen. Kun he käyttävät mallejasi, heidän on ymmärrettävä, mitä kukin parametri tekee, jotta he voivat tarjota oikeat arvot. Bicep tarjoaa @description decoratorin, jonka avulla voit dokumentoida parametrien tarkoituksen ihmisen luettavissa olevalla tavalla.

@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

Parametrien kuvaukset on hyvä antaa. Yritä tehdä kuvauksista hyödyllisiä ja anna tärkeitä tietoja siitä, mitä malli tarvitsee parametriarvojen olevan.