Vysvětlení parametrů

Dokončeno

Pomocí parametrů můžete poskytnout informace šabloně Bicep v době nasazení. Šablonu Bicep můžete nastavit jako flexibilní a opakovaně použitelnou deklarací parametrů v rámci šablony.

Dekorátory poskytují způsob připojení omezení a metadat k parametru, který pomáhá každému, kdo používá šablony, pochopit, jaké informace potřebují poskytnout.

V této lekci se dozvíte o parametrech a dekorátorech.

Deklarace parametru

V šabloně Bicep deklarujete parametr pomocí klíčového param slova. Tyto deklarace můžete umístit kamkoli do souboru šablony, i když je obvykle vhodné je umístit do horní části souboru, aby byl kód Bicep snadno čitelný.

Tady je postup deklarace parametru:

param environmentName string

Pojďme se podívat, jak jednotlivé části fungují:

• param označuje bicep, že deklarujete parametr.

• environmentName odkazuje na název parametru. I když název parametru může být cokoli, měli byste ho pro uživatele šablony vymazat a pochopit. Ve stejné šabloně můžete také odkazovat na parametr pomocí jeho názvu. Názvy parametrů musí být jedinečné. Nemůžou mít stejný název jako proměnná nebo prostředek ve stejném souboru Bicep.

  Tip

  Pro deklarace parametrů použijte zásady vytváření názvů osvědčených postupů. Dobré zásady vytváření názvů usnadňují čtení a pochopení šablon. Ujistěte se, že používáte jasné, popisné názvy a používáte konzistentní strategii pojmenování.

• string odkazuje na typ parametru.

  Tip

  Pečlivě zvažte parametry, které šablona používá. Zkuste použít parametry pro nastavení, která se mezi nasazeními mění. Proměnné a pevně zakódované hodnoty se dají použít pro nastavení, která se mezi nasazeními nemění.

Přidání výchozí hodnoty

K parametrům v šablonách můžete přiřadit výchozí hodnoty. Přiřazením výchozí hodnoty nastavíte parametr jako volitelný. Pokud je šablona nasazená bez zadané hodnoty parametru, přiřadí se výchozí hodnota.

Tady je postup, jak přidat výchozí hodnotu:

param environmentName string = 'dev'

environmentName Parametr má přiřazenu výchozí hodnotu dev.

Výrazy můžete použít jako výchozí hodnoty. Tady je příklad parametru řetězce s location výchozí hodnotou nastavenou na umístění aktuální skupiny prostředků:

param location string = resourceGroup().location

Tip

Mějte na paměti výchozí hodnoty, které používáte. Ujistěte se, že bude bezpečné, aby někdo nasadil soubor Bicep s výchozími hodnotami. Zvažte například použití levných cenových úrovní a cenových úrovní, aby někdo, kdo šablonu nasadí do testovacího prostředí, zbytečně neúčtovaly velké náklady.

Principy typů parametrů

Když deklarujete parametr, musíte bicep sdělit, jaký typ informací parametr bude obsahovat. Bicep zajistí, aby hodnota přiřazená parametru byla kompatibilní s typem parametru.

Parametry v Bicep můžou být jedním z následujících typů:

• string, který umožňuje zadat libovolný text.
• int, který umožňuje zadat číslo.
• bool, který představuje logickou hodnotu (true nebo false).
• object a array, které představují strukturovaná data a seznamy.

Objekty

Parametry objektu můžete použít ke sloučení strukturovaných dat na jednom místě. Objekt může mít více vlastností různých typů. V souboru Bicep můžete použít objekty v definicích prostředků, v proměnných nebo ve výrazech. Tady je příklad objektu:

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

Tento parametr je objekt se dvěma vlastnostmi name řetězce a tiera celočíselnou vlastností . capacity Všimněte si, že každá vlastnost je na vlastním řádku.

Když odkazujete na parametr v šabloně, můžete vybrat jednotlivé vlastnosti objektu pomocí tečky následované názvem vlastnosti, například v tomto příkladu:

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

Důležité

Mějte na paměti, že nezadáte typ každé vlastnosti v rámci objektu. Pokud však použijete hodnotu vlastnosti, musí její typ odpovídat očekávanému nastavení. V předchozím příkladu musí být název i úroveň skladové položky plánu služby App Service řetězce.

Dalším příkladem použití parametru objektu je určení značek prostředků. K nasazeným prostředkům můžete připojit metadata vlastních značek, která můžete použít k identifikaci důležitých informací o prostředku.

Značky jsou užitečné pro scénáře, jako je sledování, který tým vlastní prostředek nebo kdy prostředek patří do produkčního nebo neprodukčního prostředí. Obvykle použijete pro každé prostředí různé značky, ale u všech prostředků v šabloně budete chtít použít stejné hodnoty značek. Z tohoto důvodu jsou značky prostředků vhodné pro parametr objektu, například v tomto příkladu:

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

Pokaždé, když v souboru Bicep definujete prostředek, můžete ho znovu použít všude, kde definujete tags vlastnost:

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

Pole

Pole je seznam položek. Jako příklad můžete k deklaraci seznamu e-mailových adres pro skupinu akcí Azure Monitoru použít pole řetězcových hodnot. Nebo můžete použít pole objektů k reprezentaci seznamu podsítí pro virtuální síť.

Poznámka:

Nelze zadat typ jednotlivých položek, které pole musí obsahovat. Nemůžete například určit, že pole musí obsahovat řetězce.

Zvažte následující příklad. Azure Cosmos DB umožňuje vytvářet databázové účty, které zahrnují více oblastí, a automaticky zpracovává replikaci dat za vás. Když nasadíte nový účet databáze, musíte zadat seznam oblastí Azure, do kterých chcete účet nasadit. Často budete muset mít pro různá prostředí jiný seznam umístění. Pokud například chcete ušetřit peníze v testovacím prostředí, můžete použít pouze jedno nebo dvě místa. V produkčním prostředí ale můžete použít několik umístění.

Můžete vytvořit parametr pole, který určuje seznam umístění:

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

Tip

Předchozí příklad je pole objektů. Každý objekt má locationName vlastnost, kterou služba Azure Cosmos DB očekává. Při práci s definicí prostředku v editoru Visual Studio Code můžete začít zadáním vlastností prostředku, abyste získali IntelliSense z nástrojů Bicep. Pomocí tohoto přístupu můžete vytvořit některé ukázkové hodnoty. Až budete s konfigurací spokojeni, přesuňte tuto část kódu Bicep do parametru. Tímto způsobem můžete nahradit pevně zakódovanou vlastnost parametrem, který lze změnit během každého nasazení, a zároveň zajistit, aby byl prostředek správně nakonfigurovaný.

Když deklarujete prostředek služby Azure Cosmos DB, můžete teď odkazovat na parametr pole:

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

Pro vývojové prostředí je pak snadné použít jinou hodnotu parametru změnou hodnoty parametru. Brzy se dozvíte, jak můžete zadat různé hodnoty parametrů beze změny původní šablony.

Zadání seznamu povolených hodnot

Někdy je potřeba se ujistit, že parametr má určité hodnoty. Váš tým se například může rozhodnout, že produkční plány služby App Service by se měly nasadit pomocí skladových položek Premium v3. K vynucování tohoto pravidla můžete použít @allowed dekorátor parametrů. Dekorátor parametru je způsob, jak poskytnout Bicep informace o tom, co hodnota parametru musí být. Tady je postup, jak lze omezit pojmenovaný appServicePlanSkuName řetězcový parametr, aby bylo možné přiřadit pouze několik konkrétních hodnot:

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

Tip

@allowed Používejte dekorátor střídmě. Pokud tento dekorátor používáte příliš široce, můžete blokovat platná nasazení, pokud seznam neudržíte v aktualizovaném stavu. Předchozí příklad umožňuje pouze skladové položky Premium v3 v produkčním prostředí. Pokud potřebujete použít stejnou šablonu k nasazení některých levnějších neprodukčních prostředí, seznam povolených hodnot vám může zabránit v používání jiných skladových položek, které potřebujete použít.

Omezení délky a hodnot parametrů

Při použití parametrů řetězce často potřebujete omezit délku řetězce. Podívejme se na příklad pojmenování prostředků Azure. Všechny typy prostředků Azure mají omezení kolem délky jejich názvů. Pro parametry, které řídí pojmenování, je vhodné zadat minimální a maximální délku znaků, abyste se vyhnuli chybám později během nasazení. Dekorátory můžete použít @minLength @maxLength na minimální a maximální délku znaků, které chcete pro parametr povolit.

Tady je příklad, který deklaruje řetězcový parametr s názvem storageAccountName, jehož délka může být pouze 5 až 24 znaků:

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

Tento parametr obsahuje dva dekorátory. Více dekorátorů můžete použít u parametru tak, že každý dekorátor umístíte na vlastní řádek.

Poznámka:

Můžete také použít @minLength a @maxLength dekorátory na parametry pole a řídit, kolik položek může být v poli.

Při práci s číselnými parametry může být nutné, aby hodnoty byly v určitém rozsahu. Vaše společnost toy se například může rozhodnout, že pokaždé, když někdo nasadí plán služby App Service, by měl vždy nasadit alespoň jednu instanci, ale ne více než 10 instancí plánu. Ke splnění požadavků můžete použít @minValue a @maxValue dekorátory k určení minimálních a maximálních povolených hodnot. Následující příklad deklaruje celočíselnou hodnotu appServicePlanInstanceCount , jejíž hodnota může být pouze mezi 1 a 10 (včetně):

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

Přidání popisů k parametrům

Parametry představují skvělý způsob, jak vytvořit opakovaně použitelné šablony jinými lidmi. Když používají šablony, musí pochopit, co každý parametr dělá, aby mohl poskytnout správné hodnoty. Bicep poskytuje @description dekorátor, abyste mohli zdokumentovat účel parametrů způsobem čitelným pro člověka.

@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

Osvědčeným postupem je zadat popisy parametrů. Zkuste popisy usnadnit a uveďte všechny důležité informace o tom, co šablona potřebuje, aby hodnoty parametrů byly.

Poznámka:

Šablony Bicep se někdy dají zpřístupnit na webu Azure Portal, aby je mohli uživatelé nasazovat, třeba když používáte specifikace šablon. Portál používá popisy a další dekorátory parametrů, které uživatelům pomůžou pochopit, jaká hodnota parametru musí být.