Paraméterek ismertetése

  • 8 perc

A paraméterekkel információkat adhat meg egy Bicep-sablonnak az üzembe helyezéskor. A Bicep-sablonokat rugalmassá és újrafelhasználhatóvá teheti úgy, hogy paramétereket deklarál a sablonon belül.

A dekorátorok lehetővé teszik, hogy kényszereket és metaadatokat csatoljanak egy paraméterhez, ami segít, hogy a sablonokat használó felhasználók megértsék, milyen információkat kell megadniuk.

Ebben a leckében a paraméterekkel és a dekoratőrekkel ismerkedhet meg.

Paraméter deklarálása

Bicep-sablonban a kulcsszó használatával deklarálhat egy paramétert param . Ezeket a deklarációkat bárhol elhelyezheti a sablonfájlban, bár általában érdemes a fájl tetejére helyezni őket, hogy a Bicep-kód könnyen olvasható legyen.

A paraméter deklarálása a következőképpen történt:

param environmentName string

Tekintsük át az egyes részeket:

  • param azt jelzi a Bicepnek, hogy egy paramétert deklarál.

  • environmentName a paraméter nevére hivatkozik. Bár a paraméternév bármi lehet, egyértelművé és érthetővé kell tennie a nevet a sablon felhasználói számára. Ugyanazon a sablonon belül a paraméterre is hivatkozhat a nevével. A paraméterneveknek egyedinek kell lenniük. Nem lehet ugyanaz a név, mint egy változó vagy egy erőforrás ugyanabban a Bicep-fájlban.

    Tipp.

    A paraméterdeklarációkhoz ajánlott elnevezési konvenciók használata. A jó elnevezési konvenciók megkönnyítik a sablonok olvasását és megértését. Győződjön meg arról, hogy világos, leíró neveket használ, és konzisztens elnevezési stratégiát alkalmaz.

  • string a paraméter típusára hivatkozik.

    Tipp.

    Alaposan gondolja át a sablon által használt paramétereket. Próbálja meg paramétereket használni az üzemelő példányok között változó beállításokhoz. A változók és a rögzített értékek olyan beállításokhoz használhatók, amelyek nem változnak az üzemelő példányok között.

Alapértelmezett érték hozzáadása

A sablonokban lévő paraméterekhez alapértelmezett értékeket rendelhet. Az alapértelmezett érték hozzárendelésével a paraméter megadása nem kötelező. Ha a sablon a paraméter megadott értéke nélkül van üzembe helyezve, az alapértelmezett érték lesz hozzárendelve.

Az alapértelmezett érték hozzáadása a következőképpen történt:

param environmentName string = 'dev'

A paraméterhez a rendszer environmentName a következő alapértelmezett értéket rendeli dev: .

A kifejezéseket alapértelmezett értékként használhatja. Íme egy példa egy sztringparaméterre location , amelynek alapértelmezett értéke az aktuális erőforráscsoport helye:

param location string = resourceGroup().location

Tipp.

Ügyeljen a használt alapértelmezett értékekre. Győződjön meg arról, hogy biztonságos lesz, ha valaki telepíti a Bicep-fájlt az alapértelmezett értékekkel. Fontolja meg például az olcsó tarifacsomagok és termékváltozatok használatát, hogy a sablon tesztelési környezetben való üzembe helyezése ne járjon feleslegesen nagy költséggel.

A paramétertípusok ismertetése

Amikor deklarál egy paramétert, meg kell adnia a Bicepnek, hogy milyen típusú információkat tartalmaz majd a paraméter. A Bicep biztosítja, hogy a paraméterhez rendelt érték kompatibilis legyen a paramétertípussal.

A Bicep-paraméterek a következő típusok egyikét tartalmazhatják:

  • string, amely lehetővé teszi tetszőleges szöveg beírását.
  • int, amely lehetővé teszi szám megadását.
  • bool, amely logikai (igaz vagy hamis) értéket jelöl.
  • object és array, amelyek strukturált adatokat és listákat jelölnek.

Objektumokat

Objektumparaméterek használatával egy helyen kombinálhatja a strukturált adatokat. Egy objektum több különböző típusú tulajdonsággal is rendelkezhet. Az objektumokat az erőforrás-definíciókon belül, változókban vagy a Bicep-fájlban lévő kifejezéseken belül is használhatja. Íme egy példa egy objektumra:

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

Ez a paraméter egy két sztringtulajdonságú objektum, name és tieregy egész szám tulajdonság. capacity Figyelje meg, hogy mindegyik tulajdonság a saját sorában van.

Amikor a sablonban hivatkozik a paraméterre, kiválaszthatja az objektum egyedi tulajdonságait egy ponttal, majd a tulajdonság nevével, például az alábbi példában:

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

Fontos

Ne feledje, hogy nem adja meg az objektumokon belüli egyes tulajdonságok típusát. Ha azonban egy tulajdonság értékét használja, annak típusának meg kell egyeznie a várt értékkel. Az előző példában az App Service-csomag termékváltozatának neve és szintje egyaránt sztringeknek kell lennie.

Egy másik példa arra, hogy hol használhat objektumparamétert az erőforráscímkék megadásához. Egyéni címke metaadatait csatolhatja az üzembe helyezendő erőforrásokhoz, amelyekkel azonosíthatja az erőforrásokkal kapcsolatos fontos információkat.

A címkék olyan helyzetekben hasznosak, mint például annak nyomon követése, hogy melyik csapat tulajdonában van egy erőforrás, vagy ha egy erőforrás éles vagy nem éles környezethez tartozik. Általában különböző címkéket fog használni az egyes környezetekhez, de ugyanazokat a címkeértékeket szeretné újra felhasználni a sablon összes erőforrásán. Ezért az erőforráscímkék jól használhatók objektumparaméterekhez, például ebben a példában:

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

Amikor definiál egy erőforrást a Bicep-fájlban, újra felhasználhatja, bárhol is definiálja a tulajdonságot tags :

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

Tömbök

A tömb az elemek listája. Példaként sztringértékek tömbje használatával deklarálhatja egy Azure Monitor-műveletcsoport e-mail-címeinek listáját. Vagy használhat objektumtömböt egy virtuális hálózat alhálózatainak listájának megjelenítéséhez.

Megjegyzés:

Nem adhatja meg, hogy a tömbnek milyen típusú elemeket kell tartalmaznia. Nem adhatja meg például, hogy egy tömbnek sztringeket kell tartalmaznia.

Vegyünk egy példát. Az Azure Cosmos DB lehetővé teszi, hogy több régióra kiterjedő adatbázisfiókokat hozzon létre, amelyek automatikusan kezelik az ön számára az adatreplikálást. Új adatbázisfiók üzembe helyezésekor meg kell adnia azon Azure-régiók listáját, amelyekbe telepíteni szeretné a fiókot. Gyakran előfordul, hogy különböző környezetekhez eltérő helylistával kell rendelkeznie. Ha például pénzt szeretne spórolni a tesztkörnyezetben, előfordulhat, hogy csak egy vagy két helyet használ. Az éles környezetben azonban több helyet is használhat.

Létrehozhat egy tömbparamétert, amely meghatározza a helyek listáját:

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

Tipp.

Az előző példa egy objektumtömb. Minden objektum rendelkezik egy locationName tulajdonságmal, amit az Azure Cosmos DB elvár. Amikor egy erőforrásdefinícióval dolgozik a Visual Studio Code-ban, először megadhatja az erőforrás tulajdonságait, hogy az IntelliSense a Bicep-eszközkészletből származzon. Ezzel a módszerrel létrehozhat néhány példaértéket. Miután elégedett a konfigurációval, helyezze át a Bicep-kód adott szakaszát a paraméterbe. Ily módon lecserélhet egy szigorúan kódolt tulajdonságot egy olyan paraméterre, amely az egyes üzemelő példányok során módosítható, miközben továbbra is biztosítja az erőforrás megfelelő konfigurálását.

Az Azure Cosmos DB-erőforrás deklarálásakor mostantól hivatkozhat a tömbparaméterre:

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

Ezután a paraméter értékének módosításával egyszerűen használhat egy másik paraméterértéket a fejlesztési környezethez. Hamarosan megtudhatja, hogyan adhat meg különböző paraméterértékeket az eredeti sablon módosítása nélkül.

Az engedélyezett értékek listájának megadása

Néha meg kell győződnie arról, hogy egy paraméter bizonyos értékekkel rendelkezik. A csapat például dönthet úgy, hogy az éles App Service-csomagokat a Prémium v3 termékváltozatok használatával kell üzembe helyezni. A szabály érvényesítéséhez használhatja a @allowed dekorátor paramétert. A paraméter-dekoratőr használatával a Bicep információt kaphat arról, hogy milyen értéket kell megadnia egy paraméternek. A következőképpen korlátozható egy elnevezett appServicePlanSkuName sztringparaméter, hogy csak néhány konkrét érték rendelhető hozzá:

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

Tipp.

Használja a @allowed dekoratőrt takarékosan. Ha túl széles körben használja ezt a dekoratőrt, letilthatja az érvényes üzembe helyezéseket, ha nem tartja naprakészen a listát. Az előző példa csak a Prémium v3 termékváltozatokat teszi lehetővé éles környezetben. Ha ugyanazt a sablont kell használnia néhány olcsóbb, nem éles környezet üzembe helyezéséhez, az engedélyezett értékek listája megakadályozhatja, hogy más, használni kívánt termékváltozatokat használjon.

Paraméterek hosszának és értékeinek korlátozása

Sztringparaméterek használatakor gyakran korlátoznia kell a sztring hosszát. Tekintsük át az Azure-erőforrások elnevezésének példáját. Minden Azure-erőforrástípusnak vannak a nevük hosszára vonatkozó korlátai. Célszerű megadni az elnevezést vezérlő paraméterek minimális és maximális karakterhosszát, hogy elkerülje a későbbi hibákat az üzembe helyezés során. A dekorátorokat és @maxLength a @minLength dekorátorokat a paraméterek számára engedélyezni kívánt minimális és maximális karakterhosszra használhatja.

Íme egy példa, amely deklarál egy sztringparamétert, storageAccountNameamelynek hossza csak 5 és 24 karakter között lehet:

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

Ez a paraméter két dekorátort tartalmaz. Egy paraméterre több dekorátort is alkalmazhat, ha mindegyik dekorátort a saját sorára helyezi.

Megjegyzés:

A tömbparaméterekre is alkalmazhatja a @minLength@maxLength dekoratőreket, így szabályozhatja, hogy hány elem szerepelhet a tömbben.

Ha numerikus paraméterekkel dolgozik, előfordulhat, hogy az értékeknek egy adott tartományban kell lenniük. A toy cég például dönthet úgy, hogy amikor valaki üzembe helyez egy App Service-csomagot, mindig legalább egy példányt kell üzembe helyeznie, de legfeljebb 10 példányt a csomagból. A követelményeknek való megfelelés érdekében a dekorátorok és @maxValue a @minValue dekorátorok segítségével megadhatja a minimális és maximális megengedett értékeket. Az alábbi példa deklarálja az egész szám paramétert appServicePlanInstanceCount , amelynek értéke csak 1 és 10 között lehet (beleértve a következőket):

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

Leírások hozzáadása paraméterekhez

A paraméterekkel mások is újra felhasználhatóvá tehetik a sablonokat. Amikor a sablonokat használják, meg kell érteniük, hogy az egyes paraméterek mit tesznek, hogy a megfelelő értékeket biztosíthassák. A Bicep biztosítja a @description dekoratőrt, hogy a paraméterek célját emberi olvasható módon dokumentálhassa.

@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

Ajánlott leírásokat megadni a paraméterekhez. Próbálja meg hasznossá tenni a leírásokat, és adjon meg minden fontos információt arról, hogy a sablonnak milyen paraméterértékekre van szüksége.

Megjegyzés:

A Bicep-sablonok néha elérhetővé tehetők az Azure Portalon, hogy a felhasználók üzembe helyezhessenek, például sablon-specifikációk használatakor. A portál a paraméterek leírásait és más dekoratőreit használja, hogy segítsen a felhasználóknak megérteni, hogy milyen paraméterértéknek kell lennie.