Parametry w Bicep

  • Artykuł

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:

Używanie tekstu w formacie Markdown w programie VSCode

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