Omówienie struktury i składni plików Bicep

Artykuł
11/05/2024

W tym artykule opisano strukturę i składnię pliku Bicep. Przedstawia on różne sekcje pliku i właściwości, które są dostępne w tych sekcjach.

Aby zapoznać się z samouczkiem krok po kroku, który przeprowadzi Cię przez proces tworzenia pliku Bicep, zobacz Szybki start: tworzenie plików Bicep za pomocą programu Visual Studio Code.

Format Bicep

Bicep to język deklaratywny, co oznacza, że elementy mogą pojawiać się w dowolnej kolejności. W przeciwieństwie do języków imperatywnych kolejność elementów nie ma wpływu na sposób przetwarzania wdrożenia.

Plik Bicep zawiera następujące elementy.

@<decorator>(<argument>)
metadata <metadata-name> = ANY

targetScope = '<scope>'

@<decorator>(<argument>)
type <user-defined-data-type-name> = <type-expression>

@<decorator>(<argument>)
func <user-defined-function-name> (<argument-name> <data-type>, <argument-name> <data-type>, ...) <function-data-type> => <expression>

@<decorator>(<argument>)
param <parameter-name> <parameter-data-type> = <default-value>

@<decorator>(<argument>)
var <variable-name> = <variable-value>

@<decorator>(<argument>)
resource <resource-symbolic-name> '<resource-type>@<api-version>' = {
  <resource-properties>
}

@<decorator>(<argument>)
module <module-symbolic-name> '<path-to-file>' = {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
}

@<decorator>(<argument>)
output <output-name> <output-data-type> = <output-value>

Poniższy przykład przedstawia implementację tych elementów.

metadata description = 'Creates a storage account and a web app'

@description('The prefix to use for the storage account name.')
@minLength(3)
@maxLength(11)
param storagePrefix string

param storageSKU string = 'Standard_LRS'
param location string = resourceGroup().location

var uniqueStorageName = '${storagePrefix}${uniqueString(resourceGroup().id)}'

resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

module webModule './webApp.bicep' = {
  name: 'webDeploy'
  params: {
    skuName: 'S1'
    location: location
  }
}

Metadane

Metadane w Bicep to nietypowa wartość, którą można uwzględnić w plikach Bicep. Umożliwia ona podanie dodatkowych informacji na temat plików Bicep, w tym szczegółów, takich jak jego nazwa, opis, autor, data utworzenia i nie tylko.

Zakres docelowy

Domyślnie zakres docelowy jest ustawiony na resourceGroupwartość . Jeśli wdrażasz na poziomie grupy zasobów, nie musisz ustawiać zakresu docelowego w pliku Bicep.

Dozwolone wartości to:

resourceGroup — wartość domyślna używana dla wdrożeń grup zasobów.
subskrypcja — używana do wdrożeń subskrypcji.
managementGroup — służy do wdrożeń grup zarządzania.
dzierżawa — używana na potrzeby wdrożeń dzierżawy.

W module można określić zakres inny niż zakres pozostałej części pliku Bicep. Aby uzyskać więcej informacji, zobacz Konfigurowanie zakresu modułu

Dekoratory

Dla każdego z następujących elementów można dodać co najmniej jeden dekorator:

Param
var
zasób
module
wyjście
func
type

Dekoratory obejmują:

Dekorator	Zastosuj do elementu	Zastosuj do typu danych	Argument	opis
Dozwolone	Param	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.
batchSize	moduł, zasób	Nie dotyczy	integer	Konfigurowanie wystąpień w celu sekwencyjnego wdrażania.
opis	func, param, module, output, resource, type, var	wszystkie	string	Podaj opisy elementów. Tekst w formacie markdown może służyć do tekstu opisu.
Rozróżniacza	param, typ, dane wyjściowe	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).
eksportowanie	func, type, var	wszystkie	Brak	Wskazuje, że element może zostać zaimportowany przez inny plik Bicep.
maxLength	param, output, type	tablica, ciąg	int	Maksymalna długość ciągu i elementów tablicy. Wartość jest inkluzywna.
maxValue	param, output, type	int	int	Maksymalna wartość dla elementów całkowitych. Ta wartość jest inkluzywna.
metadane	func, output, param, type	wszystkie	obiekt	Właściwości niestandardowe, które mają być stosowane do elementów. Może zawierać właściwość opisu, która jest równoważna dekoratorowi opisu.
minLength	param, output, type	tablica, ciąg	int	Minimalna długość elementów ciągu i tablicy. Wartość jest inkluzywna.
minValue	param, output, type	int	int	Minimalna wartość dla elementów całkowitych. Ta wartość jest inkluzywna.
sealed	param, typ, dane wyjściowe	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.
bezpieczeństwo	param, typ	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.

Parametry

Użyj parametrów dla wartości, które muszą się różnić w przypadku różnych wdrożeń. Można zdefiniować wartość domyślną parametru, który jest używany, jeśli podczas wdrażania nie podano żadnej wartości.

Możesz na przykład dodać parametr jednostki SKU, aby określić różne rozmiary zasobu. Możesz przekazać różne wartości w zależności od tego, czy wdrażasz w środowisku testowym, czy produkcyjnym.

param storageSKU string = 'Standard_LRS'

Parametr jest dostępny do użycia w pliku Bicep.

sku: {
  name: storageSKU
}

Dla każdego parametru można dodać co najmniej jeden dekorator. Aby uzyskać więcej informacji, zobacz Use decorators (Używanie dekoratorów).

Aby uzyskać więcej informacji, zobacz Parametry w Bicep.

Zmienne

Plik Bicep może być bardziej czytelny, hermetyzując złożone wyrażenia w zmiennej. Możesz na przykład dodać zmienną dla nazwy zasobu, która jest tworzona przez połączenie kilku wartości.

var uniqueStorageName = '${storagePrefix}${uniqueString(resourceGroup().id)}'

Zastosuj tę zmienną wszędzie tam, gdzie potrzebne jest wyrażenie złożone.

resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: uniqueStorageName

Dla każdej zmiennej można dodać co najmniej jeden dekorator. Aby uzyskać więcej informacji, zobacz Use decorators (Używanie dekoratorów).

Aby uzyskać więcej informacji, zobacz Zmienne w Bicep.

Typy

Instrukcję type można użyć do zdefiniowania typów danych zdefiniowanych przez użytkownika.

param location string = resourceGroup().location

type storageAccountSkuType = 'Standard_LRS' | 'Standard_GRS'

type storageAccountConfigType = {
  name: string
  sku: storageAccountSkuType
}

param storageAccountConfig storageAccountConfigType = {
  name: 'storage${uniqueString(resourceGroup().id)}'
  sku: 'Standard_LRS'
}

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: storageAccountConfig.name
  location: location
  sku: {
    name: storageAccountConfig.sku
  }
  kind: 'StorageV2'
}

Można dodać co najmniej jeden dekorator dla każdego typu danych zdefiniowanego przez użytkownika. Aby uzyskać więcej informacji, zobacz Use decorators (Używanie dekoratorów).

Aby uzyskać więcej informacji, zobacz Typy danych zdefiniowanych przez użytkownika.

Funkcje

W pliku Bicep możesz utworzyć własne funkcje oprócz używania standardowych funkcji Bicep, które są automatycznie dostępne w plikach Bicep. Utwórz własne funkcje, gdy masz skomplikowane wyrażenia, które są używane wielokrotnie w plikach Bicep.

func buildUrl(https bool, hostname string, path string) string => '${https ? 'https' : 'http'}://${hostname}${empty(path) ? '' : '/${path}'}'

output azureUrl string = buildUrl(true, 'microsoft.com', 'azure')

Aby uzyskać więcej informacji, zobacz Funkcje zdefiniowane przez użytkownika.

Zasoby

Użyj słowa kluczowego resource , aby zdefiniować zasób do wdrożenia. Deklaracja zasobu zawiera symboliczną nazwę zasobu. Ta nazwa symboliczna jest używana w innych częściach pliku Bicep, aby uzyskać wartość z zasobu.

Deklaracja zasobu zawiera typ zasobu i wersję interfejsu API. W treści deklaracji zasobu dołącz właściwości specyficzne dla typu zasobu.

resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

Dla każdego zasobu można dodać co najmniej jeden dekorator. Aby uzyskać więcej informacji, zobacz Use decorators (Używanie dekoratorów).

Aby uzyskać więcej informacji, zobacz Deklarację zasobu w Bicep.

Niektóre zasoby mają relację nadrzędny/podrzędny. Zasób podrzędny można zdefiniować wewnątrz zasobu nadrzędnego lub poza nim.

W poniższym przykładzie pokazano, jak zdefiniować zasób podrzędny w ramach zasobu nadrzędnego. Zawiera konto magazynu z podrzędnym zasobem (usługą plików) zdefiniowanym na koncie magazynu. Usługa plików ma również zasób podrzędny (udział), który jest w nim zdefiniowany.

resource storage 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: 'examplestorage'
  location: resourceGroup().location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_LRS'
  }

  resource service 'fileServices' = {
    name: 'default'

    resource share 'shares' = {
      name: 'exampleshare'
    }
  }
}

W następnym przykładzie pokazano, jak zdefiniować zasób podrzędny poza zasobem nadrzędnym. Właściwość nadrzędna służy do identyfikowania relacji nadrzędny/podrzędny. Zdefiniowano te same trzy zasoby.

resource storage 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: 'examplestorage'
  location: resourceGroup().location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_LRS'
  }
}

resource service 'Microsoft.Storage/storageAccounts/fileServices@2023-04-01' = {
  name: 'default'
  parent: storage
}

resource share 'Microsoft.Storage/storageAccounts/fileServices/shares@2023-04-01' = {
  name: 'exampleshare'
  parent: service
}

Aby uzyskać więcej informacji, zobacz Ustawianie nazwy i typu dla zasobów podrzędnych w Bicep.

Moduły

Moduły umożliwiają ponowne użycie kodu z pliku Bicep w innych plikach Bicep. W deklaracji modułu połączysz się z plikiem w celu ponownego użycia. Podczas wdrażania pliku Bicep zasoby w module są również wdrażane.

module webModule './webApp.bicep' = {
  name: 'webDeploy'
  params: {
    skuName: 'S1'
    location: location
  }
}

Nazwa symboliczna umożliwia odwołanie się do modułu z innego miejsca w pliku. Na przykład możesz uzyskać wartość wyjściową z modułu przy użyciu nazwy symbolicznej i nazwy wartości wyjściowej.

Dla każdego modułu można dodać co najmniej jeden dekorator. Aby uzyskać więcej informacji, zobacz Use decorators (Używanie dekoratorów).

Aby uzyskać więcej informacji, zobacz Use Bicep modules (Używanie modułów Bicep).

Dane wyjściowe

Użyj danych wyjściowych, aby zwrócić wartości z wdrożenia. Zazwyczaj zwracana jest wartość z wdrożonego zasobu, gdy trzeba ponownie użyć tej wartości dla innej operacji.

output storageEndpoint object = stg.properties.primaryEndpoints

Dla każdego wyjścia można dodać co najmniej jeden dekorator. Aby uzyskać więcej informacji, zobacz Use decorators (Używanie dekoratorów).

Aby uzyskać więcej informacji, zobacz Dane wyjściowe w Bicep.

Pętle

Możesz dodać pętle iteracyjne do pliku Bicep, aby zdefiniować wiele kopii elementu:

zasób
moduł
zmienna
właściwość
output

Użyj wyrażenia, for aby zdefiniować pętlę.

param moduleCount int = 2

module stgModule './example.bicep' = [for i in range(0, moduleCount): {
  name: '${i}deployModule'
  params: {
  }
}]

Można iterować na tablicy, obiektu lub indeksu całkowitego.

Aby uzyskać więcej informacji, zobacz Iteracyjne pętle w Bicep.

Wdrożenie warunkowe

Możesz dodać zasób lub moduł do pliku Bicep, który jest wdrażany warunkowo. Podczas wdrażania warunek jest oceniany, a wynik określa, czy zasób lub moduł został wdrożony. Użyj wyrażenia , if aby zdefiniować wdrożenie warunkowe.

param deployZone bool

resource dnsZone 'Microsoft.Network/dnsZones@2023-07-01-preview' = if (deployZone) {
  name: 'myZone'
  location: 'global'
}

Aby uzyskać więcej informacji, zobacz Wdrażanie warunkowe w aplikacji Bicep.

Whitespace

Spacje i karty są ignorowane podczas tworzenia plików Bicep.

Bicep jest wrażliwy na nową linię. Na przykład:

resource sa 'Microsoft.Storage/storageAccounts@2023-04-01' = if (newOrExisting == 'new') {
  ...
}

Nie można napisać jako:

resource sa 'Microsoft.Storage/storageAccounts@2023-04-01' =
    if (newOrExisting == 'new') {
      ...
    }

Zdefiniuj obiekty i tablice w wielu wierszach.

Komentarze

Służy // do komentarzy jednowierszowych lub /* ... */ komentarzy wielowierszowych

W poniższym przykładzie przedstawiono komentarz jednowierszowy.

// This is your primary NIC.
resource nic1 'Microsoft.Network/networkInterfaces@2023-11-01' = {
  ...
}

W poniższym przykładzie przedstawiono komentarz wielowierszowy.

/*
  This Bicep file assumes the key vault already exists and
  is in same subscription and resource group as the deployment.
*/
param existingKeyVaultName string

Ciągi wielowierszowe

Ciąg można podzielić na wiele wierszy. Użyj trzech znaków ''' pojedynczego cudzysłowu, aby rozpocząć i zakończyć ciąg wielowierszowy.

Znaki w ciągu wielowierszowym są obsługiwane tak, jak to jest. Znaki ucieczki są niepotrzebne. Nie można uwzględnić ''' w ciągu wielowierszowym. Interpolacja ciągów nie jest obecnie obsługiwana.

Możesz uruchomić ciąg bezpośrednio po otwarciu ''' lub dołączyć nowy wiersz. W obu przypadkach wynikowy ciąg nie zawiera nowego wiersza. W zależności od zakończenia wiersza w pliku Bicep nowe wiersze są interpretowane jako \r\n lub \n.

W poniższym przykładzie przedstawiono ciąg wielowierszowy.

var stringVar = '''
this is multi-line
  string with formatting
  preserved.
'''

Powyższy przykład jest odpowiednikiem następującego kodu JSON.

"variables": {
  "stringVar": "this is multi-line\r\n  string with formatting\r\n  preserved.\r\n"
}

Deklaracje wielowierszowe

Teraz można używać wielu wierszy w deklaracjach funkcji, tablicy i obiektów. Ta funkcja wymaga interfejsu wiersza polecenia Bicep w wersji 0.7.X lub nowszej.

W poniższym przykładzie definicja jest podzielona resourceGroup() na wiele wierszy.

var foo = resourceGroup(
  mySubscription,
  myRgName)

Zobacz Tablice i obiekty, aby zapoznać się z przykładami deklaracji wielowierszowych.

Znane ograniczenia

Brak obsługi koncepcji apiProfile, która służy do mapowania pojedynczego elementu apiProfile na zestaw apiVersion dla każdego typu zasobu.
Funkcje zdefiniowane przez użytkownika nie są obecnie obsługiwane. Jednak funkcja eksperymentalna jest obecnie dostępna. Aby uzyskać więcej informacji, zobacz Funkcje zdefiniowane przez użytkownika w Bicep.
Niektóre funkcje Bicep wymagają odpowiedniej zmiany języka pośredniego (szablony JSON usługi Azure Resource Manager). Ogłaszamy te funkcje jako dostępne, gdy wszystkie wymagane aktualizacje zostały wdrożone na globalnej platformie Azure. Jeśli używasz innego środowiska, takiego jak usługa Azure Stack, może wystąpić opóźnienie w dostępności funkcji. Funkcja Bicep jest dostępna tylko wtedy, gdy język pośredni został również zaktualizowany w tym środowisku.

Następne kroki

Aby zapoznać się z wprowadzeniem do Bicep, zobacz Co to jest Bicep?. Aby uzyskać informacje o typach danych Bicep, zobacz Typy danych.

Udostępnij za pośrednictwem