Udostępnij za pośrednictwem

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.

Bicep umożliwia maksymalnie 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.

Definiuj parametry

Każdy parametr ma nazwę i typ danych. Opcjonalnie możesz podać wartość domyślną parametru .

@<decorator>(<argument>)
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.

Ustawianie wartości domyślnych

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

Nie można jednak odwołać się do zmiennej jako wartości domyślnej.

Korzystanie z dekoratorów

Parametry używają dekoratorów dla ograniczeń lub metadanych. Dekoratory są w formacie @expression i są umieszczane powyżej deklaracji parametru. W poniższej tabeli przedstawiono dostępne dekoratory parametrów.

Dekorator Zastosuj do Argument opis
Dozwolone wszystkie tablica Użyj tego dekoratora, aby upewnić się, że użytkownik udostępnia poprawne wartości. Ten dekorator jest dozwolony tylko w param instrukcjach. Aby zadeklarować, że właściwość musi być jednym z zestawu wstępnie zdefiniowanych wartości w type instrukcji lub output , użyj składni typu unii. Składnia typu unii może być również używana w param instrukcjach.
opis wszystkie string Tekst wyjaśniający, jak używać parametru . Opis jest wyświetlany użytkownikom za pośrednictwem portalu.
Rozróżniacza obiekt string Użyj tego dekoratora, aby upewnić się, że prawidłowa podklasa jest identyfikowana i zarządzana. Aby uzyskać więcej informacji, zobacz Custom-tagged union data type (Typ danych unii z tagiem niestandardowym).
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.
sealed obiekt Brak Podnieś poziom BCP089 z ostrzeżenia do błędu, gdy nazwa właściwości typu danych use-define jest prawdopodobnie literówką. Aby uzyskać więcej informacji, zobacz Podnoszenie poziomu błędu.
zabezpieczyć 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

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.

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 po renderowaniu może być wyświetlany niepoprawnie.

Rozróżniacza

Zobacz Typ danych unii otagowanych niestandardowych tagach.

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

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

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.

Zamknięte

Zobacz Podnoszenie poziomu błędu.

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

Istnieje kilka reguł linter związanych z tym dekoratorem: Ustawienie domyślne bezpiecznego parametru, Bezpieczne parametry we wdrożeniach zagnieżdżonych, Zabezpieczanie wpisów tajnych w parametrach.

Używanie parametrów

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

Używanie obiektów jako parametrów

Ł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@2023-11-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