如何使用 Azure Resource Manager (ARM) 部署範本搭配 Azure CLI

發行項
12/05/2022

本文說明如何使用 Azure CLI 搭配 Azure Resource Manager 範本 (ARM 範本)，以將您的資源部署至 Azure。如果您不熟悉部署和管理 Azure 解決方案的概念，請參閱範本部署概觀。

Azure CLI 版本 2.2.0 中的部署命令已變更。本文中的範例需要 Azure CLI 2.20.0 版或更新版本。

若要執行此範例，請安裝最新版的 Azure CLI。若要啟動，請執行 az login 來建立與 Azure 的連線。

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

如果您沒有安裝 Azure CLI，也可以使用 Azure Cloud Shell。如需詳細資訊，請參閱從 Azure Cloud Shell 部署 ARM 範本。

提示

我們建議使用 Bicep，因為其提供的功能與 ARM 範本相同，而且語法更易於使用。若要深入了解，請參閱如何使用 Bicep 和 Azure CLI 部署資源。

所需的權限

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

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

部署範圍

您可以將 Azure 部署範本的目標設為資源群組、訂用帳戶、管理群組或租用戶。視部署的範圍而定，您可以使用不同的命令。

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

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

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

針對每個範圍，部署範本的使用者必須擁有建立資源的必要權限。

部署本機範本

您可以從本機電腦或外部儲存的位置部署 ARM 範本。本節描述如何部署本機範本。

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

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

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

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

--template-file 參數的值必須是 Bicep 檔案或 .json 或 .jsonc 檔案。 .jsonc 副檔名表示檔案可以包含 // 樣式註解。 ARM 系統接受 .json 檔案中的 // 註解。該系統並不關心副檔名。如需關於註解和中繼資料的詳細資訊，請參閱了解 ARM 範本的結構和語法。

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

"provisioningState": "Succeeded",

部署遠端範本

您可能會想將 ARM 範本儲存在外部位置，而非儲存在本機電腦中。您可以將範本儲存在原始檔控制存放庫 (例如 GitHub) 中。或者，您可以將它們儲存在 Azure 儲存體帳戶中，以在組織內共用存取。

注意

若要針對儲存在私人 GitHub 存放庫中的連結範本來部署範本或參考，請參閱建立自訂和安全 Azure 入口網站供應項目中記載的自訂解決方案。您可以建立 Azure 函數，以從 Azure Key Vault 提取 GitHub 權杖。

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

使用 template-uri 參數部署外部範本。

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-uri "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.storage/storage-account-create/azuredeploy.json" \
  --parameters storageAccountType=Standard_GRS

上述範例針對範本需要可公開存取 URI，這適用於大部分的案例，因為您的範本不應該包含機密資料。如果您需要指定機密資料 (例如系統管理員密碼)，請將該值以安全參數傳遞。但是，如果您想要管理範本的存取權，請考慮使用範本規格。

若要使用儲存在儲存體帳戶中的相對路徑來部署遠端連結範本，請使用 query-string 指定 SAS 權杖：

az deployment group create \
  --name linkedTemplateWithRelativePath \
  --resource-group myResourceGroup \
  --template-uri "https://stage20210126.blob.core.windows.net/template-staging/mainTemplate.json" \
  --query-string $sasToken

如需詳細資訊，請參閱使用連結範本的相對路徑。

Azure 部署範本名稱

部署 ARM 範本時，您可以提供 Azure 部署範本的名稱。此名稱可協助您從部署歷程記錄中擷取部署。如果您未提供部署的名稱，系統會使用範本檔案的名稱。例如，如果您部署名為 azuredeploy.json 的範本，但未指定部署名稱，則會將部署命名為 azuredeploy。

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

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

deploymentName='ExampleDeployment'$RANDOM

或者，也可以加入日期值。

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

如果您使用相同的部署名稱，同時執行部署至相同的資源群組，則系統只會完成最後一項部署。具有相同名稱但未完成的任何部署，都會由最後一個部署所取代。如果您執行名稱為 newStorage 的部署來部署名稱為 storage1 的儲存體帳戶，同時執行另一個名稱為 newStorage 的部署來部署名稱為 storage2 的儲存體帳戶，則您會有兩個儲存體帳戶且部署歷程記錄中會有兩個項目。最後所產生的儲存體帳戶名稱為 storage2。

但是，如果您執行名稱為 newStorage 的部署來部署名稱為 storage1 的儲存體帳戶，並在完成後立即執行另一個名 newStorage 為的部署來部署名稱為 storage2 的儲存體帳戶，則您會有兩個儲存體帳戶。一個名稱為 storage1，而另一個名稱則為 storage2。但是，您在部署歷程記錄中只會有一個項目。

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

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

部署範本規格

除了部署本機或遠端範本，您也可以建立範本規格。範本規格是您的 Azure 訂閱中包含 ARM 範本的資源。這可讓您輕鬆安全地與組織中的使用者共用範本。您可以使用 Azure 角色型存取控制 (Azure RBAC) 授與範本規格的存取權。此功能目前為預覽狀態。

下列範例示範如何建立和部署範本規格。

首先，提供 ARM 範本來建立範本規格。

az ts create \
  --name storageSpec \
  --version "1.0" \
  --resource-group templateSpecRG \
  --location "westus2" \
  --template-file "./mainTemplate.json"

然後，取得範本規格的識別碼並加以部署。

id = $(az ts show --name storageSpec --resource-group templateSpecRG --version "1.0" --query "id")

az deployment group create \
  --resource-group demoRG \
  --template-spec $id

如需詳細資訊，請參閱 Azure Resource Manager 範本規格。

預覽變更

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

參數

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

內嵌參數

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

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

如果您要使用 Azure CLI 搭配 Windows 命令提示字元 (CMD) 或 PowerShell，請使用下列格式來傳遞陣列：exampleArray="['value1','value2']"。

您也可以取得檔案內容，並提供該內容作為內嵌參數。

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

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

arrayContent.json 的格式為：

[
    "value1",
    "value2"
]

若要傳入物件 (例如：設定標記)，請使用 JSON。例如，您的範本可能包含如下所示的參數：

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

在此情況下，您可以傳入 JSON 字串來設定參數，如下列 Bash 指令碼所示：

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

在您想要傳遞給物件的 JSON 周圍使用雙引號。

您可以使用變數來包含參數值。在 Bash 中，將變數設為所有參數值，並將其新增至部署命令。

params="prefix=start suffix=end"

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

但是，如果您要使用 Azure CLI 搭配 Windows 命令提示字元 (CMD) 或 PowerShell，請將變數設為 JSON 字串。逸出引號：$params = '{ \"prefix\": {\"value\":\"start\"}, \"suffix\": {\"value\":\"end\"} }'。

參數檔案

相對於在您的指令碼中將參數做為內嵌值傳遞，使用包含該參數值的 JSON 檔案可能較為容易。參數檔案必須是本機檔案。 Azure CLI 不支援外部參數檔案。

如需參數檔案的詳細資訊，請參閱建立 Resource Manager 參數檔案。

若要傳遞本機參數檔案，請使用 @ 來指定名為 storage.parameters.json 的本機檔案。

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

註解和擴充 JSON 格式

您可以在 // 參數檔案中包含樣式註解，但必須以 .jsonc 副檔名命名檔案。

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

如需關於註解和中繼資料的詳細資訊，請參閱了解 ARM 範本的結構和語法。

如果您使用 Azure CLI 搭配 2.3.0 版或更新版本，則可以用 --handle-extended-json-format 參數來部署具有多行字串或註解的範本。例如：

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2018-10-01",
  "name": "[variables('vmName')]", // to customize name, change it in variables
  "location": "[
    parameters('location')
    ]", //defaults to resource group location
  /*
    storage account and network interface
    must be deployed first
  */
  "dependsOn": [
    "[resourceId('Microsoft.Storage/storageAccounts/', variables('storageAccountName'))]",
    "[resourceId('Microsoft.Network/networkInterfaces/', variables('nicName'))]"
  ],

後續步驟

在您收到錯誤時，若要回復為成功的部署，請參閱錯誤回復至成功部署。
若要指定如何處理存在於資源群組中、但尚未定義於範本中的資源，請參閱 Azure Resource Manager 部署模式。
若要了解如何在您的範本中定義參數，請參閱了解 ARM 範本的結構和語法。
如需解決常見部署錯誤的秘訣，請參閱使用 Azure Resource Manager 針對常見的 Azure 部署錯誤進行疑難排解。