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

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 przy użyciu 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.

targetScope = '<scope>'

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

@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@2019-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
  }
}

output storageEndpoint object = stg.properties.primaryEndpoints

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:

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

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żna 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 przekazywanych wartości. W poniższym przykładzie pokazano jeden dekorator, ale dostępnych jest wiele innych.

@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żna na przykład dodać zmienną dla nazwy zasobu, która jest tworzona przez łączenie kilku wartości.

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

Zastosuj tę zmienną wszędzie tam, gdzie potrzebujesz wyrażenia złożonego.

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. Użyjesz tej symbolicznej nazwy 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 uwzględnij 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 aplikacji 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 ono konto magazynu z zasobem podrzędnym (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@2021-02-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@2021-02-01' = {
  name: 'examplestorage'
  location: resourceGroup().location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_LRS'
  }
}

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

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

Aby uzyskać więcej informacji, zobacz Set name and type for child resources in Bicep (Ustawianie nazwy i typu zasobów podrzędnych w aplikacji 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ływanie się do modułu z innego miejsca w pliku. Na przykład można uzyskać wartość wyjściową z modułu przy użyciu nazwy symbolicznej i nazwy wartości wyjściowej.

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

Dekoratory zasobów i modułów

Dekorator można dodać do definicji zasobu lub modułu. Jedynym obsługiwanym dekoratorem jest batchSize(int). 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 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 Outputs in Bicep (Dane wyjściowe w środowisku Bicep).

Pętle

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

  • zasób
  • moduł
  • zmienna
  • property
  • 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.

Białe znaki

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

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

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

Nie można pisać 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 pokazano komentarz jednowierszowy.

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

Poniższy przykład przedstawia 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 zgodnie z rzeczywistymi wartościami. 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 wersji Bicep w wersji 0.7.4 lub nowszej.

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

var foo = resourceGroup(
  mySubscription,
  myRgName)

Zobacz Tablice i obiekty , aby uzyskać przykłady deklaracji wielowierszowych.

Znane ograniczenia

  • Brak obsługi koncepcji interfejsu APIProfile, który służy do mapowania pojedynczego pliku apiProfile na zestaw apiVersion dla każdego typu zasobu.
  • Brak obsługi funkcji zdefiniowanych przez użytkownika.
  • Niektóre funkcje Bicep wymagają odpowiedniej zmiany języka pośredniego (szablony JSON platformy 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 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?. W przypadku typów danych Bicep zobacz Typy danych.