Parametry w Bicep
W tym artykule opisano sposób definiowania i używania parametrów w pliku Bicep. Podając różne wartości parametrów, można użyć ponownie pliku Bicep dla różnych środowisk.
Usługa Resource Manager rozwiązuje wartości parametrów przed rozpoczęciem operacji wdrażania. Wszędzie tam, gdzie jest używany parametr, usługa Resource Manager zastępuje go rozpoznaną wartością.
Każdy parametr musi być ustawiony na jeden z typów danych.
W pliku Bicep jest ograniczony do 256 parametrów. Aby uzyskać więcej informacji, zobacz Limity szablonów.
Aby uzyskać najlepsze rozwiązania dotyczące parametrów, zobacz Parametry.
Zasoby szkoleniowe
Jeśli wolisz dowiedzieć się więcej o parametrach za pomocą szczegółowych wskazówek, zobacz Tworzenie szablonów Bicep wielokrotnego użytku przy użyciu parametrów.
Deklaracji
Każdy parametr ma nazwę i typ danych. Opcjonalnie możesz podać wartość domyślną parametru .
param <parameter-name> <parameter-data-type> = <default-value>
Parametr nie może mieć takiej samej nazwy jak zmienna, zasób, dane wyjściowe lub inny parametr w tym samym zakresie.
W poniższym przykładzie przedstawiono podstawowe deklaracje parametrów.
param demoString string
param demoInt int
param demoBool bool
param demoObject object
param demoArray array
Słowo param
kluczowe jest również używane w plikach bicepparam. W plikach bicepparam nie trzeba określać typu danych, ponieważ jest on zdefiniowany w plikach Bicep.
param <parameter-name> = <value>
Aby uzyskać więcej informacji, zobacz Plik parametrów.
Wyrażenia typu zdefiniowane przez użytkownika mogą służyć jako klauzula param
typu instrukcji. Na przykład:
param storageAccountConfig {
name: string
sku: string
}
Aby uzyskać więcej informacji, zobacz Typy danych zdefiniowanych przez użytkownika.
Domyślna wartość
Możesz określić wartość domyślną parametru. Wartość domyślna jest używana, gdy wartość nie jest udostępniana podczas wdrażania.
param demoParam string = 'Contoso'
Możesz użyć wyrażeń z wartością domyślną. Wyrażenia nie są dozwolone z innymi właściwościami parametrów. Nie można użyć funkcji referencyjnej ani żadnej funkcji listy w sekcji parameters. Te funkcje pobierają stan środowiska uruchomieniowego zasobu i nie można ich wykonać przed wdrożeniem po rozpoznaniu parametrów.
param location string = resourceGroup().location
Możesz użyć innej wartości parametru, aby utworzyć wartość domyślną. Poniższy szablon tworzy nazwę planu hosta z nazwy witryny.
param siteName string = 'site${uniqueString(resourceGroup().id)}'
param hostingPlanName string = '${siteName}-plan'
output siteNameOutput string = siteName
output hostingPlanOutput string = hostingPlanName
Dekoratory
Parametry używają dekoratorów dla ograniczeń lub metadanych. Dekoratory są w formacie @expression
i są umieszczane powyżej deklaracji parametru. Parametr można oznaczyć jako bezpieczny, określić dozwolone wartości, ustawić minimalną i maksymalną długość ciągu, ustawić minimalną i maksymalną wartość dla liczby całkowitej i podać opis parametru.
W poniższym przykładzie przedstawiono dwa typowe zastosowania dekoratorów.
@secure()
param demoPassword string
@description('Must be at least Standard_A3 to support 2 NICs.')
param virtualMachineSize string = 'Standard_DS1_v2'
W poniższej tabeli opisano dostępne dekoratory i sposób ich używania.
Dekorator | Zastosuj do | Argument | opis |
---|---|---|---|
Dozwolone | wszystkie | tablica | Dozwolone wartości parametru. Użyj tego dekoratora, aby upewnić się, że użytkownik udostępnia poprawne wartości. |
opis | wszystkie | string | Tekst wyjaśniający, jak używać parametru . Opis jest wyświetlany użytkownikom za pośrednictwem portalu. |
Maxlength | tablica, ciąg | int | Maksymalna długość parametrów ciągu i tablicy. Wartość jest inkluzywna. |
Maxvalue | int | int | Maksymalna wartość parametru liczby całkowitej. Ta wartość jest inkluzywna. |
metadane | wszystkie | obiekt | Właściwości niestandardowe, które mają być stosowane do parametru. Może zawierać właściwość opisu, która jest równoważna dekoratorowi opisu. |
Minlength | tablica, ciąg | int | Minimalna długość parametrów ciągu i tablicy. Wartość jest inkluzywna. |
Minvalue | int | int | Minimalna wartość parametru liczby całkowitej. Ta wartość jest inkluzywna. |
Bezpieczne | ciąg, obiekt | Brak | Oznacza parametr jako bezpieczny. Wartość bezpiecznego parametru nie jest zapisywana w historii wdrażania i nie jest rejestrowana. Aby uzyskać więcej informacji, zobacz Zabezpieczanie ciągów i obiektów. |
Dekoratory znajdują się w przestrzeni nazw systemu. Jeśli musisz odróżnić dekorator od innego elementu o tej samej nazwie, należy poprzeć dekorator za pomocą polecenia sys
. Jeśli na przykład plik Bicep zawiera parametr o nazwie description
, należy dodać przestrzeń nazw systemu podczas korzystania z dekoratora opisu .
@sys.description('The name of the instance.')
param name string
@sys.description('The description of the instance to display.')
param description string
Dostępne dekoratory zostały opisane w poniższych sekcjach.
Parametry zabezpieczeń
Parametry ciągu lub obiektu można oznaczyć jako bezpieczne. Wartość bezpiecznego parametru nie jest zapisywana w historii wdrażania i nie jest rejestrowana.
@secure()
param demoPassword string
@secure()
param demoSecretObject object
Dozwolone wartości
Dozwolone wartości parametru można zdefiniować. Dozwolone wartości są podane w tablicy. Wdrożenie kończy się niepowodzeniem podczas walidacji, jeśli wartość jest przekazywana dla parametru, który nie jest jedną z dozwolonych wartości.
@allowed([
'one'
'two'
])
param demoEnum string
Jeśli zdefiniujesz dozwolone wartości dla parametru tablicy, rzeczywista wartość może być dowolnym podzbiorem dozwolonych wartości.
Ograniczenia długości
Można określić minimalną i maksymalną długość parametrów ciągu i tablicy. Można ustawić jedno lub oba ograniczenia. W przypadku ciągów długość wskazuje liczbę znaków. W przypadku tablic długość wskazuje liczbę elementów w tablicy.
Poniższy przykład deklaruje dwa parametry. Jednym z parametrów jest nazwa konta magazynu, która musi mieć od 3 do 24 znaków. Drugi parametr jest tablicą, która musi zawierać od 1 do 5 elementów.
@minLength(3)
@maxLength(24)
param storageAccountName string
@minLength(1)
@maxLength(5)
param appNames array
Ograniczenia liczb całkowitych
Można ustawić wartości minimalne i maksymalne dla parametrów liczb całkowitych. Można ustawić jedno lub oba ograniczenia.
@minValue(1)
@maxValue(12)
param month int
opis
Aby ułatwić użytkownikom zrozumienie wartości do podania, dodaj opis do parametru. Gdy użytkownik wdroży szablon za pośrednictwem portalu, tekst opisu jest automatycznie używany jako porada dla tego parametru. Dodaj opis tylko wtedy, gdy tekst zawiera więcej informacji niż można wywnioskować z nazwy parametru.
@description('Must be at least Standard_A3 to support 2 NICs.')
param virtualMachineSize string = 'Standard_DS1_v2'
Tekst sformatowany w języku Markdown może służyć do tekstu opisu:
@description('''
Storage account name restrictions:
- Storage account names must be between 3 and 24 characters in length and may contain numbers and lowercase letters only.
- Your storage account name must be unique within Azure. No two storage accounts can have the same name.
''')
@minLength(3)
@maxLength(24)
param storageAccountName string
Po umieszczeniu kursora na obiekcie storageAccountName w programie VS Code zobaczysz sformatowany tekst:
Upewnij się, że tekst jest zgodny z prawidłowym formatowaniem języka Markdown; w przeciwnym razie może nie być poprawnie wyświetlany podczas renderowania
Metadane
Jeśli masz właściwości niestandardowe, które chcesz zastosować do parametru, dodaj dekorator metadanych. W metadanych zdefiniuj obiekt z niestandardowymi nazwami i wartościami. Obiekt zdefiniowany dla metadanych może zawierać właściwości dowolnej nazwy i typu.
Możesz użyć tego dekoratora do śledzenia informacji o parametrze, który nie ma sensu dodawać do opisu.
@description('Configuration values that are applied when the application starts.')
@metadata({
source: 'database'
contact: 'Web team'
})
param settings object
Po podaniu dekoratora @metadata()
z właściwością, która powoduje konflikt z innym dekoratorem, dekorator zawsze ma pierwszeństwo przed wszystkimi elementami w dekoratorze @metadata()
. Dlatego właściwość powodująca konflikt w ramach @metadata() wartości jest nadmiarowa i zostanie zamieniona. Aby uzyskać więcej informacji, zobacz Brak powodujących konflikt metadanych.
Użyj parametru
Aby odwołać się do wartości parametru, użyj nazwy parametru. W poniższym przykładzie użyto wartości parametru dla nazwy magazynu kluczy.
param vaultName string = 'keyVault${uniqueString(resourceGroup().id)}'
resource keyvault 'Microsoft.KeyVault/vaults@2019-09-01' = {
name: vaultName
...
}
Obiekty jako parametry
Łatwiej jest organizować powiązane wartości, przekazując je jako obiekt. Takie podejście zmniejsza również liczbę parametrów w szablonie.
W poniższym przykładzie przedstawiono parametr, który jest obiektem. Wartość domyślna zawiera oczekiwane właściwości obiektu. Te właściwości są używane podczas definiowania zasobu do wdrożenia.
param vNetSettings object = {
name: 'VNet1'
location: 'eastus'
addressPrefixes: [
{
name: 'firstPrefix'
addressPrefix: '10.0.0.0/22'
}
]
subnets: [
{
name: 'firstSubnet'
addressPrefix: '10.0.0.0/24'
}
{
name: 'secondSubnet'
addressPrefix: '10.0.1.0/24'
}
]
}
resource vnet 'Microsoft.Network/virtualNetworks@2020-06-01' = {
name: vNetSettings.name
location: vNetSettings.location
properties: {
addressSpace: {
addressPrefixes: [
vNetSettings.addressPrefixes[0].addressPrefix
]
}
subnets: [
{
name: vNetSettings.subnets[0].name
properties: {
addressPrefix: vNetSettings.subnets[0].addressPrefix
}
}
{
name: vNetSettings.subnets[1].name
properties: {
addressPrefix: vNetSettings.subnets[1].addressPrefix
}
}
]
}
}
Następne kroki
- Aby dowiedzieć się więcej o dostępnych właściwościach parametrów, zobacz Omówienie struktury i składni plików Bicep.
- Aby dowiedzieć się więcej o przekazywaniu wartości parametrów jako pliku, zobacz Create a Bicep parameter file (Tworzenie pliku parametrów Bicep).
- Aby dowiedzieć się więcej o dostarczaniu wartości parametrów we wdrożeniu, zobacz Wdrażanie przy użyciu interfejsu wiersza polecenia platformy Azure i Wdrażanie przy użyciu programu Azure PowerShell.