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

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:

Plik parametrów Bicep

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:avm/res/storage/storage-account:0.9.0' 
...

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
}

Plik parametrów JSON

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "<first-parameter-name>": {
      "value": "<first-value>"
    },
    "<second-parameter-name>": {
      "value": "<second-value>"
    }
  }
}

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.

Plik parametrów Bicep

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.

Plik parametrów JSON

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "exampleString": {
      "value": "test string"
    },
    "exampleInt": {
      "value": 4
    },
    "exampleBool": {
      "value": true
    },
    "exampleArray": {
      "value": [
        "value 1",
        "value 2"
      ]
    },
    "exampleObject": {
      "value": {
        "property1": "value1",
        "property2": "value2"
      }
    }
  }
}

Nazwa pliku

Plik parametrów Bicep

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.

Plik parametrów JSON

Ogólna konwencja nazewnictwa pliku parametrów polega na dołączeniu parametrów w nazwie pliku Bicep. Jeśli na przykład plik Bicep nosi nazwę azuredeploy.bicep, plik parametrów nosi nazwę azuredeploy.parameters.json. Ta konwencja nazewnictwa pomaga zobaczyć połączenie między plikiem Bicep i parametrami.

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 azuredeploy.parameters-dev.json i azuredeploy.parameters-prod.json , 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.

Plik parametrów 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:

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

Plik parametrów JSON

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
    },
    "storageAccountType": {
    }
  }
}

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.

Plik parametrów Bicep

using 'main.bicep'

param storagePrefix = ''
param storageAccountType = ''

Plik parametrów JSON

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
      "value": ""
    },
    "storageAccountType": {
      "value": ""
    }
  }
}

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.

Plik parametrów 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.

Plik parametrów JSON

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
      "value": "" // This value must be provided.
    },
    "storageAccountType": {
      "value": "" // This value is optional. Bicep will use default value if not provided.
    }
  }
}

Uwaga

W przypadku komentarzy wbudowanych można użyć // lub /* ... */. W programie Visual Studio Code zapisz pliki parametrów z typem pliku JSONC . W przeciwnym razie zostanie wyświetlony komunikat o błędzie z komunikatem "Komentarze niedozwolone w formacie JSON".

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ść.

Plik parametrów Bicep

using 'main.bicep'

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

Plik parametrów JSON

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
      "value": "storage"
    },
    "storageAccountType": {
      "value": "Standard_ZRS"
    }
  }
}

Uwaga

Plik parametrów może zawierać tylko wartości parametrów zdefiniowanych w pliku Bicep. Jeśli plik parametrów zawiera dodatkowe parametry, które nie są zgodne z parametrami pliku Bicep, zostanie wyświetlony błąd.

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.

Plik parametrów 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

Plik parametrów JSON

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.bicep \
  --parameters storage.parameters.json

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

Plik parametrów Bicep

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

Plik parametrów JSON

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.bicep \
  --parameters storage.parameters.json \
  --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 .

Plik parametrów Bicep

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

Plik parametrów JSON

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

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

Plik parametrów Bicep

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

Plik parametrów JSON

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile C:\MyTemplates\storage.bicep `
  -TemplateParameterFile C:\MyTemplates\storage.parameters.json `
  -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

• Aby uzyskać więcej informacji na temat definiowania parametrów w pliku Bicep, zobacz Parametry w Bicep.
• Aby uzyskać poufne wartości, zobacz Używanie usługi Azure Key Vault do przekazywania bezpiecznej wartości parametru podczas wdrażania.