了解 Bicep 檔案的結構和語法

發行項
03/20/2024

本文描述 Bicep 檔案的結構和語法。文章將呈現顯示檔案的不同區段，以及這些區段中的可用屬性。

請參閱快速入門：使用 Visual Studio Code 建立 Bicep 檔案，了解可引導您完成 Bicep 檔案建立流程的逐步教學課程。

Bicep 格式

Bicep 為宣告式語言，這表示元素可依任何順序顯示。與命令式語言不同的是，元素的順序不會影響部署的處理方式。

Bicep 檔案具有下列元素。

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>

下列範例呈現這些元素的實作。

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

中繼資料

Bicep 中的中繼資料是可包含在 Bicep 檔案中且不具類型的值。該值可讓您提供 Bicep 檔案的補充資訊，包括其名稱、描述、作者、建立日期等詳細資料。

目標範圍

依預設，目標範圍設為 resourceGroup。若要在資源群組層級部署，則無須在 Bicep 檔案中設定目標範圍。

允許的值包括：

resourceGroup - 預設值，用於資源群組部署。
subscription - 用於訂用帳戶部署。
managementGroup - 用於管理群組部署。
tenant - 用於租用戶部署。

在模組中，您指定的範圍可與 Bicep 檔案其餘部分的範圍不同。如需詳細資訊，請參閱設定模組範圍

類型

您可以使用 type 陳述式來定義使用者定義的資料類型。

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

如需詳細資訊，請參閱使用者定義的資料類型。

函式 (預覽)

注意

若要啟用預覽功能，請參閱啟用實驗性功能。

在您的 Bicep 檔案中，除了使用 Bicep 檔案中自動提供的標準 Bicep 函式之外，您還可以建立自己的函式。若您有在 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')

如需詳細資訊，請參閱使用者定義的函式。

參數

若不同部署需要不同的值，請使用參數。您可定義部署期間未提供值時所用的參數預設值。

例如，您可新增 SKU 參數來指定資源的不同大小。視要部署至測試或生產環境而定，您可傳遞不同的值。

param storageSKU string = 'Standard_LRS'

Bicep 檔案中可使用該參數。

sku: {
  name: storageSKU
}

如需詳細資訊，請參閱 Bicep 中的參數。

參數裝飾項目

您可為各參數新增一或多個裝飾項目。這些裝飾項目描述參數，並定義所傳送值的條限制式。下列範例說明了一個裝飾項目，但您也可使用其他許多項目。

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

如需詳細資訊 (含所有可用裝飾項目的描述)，請參閱裝飾項目。

變數

您可在變數中封裝複雜運算式，讓 Bicep 檔案更容易讀取。例如，若資源名稱由數個值串連構成，則可新增變數。

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

在需要複雜運算式的位置套用此變數。

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

如需詳細資訊，請參閱 Bicep 中的變數。

資源

使用 resource 關鍵字來定義要部署的資源。您的資源宣告包含資源的符號名稱。您將會在 Bicep 檔案的其他部分使用此符號名稱，以取得資源的值。

資源宣告包含資源類型和 API 版本。在資源宣告主體中，請包含資源類型專屬的屬性。

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

如需詳細資訊，請參閱 Bicep 中的資源宣告。

有些資源具有父/子關聯性。您可在父資源內部或外部定義子資源。

下列範例顯示如何定義父資源內的子資源。其中包含一個儲存體帳戶，以及在該儲存體帳戶中定義的子資源 (檔案服務)。該檔案服務內也有定義的子資源 (共用)。

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

下一個範例顯示如何定義父資源外部的子資源。您可使用父屬性來識別父/子關聯性。已定義三個相同的資源。

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
}

如需詳細資訊，請參閱設定 Bicep 中的子資源名稱和類型。

模組

模組可讓某 Bicep 檔案中的程式碼重複用於其他 Bicep 檔案。在模組宣告中，您可連結至要重複使用的檔案。部署 Bicep 檔案時，模組中的資源也會進行部署。

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

符號名稱可讓您從檔案中的其他位置參考模組。例如，您可以使用符號名稱和輸出值名稱來取得模組的輸出值。

如需詳細資訊，請參閱使用 Bicep 模組。

資源和模組裝飾項目

您可將裝飾項目新增至資源或模組定義。支援的裝飾項目為 batchSize(int) 與 description。您僅可將其套用至使用 for 運算式的資源或模組定義。

依預設，資源以平行方式部署。新增 batchSize(int) 裝飾項目時，請依序部署實例。

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

如需詳細資訊，請參閱分批部署。

輸出

使用輸出來傳回部署的值。當其他作業必須重複使用某值時，通常可由已部署的資源傳回該值。

output storageEndpoint object = stg.properties.primaryEndpoints

如需詳細資訊，請參閱 Bicep 中的輸出。

迴圈

您可將反覆式迴圈新增至 Bicep 檔案，以定義下列項目的多個複本：

resource
模組
variable
property
output

使用 for 運算式來定義迴圈。

param moduleCount int = 2

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

您可反覆執行陣列、物件或整數索引。

如需詳細資訊，請參閱 Bicep 中的反覆式迴圈 (部分機器翻譯)。

條件式部署

您可將資源或模組新增至條件式部署的 Bicep 檔案。在部署期間，系統會評估條件，並依結果判斷是否要部署資源或模組。使用 if 運算式來定義條件式部署。

param deployZone bool

resource dnsZone 'Microsoft.Network/dnszones@2018-05-01' = if (deployZone) {
  name: 'myZone'
  location: 'global'
}

如需詳細資訊，請參閱 Bicep 中的條件式部署。

空格

製作 Bicep 檔案時，系統會忽略空格和索引標籤。

Bicep 會區分新行。例如：

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

不可撰寫如下：

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

以多行定義物件和陣列。

註解

將 // 用於單行註解或將 /* ... */ 用於多行註解

下列範例顯示單行註解。

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

下列範例顯示多行註解。

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

多行字串

您可將字串分為多行。使用三個單引號字元 ''' 作為多行字串開頭和結尾。

多行字串內的字元會維持原樣。不需要使用逸出字元。多行字串中無法包含 '''。目前不支援字串插補。

您可直接在開頭的 ''' 後開始撰寫字串，或者包含新行。在任一情況下，產生的字串皆不含新行。根據 Bicep 檔案中的行尾結束符號，新行會解譯為 \r\n 或 \n。

下列範例顯示多行字串。

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

上述範例等同下列 JSON。

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

多行宣告

您現在可以在函式、陣列和物件宣告中使用多行。此功能需要 Bicep CLI 0.7.X 版或更高版本。

在下列範例中，resourceGroup() 定義會分成多行。

var foo = resourceGroup(
  mySubscription,
  myRgName)

如需多行宣告範例，請參閱陣列和物件。

已知的限制

不支援 apiProfile 概念；此概念用於將單一 apiProfile 對應至各資源類型的一組 apiVersion。
目前不支援使用者定義的函式。不過，目前可存取實驗性功能。如需詳細資訊，請參閱 Bicep 中的使用者定義函式。
某些 Bicep 功能須進行中繼語言 (Azure Resource Manager JSON 範本) 的相應變更。當所有必要更新皆部署至全域 Azure 時，這些功能便會正式推出。若使用不同環境 (例如 Azure Stack)，該功能的推出時間則可能延遲。當該環境也已更新中繼語言時，才能使用 Bicep 功能。

下一步

如需 Bicep 簡介，請參閱何謂 Bicep？。如需 Bicep 資料類型，請參閱資料類型。