使用 Azure CLI 部署 Bicep 檔案

發行項
01/14/2025

本文說明如何使用 Azure CLI 搭配 Bicep 檔案將資源部署至 Azure。如果您不熟悉部署和管理 Azure 解決方案，請參閱什麼是 Bicep？。

必要條件

您需要 Bicep 檔案才能部署，而且檔案必須是本機檔案。您也需要 Azure CLI 並連線到 Azure：

在本機電腦上安裝 Azure CLI 命令。 若要部署 Bicep 檔案，您需要 Azure CLI 2.20.0 或更新版本。
使用 az login 連線到 Azure。如果您有多個 Azure 訂用帳戶，您可能也需要執行 az account set。

Azure CLI 的範例專為 bash 殼層撰寫。若要在 Windows PowerShell 或命令提示字元中執行此範例（cmd），您可能需要變更腳本的元素。

如果您沒有安裝 Azure CLI，您可以使用 Azure Cloud Shell。如需詳細資訊，請參閱使用 Azure Cloud Shell 部署 Bicep 檔案。

所需的權限

若要部署 Bicep 檔案或 ARM 範本，您需要對即將進行部署的資源具備寫入存取權，並可存取 Microsoft.Resources/部署資源類型上的所有作業。例如，若要部署虛擬機器，您需要 Microsoft.Compute/virtualMachines/write 和 Microsoft.Resources/deployments/* 權限。假設狀況作業具有相同的權限需求。

如需角色與權限的清單，請參閱 Azure 內建角色。

部署範圍

您可以將部署的目標設為資源群組、訂用帳戶、管理群組或租用戶。視部署的範圍而定，您會使用不同的命令，而部署 Bicep 檔案的用戶必須具有為每個範圍建立資源所需的許可權。

若要部署至 資源群組，請使用 az deployment group create：

az deployment group create --resource-group <resource-group-name> --template-file <path-to-bicep>

若要部署至 訂用帳戶，請使用 az deployment sub create：
```
az deployment sub create --location <location> --template-file <path-to-bicep>
```
如需訂用帳戶層級部署的詳細資訊，請參閱使用 Bicep 將資源部署至訂用帳戶。
若要部署至 管理群組，請使用 az deployment mg create：
```
az deployment mg create --location <location> --template-file <path-to-bicep>
```
如需管理群組層級部署的詳細資訊，請參閱使用 Bicep 將資源部署至管理群組。
若要部署至 租使用者，請使用 az deployment tenant create：
```
az deployment tenant create --location <location> --template-file <path-to-bicep>
```
如需租用戶層級部署的詳細資訊，請參閱使用 Bicep 將資源部署至租使用者。

部署本機 Bicep 檔案

您可以從本機電腦或外部電腦部署 Bicep 檔案。本節說明如何部署本機 Bicep 檔案。

如果您要部署到不存在的資源群組，請先建立資源群組。資源群組的名稱只能包含英數字元、句點 (.)、底線、連字號及括弧。最多可以有90個字元，而且不能在一段期間內結束。

az group create --name ExampleGroup --location "Central US"

若要部署本機 Bicep 檔案，請在部署命令中使用 --template-file 參數。下列範例也會示範如何設定參數值：

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file <path-to-bicep> \
  --parameters storageAccountType=Standard_GRS

部署需要幾分鐘的時間才能完成。完成後，您會看到包含下列結果的訊息：

"provisioningState": "Succeeded",

部署遠端 Bicep 檔案

Azure CLI 目前不支援部署遠端 Bicep 檔案。您可以使用 Bicep CLI 將 Bicep 檔案建置至 JSON 範本，然後將 JSON 檔案載入遠端位置。如需詳細資訊，請參閱部署遠端範本。

參數

若要傳遞參數值，可以使用內嵌參數或參數檔案。參數檔案可以是 Bicep 參數檔案或 JSON 參數檔案。

內嵌參數

若要傳遞內嵌參數，請提供 parameters 中的值。例如，若要透過 Bash 殼層將字串和陣列傳遞至 Bicep 檔案，請使用：

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-bicep> \
  --parameters exampleString='inline string' exampleArray='["value1", "value2"]'

如果您使用 Azure CLI 搭配 Cmd 或 PowerShell，請以下列格式傳遞數位： exampleArray="['value1','value2']"。

您也可以取得檔案的內容，以提供該內容做為內嵌參數。在檔案名前面加上 @：

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-bicep> \
  --parameters exampleString=@stringContent.txt exampleArray=@arrayContent.json

當您需要提供組態值時，從檔案取得參數值會很有幫助。例如，您可以提供 Linux 虛擬機器的 cloud-init 值。

arrayContent.json 的格式為：

[
  "value1",
  "value2"
]

若要傳入物件，請使用 JSON（例如設定標籤時）。您的 Bicep 檔案可能包含如下的參數：

"resourceTags": {
  "type": "object",
  "defaultValue": {
    "Cost Center": "IT Department"
  }
}

如下列 Bash 腳稿所示，您也可以傳入 JSON 字串來設定參數。在您要傳遞至物件的 JSON 周圍使用雙引號：

tags='{"Owner":"Contoso","Cost Center":"2345-324"}'
az deployment group create --name addstorage  --resource-group myResourceGroup \
--template-file $bicepFile \
--parameters resourceName=abcdef4556 resourceTags="$tags"

如果您使用 Azure CLI 搭配 Cmd 或 PowerShell，請以下列格式傳遞物件：

$tags="{'Owner':'Contoso','Cost Center':'2345-324'}"
az deployment group create --name addstorage  --resource-group myResourceGroup \
--template-file $bicepFile \
--parameters resourceName=abcdef4556 resourceTags=$tags

您可以使用變數來包含參數值。將變數設定為Bash腳本中的所有參數值，並將它新增至部署命令：

params="prefix=start suffix=end"

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-bicep> \
  --parameters $params

不過，如果您使用 Azure CLI 搭配 Cmd 或 PowerShell，請將變數設定為 JSON 字串。逸出引號：$params = '{ \"prefix\": {\"value\":\"start\"}, \"suffix\": {\"value\":\"end\"} }'。

參數的評估會遵循循序順序，這表示如果已指派值多次，則只會使用最後一個指派的值。若要正確指派參數，建議您一開始提供參數檔案，然後使用 KEY=VALUE 語法選擇性地覆寫特定參數。如果您提供 .bicepparam 參數檔案，則只能使用此自變數一次。

Bicep 參數檔案

相較於在腳本中傳遞參數做為內嵌值，您可能會發現使用 Bicep 參數檔案或包含參數值的 JSON 參數檔案會比較容易。參數檔案必須是本機檔案，因為 Azure CLI 不支援外部參數檔案。如需參數檔案的詳細資訊，請參閱建立 Bicep 部署的參數檔案。

您可以使用 Bicep 參數檔案，使用 Azure CLI 2.53.0 版或更新版本和 Bicep CLI 0.22.X 版或更新版本來部署 Bicep 檔案。 using使用 Bicep 參數檔案內的語句，在指定--parameters參數的 Bicep 參數檔案時，不需要提供 --template-file 參數。 --template-file包含參數將會提示「只有 .bicep 範本允許使用 .bicepparam 檔案」錯誤。

下列範例會顯示名為 storage.bicepparam 的參數檔案。檔案位於命令執行所在的相同目錄中：

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --parameters storage.bicepparam

JSON 參數檔案

下列範例會顯示名為 storage.parameters.json 的參數檔案。檔案位於命令執行所在的相同目錄中：

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.bicep \
  --parameters '@storage.parameters.json'

您可以在相同的部署作業中使用內嵌參數和位置參數檔案。如需詳細資訊，請參閱參數優先順序。

預覽變更

在部署 Bicep 檔案之前，您可以預覽 Bicep 檔案將對您的環境進行的變更。使用假設狀況作業來確認 Bicep 檔案會進行您預期的變更。假設狀況也能驗證 Bicep 檔是否有錯誤。

部署範本規格

目前，Azure CLI 不提供 Bicep 檔案來協助建立範本規格。不過，您可以使用 Microsoft.Resources/templateSpecs 資源建立 Bicep 檔案，以部署範本規格。建立範例示範如何在 Bicep 檔案中建立範本規格。您也可以使用 Bicep CLI 和 JSON 範本來建立範本規格，將 Bicep 檔案建置至 JSON。

部署名稱

部署 Bicep 檔案時，您可以為該部署取名。此名稱可協助您從部署歷程記錄中擷取部署。如果您未提供部署的名稱，其名稱會變成 Bicep 檔案的名稱。例如，如果您部署名為 main.bicep 且未指定部署名稱的 Bicep 檔案，則部署名為 main。

每次執行部署時，資源群組的部署歷程記錄便會新增一筆具有部署名稱的項目。如果您執行另一個部署並提供相同名稱，則系統會將先前的項目取代為目前的部署。如果您想在部署歷程記錄中維護唯一的項目，請為每個部署提供唯一的名稱。

若要建立唯一的名稱，您可以指派隨機數：

deploymentName='ExampleDeployment'$RANDOM

或者，新增日期值：

deploymentName='ExampleDeployment'$(date +"%d-%b-%Y")

如果您使用相同的部署名稱，同時對同一個資源群組執行部署，則只會完成最後一個部署。具有相同名稱但尚未完成的任何部署，都會由最後一個部署所取代。例如，如果您執行名為的部署來部署名為 newStorage storage1 的記憶體帳戶，並執行另一個名為的部署，以同時部署名為 newStorage storage2 的記憶體帳戶，您只會部署一個記憶體帳戶。產生的儲存體帳戶名稱為 storage2。

不過，如果您執行名為的部署，其會部署名為 newStorage storage1 的記憶體帳戶，並立即執行另一個名為的部署，以部署名為的第一個部署完成之後所命名newStoragestorage2的記憶體帳戶，則您有兩個記憶體帳戶。一個名稱為 storage1，另一個名稱則為 storage2。但是，您在部署歷程記錄中只會具有一個項目。

若您為每個部署指定唯一的名稱，便可以同時執行這些部署，而不會發生衝突。如果您執行名為的部署來部署名為 newStorage1 storage1 的記憶體帳戶，並執行另一個名為的部署，以同時部署名為 newStorage2 storage2 的記憶體帳戶，則您在部署歷程記錄中有兩個記憶體帳戶和兩個專案。

為了避免因同時部署而發生衝突，並確保部署歷程記錄中項目的唯一性，請為每個部署提供唯一的名稱。

下一步

若要了解如何在檔案中定義參數，請參閱了解 Bicep 檔案的結構和語法。

共用方式為