在 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. 角色分配是扩展资源类型。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.

备注

scope 属性仅适用于扩展资源类型。The scope property is only available to extension resource types. 若要为非扩展类型的资源类型指定其他范围，请使用嵌套部署或链接部署。To specify a different scope for a resource type that isn't an extension type, use a nested or linked deployment. 有关详细信息，请参阅资源组部署、订阅部署、管理组部署和租户部署。For more information, see resource group deployments, subscription deployments, management group deployments, and tenant deployments.

在部署范围内应用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 run in error like Unable to download deployment content sometime.

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

  1. 复制模板 URI，通过更改前缀、中缀和模板文件名来转换 URI。Copy the template URI, convert the URI by changing the prefix, infix, and tempalte file name. 例如，源 URI 是 https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/101-cosmosdb-sql-autoscale/azuredeploy.jsonFor exsample: the origin URI is https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/101-cosmosdb-sql-autoscale/azuredeploy.json

    类别Category 原始值Original value 转换后的值Converted value 操作Action
    前缀Prefix https://raw.githubusercontent.com https://github.com 更新Update
    中辍Infix blob 在 master 或 main 之前添加分支名称Add before master or main branch name
    模板文件名Template file name azuredeploy.jsonazuredeploy.json 你的下载模板文件名your download tempalte file name updateupdate

    修改后，转换后的 URI 看起来将类似于 https://github.com/Azure/azure-quickstart-templates/blob/master/101-cosmosdb-sql-autoscale/azuredeploy.json。After modified, the converted URI will show like https://github.com/Azure/azure-quickstart-templates/blob/master/101-cosmosdb-sql-autoscale/azuredeploy.json.

  2. 复制转换后的 URI，并在 Internet 浏览器中手动下载特定的模板内容。Copy the converted URI and download the specific template content in Internet browsers manully.

  3. 修改从 GitHub 存储库下载或引用的模板，以适应 Azure 中国云环境。Modify the templates you downloaded or referenced from the GitHub Repo in order to fit in the Azure China Cloud Environment. 例如，替换某些终结点（将“blob.core.windows.net”替换为“blob.core.chinacloudapi.cn”，将“cloudapp.azure.com”替换为“chinacloudapp.cn”）；必要时更改某些不受支持的位置、VM 映像、VM 大小、SKU 以及资源提供程序的 API 版本。For example, replace some endpoints -- "blob.core.windows.net" by "blob.core.chinacloudapi.cn", "cloudapp.azure.com" by "chinacloudapp.cn"; change some unsupported Location,VM images, VM sizes, SKU, and resource-provider's API Version when necessary.

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

    语言类别Language category 参考链接Reference link 操作Action
    PowerShellPowerShell New-AzResourceGroupDeployment 将 -TemplateUri 替换为 -TemplateFileReplace -TemplateUri with -TemplateFile
    如有必要，请按照前面的步骤下载 --TemplateParameterUri 内容并在 cmdlet 中替换为 --TemplateParameterFile。Follow the previous steps to download the --TemplateParameterUri content and repalce with --TemplateParameterFile in cmdlet when necessary.
    Azure CLIAzure CLI 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