在 ARM 模板中设置扩展资源的范围Setting scope for extension resources in ARM templates

扩展资源是用于修改其他资源的资源。An extension resource is a resource that modifies another resource. 例如，可以为资源分配角色以限制访问权限。For example, you can assign a role to a resource to limit access. 角色分配是扩展资源类型。The role assignment is an extension resource type.

有关扩展资源类型的完整列表，请参阅用于扩展其他资源的功能的资源类型。For a full list of extension resource types, see Resource types that extend capabilities of other resources.

本文介绍如何在使用 Azure 资源管理器模板（ARM 模板）进行部署时设置扩展资源类型的范围。This article shows how to set the scope for an extension resource type when deployed with an Azure Resource Manager template (ARM template). 它介绍了在应用到资源时可用于扩展资源的 scope 属性。It describes the scope property that is available for extension resources when applying to a resource.

在部署范围内应用Apply at deployment scope

若要在目标部署范围内应用扩展资源类型，请将该资源添加到模板中，就像应用任何资源类型一样。To apply an extension resource type at the target deployment scope, you add the resource to your template, as would with any resource type. 可用的范围是资源组、订阅、管理组和租户。The available scopes are resource group, subscription, management group, and tenant. 部署范围必须支持该资源类型。The deployment scope must support the resource type.

以下模板会部署一个锁。The following template deploys a lock.

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {  
    },
    "resources": [
        {
            "type": "Microsoft.Authorization/locks",
            "apiVersion": "2016-09-01",
            "name": "rgLock",
            "properties": {
                "level": "CanNotDelete",
                "notes": "Resource Group should not be deleted."
            }
        }
    ]
}

部署到资源组时，它会锁定资源组。When deployed to a resource group, it locks the resource group.

备注

当我们使用以 https://raw.githubusercontent.com/ 开头的指定模板文件 URI 部署资源时，控制台有时将返回错误，如 Unable to download deployment content。When we deploy resource with specified template file URI that starts with https://raw.githubusercontent.com/, the console will return error like Unable to download deployment content sometime.

可以执行以下操作来解决相应问题。We can follow the actions below to resolve the corresponding issue.

  1. 下载指定 URI 的模板文件内容并以同一名称另存在本地计算机上。Download the template file content of specified URI and save as the same name on your local computer.

  2. 将 TemplateUri 的参数替换为 TemplateFile，然后用下载的实际文件名更新指定的 URI，并再次运行该脚本。Replace the parameter of TemplateUri with TemplateFile, then update the specified URI with the download actual file name and run the script again.

    语言类别Language category 参考链接Reference link 操作Action
    PowerShellPowerShell New-AzResourceGroupDeploymentNew-AzResourceGroupDeployment 将 -TemplateUri 替换为 '-TemplateFile`Replace -TemplateUri with '-TemplateFile`
    Azure CLIAzure CLI az 部署组创建az deployment group create 将 --template-uri 替换为 '--template-file`Replace --template-uri with '--template-file` 
az deployment group create \
  --resource-group ExampleGroup \
  --template-uri "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/azure-resource-manager/scope/locktargetscope.json"

下一个示例会分配角色。The next example assigns a role.

{
    "$schema": "https://schema.management.azure.com/schemas/2018-05-01/subscriptionDeploymentTemplate.json#",
    "contentVersion": "1.0.0.1",
    "parameters": {
        "principalId": {
            "type": "string",
            "metadata": {
                "description": "The principal to assign the role to"
            }
        },
        "builtInRoleType": {
            "type": "string",
            "allowedValues": [
                "Owner",
                "Contributor",
                "Reader"
            ],
            "metadata": {
                "description": "Built-in role to assign"
            }
        },
        "roleNameGuid": {
            "type": "string",
            "defaultValue": "[newGuid()]",
            "metadata": {
                "description": "A new GUID used to identify the role assignment"
            }
        }
    },
    "variables": {
        "Owner": "[concat('/subscriptions/', subscription().subscriptionId, '/providers/Microsoft.Authorization/roleDefinitions/', '8e3af657-a8ff-443c-a75c-2fe8c4bcb635')]",
        "Contributor": "[concat('/subscriptions/', subscription().subscriptionId, '/providers/Microsoft.Authorization/roleDefinitions/', 'b24988ac-6180-42a0-ab88-20f7382dd24c')]",
        "Reader": "[concat('/subscriptions/', subscription().subscriptionId, '/providers/Microsoft.Authorization/roleDefinitions/', 'acdd72a7-3385-48ef-bd42-f606fba81ae7')]"
    },
    "resources": [
        {
            "type": "Microsoft.Authorization/roleAssignments",
            "apiVersion": "2020-04-01-preview",
            "name": "[parameters('roleNameGuid')]",
            "properties": {
                "roleDefinitionId": "[variables(parameters('builtInRoleType'))]",
                "principalId": "[parameters('principalId')]"
            }
        }
    ],
    "outputs": {}
}

部署到订阅时，它会为订阅分配角色。When deployed to a subscription, it assigns the role to the subscription.

az deployment sub create \
  --name demoSubDeployment \
  --location chinaeast \
  --template-uri "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/azure-resource-manager/scope/roletargetscope.json"

应用于资源Apply to resource

若要将扩展资源应用于资源，请使用 scope 属性。To apply an extension resource to a resource, use the scope property. 将 scope 属性设置为要将扩展添加到其中的资源的名称。Set the scope property to the name of the resource you're adding the extension to. scope 属性是扩展资源类型的根属性。The scope property is a root property for the extension resource type.

下面的示例创建一个存储帐户并对其应用角色。The following example creates a storage account and applies a role to it.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "principalId": {
      "type": "string",
      "metadata": {
        "description": "The principal to assign the role to"
      }
    },
    "builtInRoleType": {
      "type": "string",
      "allowedValues": [
        "Owner",
        "Contributor",
        "Reader"
      ],
      "metadata": {
        "description": "Built-in role to assign"
      }
    },
    "roleNameGuid": {
      "type": "string",
      "defaultValue": "[newGuid()]",
      "metadata": {
        "description": "A new GUID used to identify the role assignment"
      }
    },
    "location": {
        "type": "string",
        "defaultValue": "[resourceGroup().location]"
    }
  },
  "variables": {
    "Owner": "[concat('/subscriptions/', subscription().subscriptionId, '/providers/Microsoft.Authorization/roleDefinitions/', '8e3af657-a8ff-443c-a75c-2fe8c4bcb635')]",
    "Contributor": "[concat('/subscriptions/', subscription().subscriptionId, '/providers/Microsoft.Authorization/roleDefinitions/', 'b24988ac-6180-42a0-ab88-20f7382dd24c')]",
    "Reader": "[concat('/subscriptions/', subscription().subscriptionId, '/providers/Microsoft.Authorization/roleDefinitions/', 'acdd72a7-3385-48ef-bd42-f606fba81ae7')]",
    "storageName": "[concat('storage', uniqueString(resourceGroup().id))]"
  },
  "resources": [
    {
      "apiVersion": "2019-04-01",
      "type": "Microsoft.Storage/storageAccounts",
      "name": "[variables('storageName')]",
      "location": "[parameters('location')]",
      "sku": {
          "name": "Standard_LRS"
      },
      "kind": "Storage",
      "properties": {}
    },
    {
      "type": "Microsoft.Authorization/roleAssignments",
      "apiVersion": "2020-04-01-preview",
      "name": "[parameters('roleNameGuid')]",
      "scope": "[concat('Microsoft.Storage/storageAccounts', '/', variables('storageName'))]",
      "dependsOn": [
          "[variables('storageName')]"
      ],
      "properties": {
        "roleDefinitionId": "[variables(parameters('builtInRoleType'))]",
        "principalId": "[parameters('principalId')]"
      }
    }
  ]
}

后续步骤Next steps