Tworzenie pliku parametrów dla wdrożenia Bicep

W tym artykule pokazano, jak utworzyć plik parametrów, którego można użyć zamiast przekazywania parametrów jako wartości wbudowanych w skrycie. Możesz użyć pliku parametrów Bicep z .bicepparam rozszerzeniem pliku lub plikiem parametrów JSON zawierającym wartość parametru.

Uwaga

Pliki parametrów Bicep są obsługiwane 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. Tę relację można ustanowić, stosując instrukcję using w pliku parametrów Bicep.

Pliki parametrów Bicep można skompilować do plików parametrów JSON, które można wdrożyć przy użyciu pliku Bicep. Aby uzyskać więcej informacji, zobacz build-params. Można również dekompilować plik parametrów JSON do pliku parametrów Bicep. Aby uzyskać więcej informacji, zobacz decompile-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>

Instrukcję using można zastosować przy użyciu pliku Bicep, szablonów usługi Azure Resource Manager JSON, modułów Bicep i specyfikacji 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 Using statement (Używanie instrukcji).

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ć. Aby używać zmiennych w plikach, należy użyć interfejsu wiersza polecenia Bicep w .bicepparam wersji 0.21.X lub nowszej. Zobacz poniższe przykłady:

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

Uwaga

Plik parametrów zapisuje wartości parametrów jako zwykły tekst. Ze względów bezpieczeństwa nie zalecamy używania tego podejścia z poufnymi wartościami, takimi jak hasła.

Jeśli musisz przekazać parametr z wartością wrażliwą, należy zachować wartość w magazynie kluczy. Zamiast dodawać wartość wrażliwą do pliku parametrów, użyj getSecret funkcji , aby ją pobrać. Aby uzyskać więcej informacji, zobacz Używanie usługi Azure Key Vault do przekazywania wpisu tajnego jako 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

Rozszerzenie pliku dla pliku parametrów Bicep to .bicepparam.

Aby wdrożyć w wielu środowiskach, należy utworzyć więcej niż jeden plik parametrów. Jeśli używasz wielu plików parametrów, oznacz je etykietą zgodnie z ich użyciem. Aby na przykład wdrożyć zasoby, użyj etykiety main.dev.bicepparam na potrzeby programowania i etykiety main.prod.bicepparam dla środowiska produkcyjnego.

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. Jeśli używasz wielu plików parametrów, oznacz je etykietą zgodnie z ich użyciem. Aby na przykład wdrożyć zasoby, użyj etykiety azuredeploy.parameters-dev.json do programowania i etykiety azuredeploy.parameters-prod.json dla środowiska produkcyjnego.

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 parameters wyszukaj nazwę 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 wpiseniu słowa kluczowego param w programie Visual Studio Code zostanie wyświetlony monit o podanie dostępnych parametrów i ich opisów z połączonego pliku Bicep.

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

Plik parametrów JSON

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

Przejrzyj typ parametru, ponieważ 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, które zawierają wartość 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 uses 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 uses 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 JSONC pliku. Jeśli tego nie zrobisz, zostanie wyświetlony komunikat o błędzie z komunikatem "Komentarze niedozwolone w formacie JSON".

Aby sprawdzić, czy istnieją jakiekolwiek ograniczenia, takie jak maksymalna długość, sprawdź dozwolone wartości pliku Bicep. Dozwolone 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

Plik parametrów można utworzyć przy użyciu programu Visual Studio Code lub interfejsu wiersza polecenia Bicep. Oba narzędzia umożliwiają generowanie pliku parametrów przy użyciu pliku Bicep. Zobacz Generowanie pliku parametrów dla metody programu Visual Studio Code i Generowanie pliku parametrów dla metody interfejsu wiersza polecenia Bicep.

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

Z poziomu interfejsu wiersza polecenia platformy Azure możesz przekazać plik parametrów z wdrożeniem pliku Bicep.

Plik parametrów Bicep

Plik Bicep można wdrożyć przy użyciu pliku parametrów Bicep z interfejsem wiersza polecenia platformy Azure w wersji 2.53.0 lub nowszej oraz interfejsu wiersza polecenia Bicep w wersji 0.22.X lub nowszej. 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 Wdrażanie plików Bicep przy użyciu 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 Wdrażanie plików Bicep przy użyciu programu Azure PowerShell. Aby wdrożyć .bicep pliki, 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.

Mimo że pliki parametrów Bicep zewnętrznych nie są obecnie obsługiwane, można użyć zewnętrznego pliku parametrów JSON, podając identyfikator URI do pliku. Jeśli używasz pliku parametrów zewnętrznych, podaj wszystkie wartości parametrów w pliku zewnętrznym. W przypadku korzystania z pliku zewnętrznego nie można przekazać innych wartości w tekście ani z pliku lokalnego, a wszystkie parametry wbudowane są ignorowane.

Konflikty nazw parametrów

Jeśli plik Bicep zawiera parametr o takiej samej nazwie jak jeden z parametrów w poleceniu programu Azure PowerShell, program Azure PowerShell przedstawia parametr z pliku Bicep z postfiksem FromTemplate . Jeśli na przykład parametr o nazwie ResourceGroupName w pliku Bicep powoduje konflikt z parametrem ResourceGroupName w poleceniu New-AzResourceGroupDeployment cmdlet, 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.

Powiązana zawartość

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