了解 Bicep 檔案的結構和語法

發行項
10/16/2024

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

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

Bicep 格式

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

Bicep 檔案具有下列元素。

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

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

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

中繼資料

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

目標範圍

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

允許的值包括：

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

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

裝飾項目

您可以為以下每個元素新增一個或多個裝飾項目：

param
var
資源
module
output
func
type

裝飾項目包括：

裝飾項目	套用至元素	套用至資料類型	Argument	描述
允許	param	全部	陣列	使用此裝飾項目可確保使用者提供正確的值。此裝飾項目僅能在 `param` 陳述式上。若要宣告該屬性必須是 `type` 或 `output` 陳述式中一組預先定義的值之一，請使用等位型別語法。等位型別語法也可以在 `param` 陳述式使用。
batchSize	[module]，[resource]	N/A	整數	設定執行個體以依順序部署。
description	[func]，[param]，[module]，[output]，[resource]，[type]，[var]	全部	字串	提供元素的描述。 Markdown 格式的文字可以用於描述文字。
discriminator	[param]，[type]，[output]	object	字串	使用此裝飾項目來確保識別和管理正確的子類別。如需詳細資訊，請參閱 [自訂標記的聯集資料類型]。
匯出	[func]，[type]，[var]	全部	none	指示元素可以由另一個 Bicep 檔案匯入。
maxLength	[param]，[output]，[type]	陣列、字串	int	字串和陣列元素的最大長度。此值為內含。
maxValue	[param]，[output]，[type]	int	int	整數元素的最大值。此值為內含。
中繼資料	[func]，[output]，[param]，[type]	全部	object	要套用至元素的自訂屬性。可以包含相當於描述裝飾項目的描述屬性。
minLength	[param]，[output]，[type]	陣列、字串	int	字串和陣列元素的最小長度。此值為內含。
minValue	[param]，[output]，[type]	int	int	整數元素的最小值。此值為內含。
sealed	[param]，[type]，[output]	object	none	當使用-定義資料類型的屬性名可能是拼字錯誤時，將 [BCP089] 從警告提升為錯誤。如需詳細資訊，請參閲 [提升錯誤層級]。
secure	[param]，[type]	字串、物件	none	將參數標示為安全。安全參數的值不會儲存在部署歷程記錄中，而且不會記錄。如需詳細資訊，請參閱安全字串和物件。

參數

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

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

param storageSKU string = 'Standard_LRS'

Bicep 檔案中可使用該參數。

sku: {
  name: storageSKU
}

您可為各參數新增一或多個裝飾項目。如需詳細資訊，請參閱 [使用裝飾項目]。

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

變數

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

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

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

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

您可以為每個變數新增一個或多個裝飾項目。如需詳細資訊，請參閱 [使用裝飾項目]。

如需詳細資訊，請參閱 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@2023-04-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')

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

資源

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

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

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

您可以為每個資源新增一個或多個裝飾項目。如需詳細資訊，請參閱 [使用裝飾項目]。

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

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

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

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

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

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
}

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

模組

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

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

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

您可以為每個模組新增一個或多個裝飾項目。如需詳細資訊，請參閱 [使用裝飾項目]。

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

輸出

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

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@2023-07-01-preview' = if (deployZone) {
  name: 'myZone'
  location: 'global'
}

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

空格

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

Bicep 會區分新行。例如：

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

不可撰寫如下：

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

以多行定義物件和陣列。

註解

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

下列範例顯示單行註解。

// This is your primary NIC.
resource nic1 'Microsoft.Network/networkInterfaces@2023-11-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 資料類型，請參閱資料類型。

共用方式為