使用 ARM 模板和资源管理器 REST API 部署资源Deploy resources with ARM templates and Resource Manager REST API

本文介绍如何将资源管理器 REST API 与 Azure 资源管理器模板 (ARM) 配合使用向 Azure 部署资源。This article explains how to use the Resource Manager REST API with Azure Resource Manager (ARM) templates to deploy your resources to Azure.

可以在请求正文中包含模板或链接到文件。You can either include your template in the request body or link to a file. 使用文件时,它可以是本地文件,也可以是通过 URI 提供的外部文件。When using a file, it can be a local file or an external file that is available through a URI. 如果模板位于存储帐户中,可以限制对该模板的访问,并在部署过程中提供共享访问签名 (SAS) 令牌。When your template is in a storage account, you can restrict access to the template and provide a shared access signature (SAS) token during deployment.

部署范围Deployment scope

可将部署目标设定为管理组、Azure 订阅或资源组。You can target your deployment to a management group, an Azure subscription, or a resource group. 大多数情况下,我们会将部署目标设定为资源组。In most cases, you'll target deployments to a resource group. 使用管理组或订阅部署在指定范围内应用策略和角色分配。Use management group or subscription deployments to apply policies and role assignments across the specified scope. 还可以使用订阅部署创建资源组,并将资源部署到该资源组。You also use subscription deployments to create a resource group and deploy resources to it. 你将根据部署范围使用不同的命令。Depending on the scope of the deployment, you use different commands.

本文中的示例使用资源组部署。The examples in this article use resource group deployments.

使用 REST API 进行部署Deploy with the REST API

  1. 设置 常见参数和标头,包括身份验证令牌。Set common parameters and headers, including authentication tokens.

  2. 如果目前没有资源组,请创建资源组。If you don't have an existing resource group, create a resource group. 提供订阅 ID、新资源组的名称,以及解决方案所需的位置。Provide your subscription ID, the name of the new resource group, and location that you need for your solution. 有关详细信息,请参阅 创建资源组For more information, see Create a resource group.

    PUT https://management.chinacloudapi.cn/subscriptions/<YourSubscriptionId>/resourcegroups/<YourResourceGroupName>?api-version=2019-10-01
    

    使用如下所示请求正文:With a request body like:

    {
    "location": "China North",
    "tags": {
      "tagname1": "tagvalue1"
    }
    }
    
  3. 在部署模板之前,可以预览模板将对环境作出的更改。Before deploying your template, you can preview the changes the template will make to your environment. 使用假设操作验证模板是否进行了预期的更改。Use the what-if operation to verify that the template makes the changes that you expect. 假设操作还验证模板是否有错误。What-if also validates the template for errors.

  4. 若要部署模板,请在请求 URI 中提供订阅 ID、资源组名称和部署名称。To deploy a template, provide your subscription ID, the name of the resource group, the name of the deployment in the request URI.

    PUT https://management.chinacloudapi.cn/subscriptions/<YourSubscriptionId>/resourcegroups/<YourResourceGroupName>/providers/Microsoft.Resources/deployments/<YourDeploymentName>?api-version=2019-10-01
    

    在请求正文中,提供指向模板和参数文件的链接。In the request body, provide a link to your template and parameter file. 有关参数文件的详细信息,请参阅创建资源管理器参数文件For more information about the parameter file, see Create Resource Manager parameter file.

    请注意, mode 设置为 IncrementalNotice the mode is set to Incremental . 要运行完整部署,请将 mode 设置为 CompleteTo run a complete deployment, set mode to Complete . 使用完整模式时要小心,因为可能会无意中删除不在模板中的资源。Be careful when using the complete mode as you can inadvertently delete resources that aren't in your template.

    {
    "properties": {
      "templateLink": {
        "uri": "http://mystorageaccount.blob.core.chinacloudapi.cn/templates/template.json",
        "contentVersion": "1.0.0.0"
      },
      "parametersLink": {
        "uri": "http://mystorageaccount.blob.core.chinacloudapi.cn/templates/parameters.json",
        "contentVersion": "1.0.0.0"
      },
      "mode": "Incremental"
    }
    }
    

    如果想要记录响应内容或/和请求内容,请在请求中包括 debugSettingIf you want to log response content, request content, or both, include debugSetting in the request.

    {
    "properties": {
      "templateLink": {
        "uri": "http://mystorageaccount.blob.core.chinacloudapi.cn/templates/template.json",
        "contentVersion": "1.0.0.0"
      },
      "parametersLink": {
        "uri": "http://mystorageaccount.blob.core.chinacloudapi.cn/templates/parameters.json",
        "contentVersion": "1.0.0.0"
      },
      "mode": "Incremental",
      "debugSetting": {
        "detailLevel": "requestContent, responseContent"
      }
     }
    }
    

    可以将存储帐户设置为使用共享访问签名 (SAS) 令牌。You can set up your storage account to use a shared access signature (SAS) token. 有关详细信息,请参阅使用共享访问签名委托访问权限For more information, see Delegating Access with a Shared Access Signature.

    如果需要为参数(如密码)提供敏感值,请将该值添加到密钥保管库。If you need to provide a sensitive value for a parameter (such as a password), add that value to a key vault. 在部署过程中检索密钥保管库,如前面的示例所示。Retrieve the key vault during deployment as shown in the previous example. 有关详细信息,请参阅在部署期间传递安全值For more information, see Pass secure values during deployment.

  5. 可以将模板和参数包含在请求正文中,而不是链接到模板和参数的文件。Instead of linking to files for the template and parameters, you can include them in the request body. 以下示例显示了内联模板和参数的请求正文:The following example shows the request body with the template and parameter inline:

    {
      "properties": {
      "mode": "Incremental",
      "template": {
        "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
        "contentVersion": "1.0.0.0",
        "parameters": {
          "storageAccountType": {
            "type": "string",
            "defaultValue": "Standard_LRS",
            "allowedValues": [
              "Standard_LRS",
              "Standard_GRS",
              "Premium_LRS"
            ],
            "metadata": {
              "description": "Storage Account type"
            }
          },
          "location": {
            "type": "string",
            "defaultValue": "[resourceGroup().location]",
            "metadata": {
              "description": "Location for all resources."
            }
          }
        },
        "variables": {
    
          "storageAccountName": "[concat(uniquestring(resourceGroup().id), 'standardsa')]"
        },
        "resources": [
          {
            "type": "Microsoft.Storage/storageAccounts",
            "apiVersion": "2018-02-01",
            "name": "[variables('storageAccountName')]",
            "location": "[parameters('location')]",
            "sku": {
              "name": "[parameters('storageAccountType')]"
            },
            "kind": "StorageV2",
            "properties": {}
          }
        ],
        "outputs": {
          "storageAccountEndPoint": "https://core.chinacloudapi.cn/",
          "storageAccountName": {
            "type": "string",
            "value": "[variables('storageAccountName')]"
          }
        }
      },
      "parameters": {
        "location": {
          "value": "chinaeast2"
        }
      }
     }
    }
    
  6. 要获取模板部署的状态,请使用部署 - 获取To get the status of the template deployment, use Deployments - Get.

    GET https://management.chinacloudapi.cn/subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}/providers/Microsoft.Resources/deployments/{deploymentName}?api-version=2019-10-01
    

部署名称Deployment name

可为部署提供一个名称,如 ExampleDeploymentYou can give your deployment a name such as ExampleDeployment.

每次运行部署时,一个包含部署名称的条目会添加到资源组的部署历史记录中。Every time you run a deployment, an entry is added to the resource group's deployment history with the deployment name. 如果运行另一个部署并为其指定了相同的名称,则会将先前的条目替换为当前部署。If you run another deployment and give it the same name, the earlier entry is replaced with the current deployment. 如果要在部署历史记录中保持唯一条目,请为每个部署指定唯一名称。If you want to maintain unique entries in the deployment history, give each deployment a unique name.

若要创建唯一名称,你可以分配一个随机数。To create a unique name, you can assign a random number. 或者,添加日期值。Or, add a date value.

如果使用相同的部署名称对同一资源组运行并发部署,则仅会完成最后一个部署。If you run concurrent deployments to the same resource group with the same deployment name, only the last deployment is completed. 尚未完成的具有相同名称的任何部署都将被最后一个部署所替换。Any deployments with the same name that haven't finished are replaced by the last deployment. 例如,如果你运行一个名为 newStorage 的部署,它部署了一个名为 storage1 的存储帐户;与此同时,你运行了另一个名为 newStorage 的部署,它部署了一个名为 storage2 的存储帐户,则你将仅部署一个存储帐户。For example, if you run a deployment named newStorage that deploys a storage account named storage1, and at the same time run another deployment named newStorage that deploys a storage account named storage2, you deploy only one storage account. 生成的存储帐户名为 storage2The resulting storage account is named storage2.

但是,如果你运行一个名为 newStorage 的部署,它部署了一个名为 storage1 的存储帐户;在该部署完成时你又立即运行了另一个名为 newStorage 的部署,它部署了一个名为 storage2 的存储帐户,则你将有两个存储帐户。However, if you run a deployment named newStorage that deploys a storage account named storage1, and immediately after it completes you run another deployment named newStorage that deploys a storage account named storage2, then you have two storage accounts. 一个名为 storage1,另一个名为 storage2One is named storage1, and the other is named storage2. 但是,部署历史记录中只有一个条目。But, you only have one entry in the deployment history.

为每个部署指定唯一的名称时,可以并发运行它们而不会发生冲突。When you specify a unique name for each deployment, you can run them concurrently without conflict. 如果你运行一个名为 newStorage1 的部署,它部署了一个名为 storage1 的存储帐户;与此同时,你又运行了另一个名为 newStorage2 的部署,它部署了一个名为 storage2 的存储帐户,则部署历史记录中将有两个存储帐户和两个条目。If you run a deployment named newStorage1 that deploys a storage account named storage1, and at the same time run another deployment named newStorage2 that deploys a storage account named storage2, then you have two storage accounts and two entries in the deployment history.

为避免与并发部署冲突并确保部署历史记录中的条目是唯一的,请为每个部署指定唯一的名称。To avoid conflicts with concurrent deployments and to ensure unique entries in the deployment history, give each deployment a unique name.

后续步骤Next steps