Tworzenie pliku parametrów dla wdrożenia Bicep

Pliki parametrów Bicep umożliwiają definiowanie wartości parametrów w osobnym pliku i przekazywanie ich do pliku main.bicep. Doskonale nadają się do wartości, które różnią się w zależności od subskrypcji, środowiska lub regionu.

Najważniejsze korzyści to:

• Zachowaj spójność wdrożeń infrastruktury jako kodu (IaC), jednocześnie zapewniając elastyczność.
• Obsługa optymalizacji kosztów, takich jak odpowiednie określanie rozmiaru środowisk nieprodukcyjnych bez zmieniania podstawowej infrastruktury.
• Usprawnij potoki CI/CD, przechowując pliki parametrów w systemie kontroli wersji i przekazując odpowiedni plik do każdego etapu wdrażania.

Uwaga

Pliki parametrów Bicep są obsługiwane tylko w Bicep CLI w wersji 0.18.4 lub nowszej, Azure CLI w wersji 2.47.0 lub nowszej oraz Azure PowerShell w wersji 9.7.1 lub nowszej.

Możesz użyć jednej z następujących opcji:

• Natywny plik parametrów Bicep (z rozszerzeniem .bicepparam) lub
• Standardowy plik parametrów JSON.

Plik parametrów Bicep

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

Aby wdrożyć w wielu środowiskach, utwórz 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 ma nazwę azuredeploy.bicep nadaj plikowi parametrów nazwę azuredeploy.parameters.json. Ta konwencja nazewnictwa pomaga zobaczyć połączenie między plikiem Bicep i parametrami.

Aby wdrożyć w różnych środowiskach, utwórz 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.

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.

Warning

Plik parametrów zapisuje wartości parametrów jako zwykły tekst. Ze względów bezpieczeństwa nie należy używać tego podejścia z poufnymi wartościami, takimi jak hasła. Jeśli musisz przekazać parametr z wartością poufną, przechowuj ją w sejfie 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 tajnego klucza jako parametru podczas wdrażania Bicep.

Definiowanie pliku parametrów

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

Plik parametrów Bicep

using '<path>/<file-name>.bicep' | using none
extends '<path>/<file-name>.bicepparam' 

type <user-defined-data-type-name> = <type-expression>

var <variable-name> <data-type> = <variable-value>

import {<symbol_name> [as <alias_name>], ...} from '<bicep_file_name>'

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

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

Aby określić sposób definiowania nazw parametrów i wartości, otwórz plik Bicep. Spójrz na 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 użyj nazwy 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. Można skojarzyć wiele plików parametrów z jednym plikiem Bicep. Każdy plik parametrów zwykle łączy się z określonym plikiem Bicep przy użyciu instrukcji using.

Użyj using none, jeśli nie chcesz połączyć pliku parametrów z określonym plikiem Bicep. Interfejs wiersza polecenia Bicep w wersji 0.31.0 lub nowszej obsługuje funkcję using none.

Aby uzyskać więcej informacji, zobacz Using statement.

Instrukcja extends dziedziczy parametry z pliku podstawowego .bicepparam , dzięki czemu wartości parametrów mogą być ponownie używane i selektywnie zastępowane w bieżącym pliku parametrów. Aby uzyskać więcej informacji, zobacz Rozszerzanie plików parametrów.

Po wpisaniu słowa kluczowego param w programie Visual Studio Code zostaną wyświetlone dostępne parametry i ich opisy 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 musisz tego robić. 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ć funkcji // 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.

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.

Wyrażenia można używać jako wartości parametrów. Na przykład:

using './main.bicep'

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

Zmienne środowiskowe można wykorzystać jako wartości parametrów. Na przykład:

using './main.bicep'

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

Zmienne można definiować i używać. Musisz użyć Bicep CLI w wersji 0.21.X lub nowszej, aby używać zmiennych w .bicepparam plikach. 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
}

Można zdefiniować typy danych zdefiniowane przez użytkownika. Na przykład:

using './main.bicep'

// Define a reusable type for tags with optional properties
type TagValues = {
  environment: 'dev' | 'test' | 'production'
  project: string
}

var tagsExample TagValues = {
  environment: 'dev'
  project: 'bicep-sample'
}

param tags = tagsExample

Można również importować zmienne, typy danych zdefiniowane przez użytkownika i funkcje definiowane przez użytkownika z pliku Bicep. Aby uzyskać więcej informacji, zobacz Importowanie.

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

Plik parametrów z możliwością rozszerzenia

Aby uzyskać szczegółowe informacje, zobacz Rozszerzanie pliku parametrów.

Generowanie i kompilowanie 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 metodą Visual Studio Code i Generowanie pliku parametrów metodą Bicep CLI.

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.

Wdróż plik Bicep z plikiem 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 w tekście, wartość podana w tekście ma pierwszeństwo.

Mimo że zewnętrzne pliki parametrów Bicep nie są obecnie obsługiwane, można użyć zewnętrznego pliku parametrów JSON, podając 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 formie wbudowanej ani z pliku lokalnego, a wszystkie parametry w formie wbudowanej są ignorowane.

Poniższy przykład przedstawia przykład użycia interfejsu wiersza polecenia platformy Azure z użyciem zewnętrznego pliku parametrów w formacie JSON:

az deployment group create \
  --resource-group my-rg \
  --template-file main.bicep \
  --parameters https://storageaccount.blob.core.windows.net/templates/main.parameters.json

Azure CLI

W Azure CLI możesz przekazać plik parametrów przy wdrożeniu 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. Używając instrukcji using w pliku parametrów Bicep, nie trzeba podawać przełącznika --template-file podczas określania pliku parametrów Bicep za pomocą 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 za pomocą programu Azure PowerShell. Aby wdrożyć .bicep pliki, potrzebujesz programu Azure PowerShell w wersji 5.6.0 lub nowszej.

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, zostaniesz poproszony o podanie wartości dla 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.