Tworzenie plików parametrów dla wdrożenia Bicep

  • Artykuł

Zamiast przekazywać parametry jako wartości wbudowane w skrypcie, możesz użyć pliku parametrów Bicep z .bicepparam rozszerzeniem pliku lub plikiem parametrów JSON zawierającym wartości parametrów. W tym artykule pokazano, jak utworzyć pliki parametrów.

Uwaga

Plik parametrów Bicep jest obsługiwany tylko w interfejsie wiersza polecenia Bicep w wersji 0.18.4 lub nowszej, interfejs wiersza polecenia platformy Azure w wersji 2.47.0 lub nowszej oraz program Azure PowerShell w wersji 9.7.1 lub nowszej.

Pojedynczy plik Bicep może zawierać wiele skojarzonych z nim plików parametrów Bicep. Jednak każdy plik parametrów Bicep jest przeznaczony dla jednego konkretnego pliku Bicep. Ta relacja jest ustanawiana przy użyciu instrukcji using w pliku parametrów Bicep.

Pliki parametrów Bicep można skompilować do plików parametrów JSON w celu wdrożenia za pomocą pliku Bicep. Zobacz parametry kompilacji. Można również dekompilować plik parametrów JSON do pliku parametrów Bicep. Zobacz dekompiluj-params.

Plik parametrów

Plik parametrów używa następującego formatu:

using '<path>/<file-name>.bicep'

param <first-parameter-name> = <first-value>
param <second-parameter-name> = <second-value>

Możesz użyć instrukcji using z plikiem Bicep, szablonami JSON usługi ARM, modułami Bicep i specyfikacjami szablonu. Na przykład:

using './main.bicep'
...

using './azuredeploy.json'
...

using 'br/public:storage/storage-account:3.0.1'
...

using 'br:myacr.azurecr.io/bicep/modules/storage:v1'
...

using 'ts:00000000-0000-0000-0000-000000000000/myResourceGroup/storageSpec:1.0'
...

Aby uzyskać więcej informacji, zobacz instrukcję using.

Możesz użyć wyrażeń z wartością domyślną. Na przykład:

using 'main.bicep'

param storageName = toLower('MyStorageAccount')
param intValue = 2 + 2

Zmienne środowiskowe można odwoływać się jako wartości parametrów. Na przykład:

using './main.bicep'

param intFromEnvironmentVariables = int(readEnvironmentVariable('intEnvVariableName'))

Zmienne można definiować i używać. Interfejs wiersza polecenia Bicep w wersji 0.21.X lub nowszej jest wymagany do używania zmiennych w pliku .bicepparam. Oto kilka przykładów:

using './main.bicep'

var storagePrefix = 'myStorage'
param primaryStorageName = '${storagePrefix}Primary'
param secondaryStorageName = '${storagePrefix}Secondary'

using './main.bicep'

var testSettings = {
  instanceSize: 'Small'
  instanceCount: 1
}

var prodSettings = {
  instanceSize: 'Large'
  instanceCount: 4
}

param environmentSettings = {
  test: testSettings
  prod: prodSettings
}

Warto zauważyć, że plik parametrów zapisuje wartości parametrów jako zwykły tekst. Ze względów bezpieczeństwa takie podejście nie jest zalecane w przypadku wartości poufnych, takich jak hasła. Jeśli musisz przekazać parametr z wartością wrażliwą, zachowaj wartość w magazynie kluczy. Zamiast dodawać wartość wrażliwą do pliku parametrów, użyj funkcji getSecret, aby ją pobrać. Aby uzyskać więcej informacji, zobacz Use Azure Key Vault to pass secure parameter value during Bicep deployment (Używanie usługi Azure Key Vault do przekazywania wartości bezpiecznego parametru podczas wdrażania Bicep).

Formaty typów parametrów

W poniższym przykładzie przedstawiono formaty różnych typów parametrów: ciąg, liczba całkowita, wartość logiczna, tablica i obiekt.

using './main.bicep'

param exampleString = 'test string'
param exampleInt = 2 + 2
param exampleBool = true
param exampleArray = [
  'value 1'
  'value 2'
]
param exampleObject = {
  property1: 'value 1'
  property2: 'value 2'
}

Użyj składni Bicep, aby zadeklarować obiekty i tablice.

Nazwa pliku

Plik parametrów Bicep ma rozszerzenie .bicepparampliku .

Aby wdrożyć w różnych środowiskach, należy utworzyć więcej niż jeden plik parametrów. Podczas nadawania nazw plikom parametrów zidentyfikuj ich użycie, takie jak programowanie i produkcja. Na przykład użyj polecenia main.dev.bicepparam i main.prod.bicepparam , aby wdrożyć zasoby.

Definiowanie wartości parametrów

Aby określić sposób definiowania nazw parametrów i wartości, otwórz plik Bicep. Zapoznaj się z sekcją parametrów pliku Bicep. W poniższych przykładach przedstawiono parametry z pliku Bicep o nazwie main.bicep.

@maxLength(11)
param storagePrefix string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
param storageAccountType string = 'Standard_LRS'

W pliku parametrów pierwszą szczegółową informacją jest nazwa każdego parametru. Nazwy parametrów w pliku parametrów muszą być zgodne z nazwami parametrów w pliku Bicep.

using 'main.bicep'

param storagePrefix
param storageAccountType

Instrukcja using łączy plik parametrów Bicep z plikiem Bicep. Aby uzyskać więcej informacji, zobacz using statement (Używanie instrukcji).

Po wpisaniu słowa kluczowego param w programie Visual Studio Code zostanie wyświetlony monit o dostępne parametry i ich opisy z połączonego pliku Bicep:

Zrzut ekranu przedstawiający monit o dostępne parametry.

Po umieszczeniu wskaźnika myszy na nazwie parametru można zobaczyć typ danych parametru i opis.

Zrzut ekranu przedstawiający typ i opis parametru.

Zwróć uwagę na typ parametru. Typy parametrów w pliku parametrów muszą używać tych samych typów co plik Bicep. W tym przykładzie oba typy parametrów są ciągami.

using 'main.bicep'

param storagePrefix = ''
param storageAccountType = ''

Sprawdź plik Bicep pod kątem parametrów z wartością domyślną. Jeśli parametr ma wartość domyślną, możesz podać wartość w pliku parametrów, ale nie jest to wymagane. Wartość pliku parameters zastępuje wartość domyślną pliku Bicep.

using 'main.bicep'

param storagePrefix = '' // This value must be provided.
param storageAccountType = '' // This value is optional. Bicep will use default value if not provided.

Sprawdź dozwolone wartości Bicep i wszelkie ograniczenia, takie jak maksymalna długość. Te wartości określają zakres wartości, które można podać dla parametru. W tym przykładzie storagePrefix może mieć maksymalnie 11 znaków i storageAccountType musi określać dozwoloną wartość.

using 'main.bicep'

param storagePrefix = 'storage'
param storageAccountType = 'Standard_ZRS'

Generowanie pliku parametrów

Aby wygenerować plik parametrów, masz dwie opcje: za pomocą programu Visual Studio Code lub przy użyciu interfejsu wiersza polecenia Bicep. Obie metody umożliwiają uzyskanie pliku parametrów z pliku Bicep. W programie Visual Studio Code zobacz Generowanie pliku parametrów. W interfejsie wiersza polecenia Bicep zobacz Generowanie pliku parametrów.

Plik parametrów kompilacji Bicep

Za pomocą interfejsu wiersza polecenia Bicep można utworzyć plik parametrów Bicep w pliku parametrów JSON. Aby uzyskać więcej informacji, zobacz Plik parametrów kompilacji.

Wdrażanie pliku Bicep z plikiem parametrów

Interfejs wiersza polecenia platformy Azure

Za pomocą interfejsu wiersza polecenia platformy Azure możesz przekazać plik parametrów przy użyciu wdrożenia pliku Bicep.

Za pomocą interfejsu wiersza polecenia platformy Azure w wersji 2.53.0 lub nowszej oraz interfejsu wiersza polecenia Bicep w wersji 0.22.X lub nowszej można wdrożyć plik Bicep, korzystając z pliku parametrów Bicep. W pliku using parametrów Bicep instrukcji nie ma potrzeby podawania --template-file przełącznika podczas określania pliku parametrów Bicep dla przełącznika --parameters .

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --parameters storage.bicepparam

Możesz użyć wbudowanych parametrów i pliku parametrów lokalizacji w tej samej operacji wdrażania. Na przykład:

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --parameters storage.bicepparam \
  --parameters storageAccountType=Standard_LRS

Aby uzyskać więcej informacji, zobacz Deploy resources with Bicep and Azure CLI (Wdrażanie zasobów przy użyciu platformy Bicep i interfejsu wiersza polecenia platformy Azure).

Azure PowerShell

W programie Azure PowerShell przekaż plik parametrów lokalnych przy użyciu parametru TemplateParameterFile .

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile C:\MyTemplates\storage.bicep `
  -TemplateParameterFile C:\MyTemplates\storage.bicepparam

Możesz użyć wbudowanych parametrów i pliku parametrów lokalizacji w tej samej operacji wdrażania. Na przykład:

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile C:\MyTemplates\storage.bicep `
  -TemplateParameterFile C:\MyTemplates\storage.bicepparam `
  -storageAccountType Standard_LRS

Aby uzyskać więcej informacji, zobacz Deploy resources with Bicep and Azure PowerShell (Wdrażanie zasobów za pomocą programu Bicep i programu Azure PowerShell). Aby wdrożyć pliki bicep , potrzebujesz programu Azure PowerShell w wersji 5.6.0 lub nowszej.

Pierwszeństwo parametrów

Możesz użyć wbudowanych parametrów i pliku parametrów lokalnych w tej samej operacji wdrażania. Na przykład można określić niektóre wartości w pliku parametrów lokalnych i dodać inne wartości wbudowane podczas wdrażania. Jeśli podasz wartości parametru zarówno w pliku parametrów lokalnych, jak i wbudowanych, pierwszeństwo ma wartość śródliniowa.

Można użyć zewnętrznego pliku parametrów JSON, podając identyfikator URI do pliku. Plik parametrów Bicep zewnętrznego nie jest obecnie obsługiwany. W przypadku korzystania z pliku parametrów zewnętrznych nie można przekazać innych wartości w tekście ani z pliku lokalnego. Wszystkie parametry wbudowane są ignorowane. Podaj wszystkie wartości parametrów w pliku zewnętrznym.

Konflikty nazw parametrów

Jeśli plik Bicep zawiera parametr o takiej samej nazwie jak jeden z parametrów w poleceniu programu PowerShell, program PowerShell przedstawia parametr z pliku Bicep z postfiksem FromTemplate. Na przykład parametr o nazwie ResourceGroupName w pliku Bicep powoduje konflikt z parametrem ResourceGroupName w poleceniu cmdlet New-AzResourceGroupDeployment . Zostanie wyświetlony monit o podanie wartości .ResourceGroupNameFromTemplate Aby uniknąć tego zamieszania, użyj nazw parametrów, które nie są używane do poleceń wdrażania.

Następne kroki