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

  • Artykuł

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.

metadata <metadata-name> = ANY

targetScope = '<scope>'

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

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>

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

resource <resource-symbolic-name> '<resource-type>@<api-version>' = {
  <resource-properties>
}

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

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@2022-09-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

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@2022-09-01' = {
  name: storageAccountConfig.name
  location: location
  sku: {
    name: storageAccountConfig.sku
  }
  kind: 'StorageV2'
}

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

Funkcje (wersja zapoznawcza)

Uwaga

Aby włączyć funkcję w wersji zapoznawczej, zobacz Włączanie funkcji eksperymentalnych.

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.

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
}

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

Dekoratory parametrów

Dla każdego parametru można dodać co najmniej jeden dekorator. Te dekoratory opisują parametr i definiują ograniczenia dla wartości, które są przekazywane. Poniższy przykład przedstawia jeden dekorator, ale wiele innych jest dostępnych.

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

Aby uzyskać więcej informacji, w tym opisy wszystkich dostępnych dekoratorów, zobacz Decorators (Decorators).

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@2019-04-01' = {
  name: uniqueStorageName

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

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@2019-06-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

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@2022-09-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@2022-09-01' = {
  name: 'examplestorage'
  location: resourceGroup().location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_LRS'
  }
}

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

resource share 'Microsoft.Storage/storageAccounts/fileServices/shares@2022-09-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.

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

Dekoratory zasobów i modułów

Dekorator można dodać do definicji zasobu lub modułu. Obsługiwane dekoratory to batchSize(int) i description. Można go zastosować tylko do definicji zasobu lub modułu for , która używa wyrażenia.

Domyślnie zasoby są wdrażane równolegle. Po dodaniu dekoratora batchSize(int) wystąpienia są wdrażane szeregowo.

@batchSize(3)
resource storageAccountResources 'Microsoft.Storage/storageAccounts@2019-06-01' = [for storageName in storageAccounts: {
  ...
}]

Aby uzyskać więcej informacji, zobacz Wdrażanie w partiach.

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

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@2018-05-01' = 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@2019-06-01' = if (newOrExisting == 'new') {
  ...
}

Nie można napisać jako:

resource sa 'Microsoft.Storage/storageAccounts@2019-06-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@2020-06-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.