你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

如何将 Azure 资源管理器（ARM）部署模板与 Azure CLI 配合使用

本文介绍如何将Azure CLI与Azure 资源管理器模板（ARM 模板）配合使用，将资源部署到Azure。如果不熟悉部署和管理Azure解决方案的概念，请参阅模板部署概述。

Azure CLI版本 2.2.0 中更改了部署命令。本文中的示例需要 Azure CLI 2.20.0 或更高版本。

若要运行此示例，请安装最新版本的 Azure CLI。若要开始，请运行 az login 以创建与Azure的连接。

Azure CLI的示例是为 bash shell 编写的。若要在 Windows PowerShell 或命令提示符中运行此示例，可能需要更改脚本的元素。

如果没有安装Azure CLI，可以使用Azure Cloud Shell。有关详细信息，请参阅在 Azure Cloud Shell 上部署 ARM 模板。

提示

建议使用 Bicep，因为它提供与 ARM 模板相同的功能，并且语法更易于使用。若要了解详细信息，请参阅如何使用 Bicep 和 Azure CLI 部署资源。

先决条件

所需的权限

若要部署Bicep文件或 Azure 资源管理器（ARM）模板，需要对所部署的资源拥有写入权限，以及访问 Microsoft.Resources/deployments 资源类型的所有操作权限。例如，若要部署虚拟机，需要Microsoft.Compute/virtualMachines/write 和 Microsoft.Resources/deployments/* 权限。 What-if 操作具有相同的权限要求。

Azure CLI版本 2.76.0 或更高版本和Azure PowerShell版本 13.4.0 或更高版本引入了 ValidationLevel 开关，以确定 ARM 在此过程中如何彻底验证Bicep模板。有关详细信息，请参阅 What-if 命令

有关角色和权限的列表，请参阅 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 密钥保管库中提取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 并部署它。

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 资源管理器模板规格。

预览更改

在部署 ARM 模板之前，可以预览模板对环境做出的更改。使用模拟操作验证模板是否会进行你所期望的更改。模拟操作还验证模板是否有错误。

参数

若要传递参数值，可以使用内联参数或参数文件。参数文件可以是 Bicep parameters 文件或 JSON 参数文件。

内联参数。

若要传递内联参数，请在 parameters 中提供值。例如，若要在 Bash shell 中将字符串和数组传递给模板，请使用：

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 参数文件

与在脚本中将参数作为内联值传递相比，你可能会发现使用包含参数值的参数文件（.bicepparam 文件或 JSON 参数文件）更容易。参数文件必须是本地文件。 Azure CLI不支持外部参数文件。

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

有关参数文件的详细信息，请参阅创建资源管理器参数文件。

Bicep 参数文件

使用 Azure CLI 版本 2.53.0 或更高版本，以及 Bicep CLI 版本 0.22.6 或更高版本，你可以使用 Bicep 参数文件来部署 Bicep 文件。使用 Bicep 参数文件中的 using 语句，在为 --template-file 开关指定 Bicep 参数文件时无需提供 --parameters 开关。包含 --template-file 开关会导致出现“.bicepparam 文件仅允许 .bicep 文件”错误。

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

参数文件必须是本地文件。 Azure CLI不支持外部参数文件。有关参数文件的详细信息，请参阅创建资源管理器参数文件。

注释和扩展的 JSON 格式

可以在参数文件中包含 // 样式注释，但必须使用 .jsonc 扩展名命名文件。

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

有关注释和元数据的更多详细信息，请参阅了解 ARM 模板的结构和语法。

如果使用版本 2.3.0 或更高版本的 Azure CLI，则可以使用 --handle-extended-json-format 开关部署包含多行字符串或注释的模板。例如：

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2025-04-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 资源管理器部署模式。
要了解如何在模板中定义参数，请参阅了解 ARM 模板的结构和语法。
有关解决常见部署错误的提示，请参阅使用 Azure 资源管理器排查常见 Azure 部署错误。

反馈

此页面是否有帮助？

Last updated on 2026-04-14