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

如何使用 PowerShell 管理分配

Important

Azure 蓝图（预览版）将于 2027 年 1 月 31 日停用，从 2026 年 7 月 31 日开始逐步停用。将现有蓝图定义和分配迁移到部署堆栈（建议）和模板规格。蓝图构件会被转换为用于定义部署堆栈的 ARM JSON 模板或 Bicep 文件。有关完整的分阶段时间线、影响和常见问题解答，请参阅Azure 蓝图停用或https://aka.ms/AzureBlueprintsRetirement。若要了解如何将工件编写为 ARM 资源，请参阅：

可以使用 Az.Blueprint Azure PowerShell 模块管理蓝图分配。该模块支持提取、创建、更新和删除分配。该模块还可以提取有关现有蓝图定义的详细信息。本文介绍如何安装模块并开始使用它。

添加 Az.Blueprint 模块

若要启用Azure PowerShell来管理蓝图分配，必须添加模块。此模块可与本地安装的 PowerShell、Azure Cloud Shell或 Azure PowerShell Docker 映像一起使用。

基本要求

Azure 蓝图模块需要以下软件：

Azure PowerShell 1.5.0 或更高版本。若尚未安装，请遵循这些说明。
PowerShellGet 2.0.1 或更高版本。如果未安装或更新，请按照以下说明操作。

安装此模块

PowerShell 的Azure 蓝图模块是 Az.Blueprint。

在管理 PowerShell 提示符下运行以下命令：
```
# Install the Azure Blueprints module from PowerShell Gallery
Install-Module -Name Az.Blueprint
```
Note

如果已安装 Az.Accounts，则可能需要使用 -AllowClobber 来强制安装。

验证模块是否已导入，并且是否为正确的版本（0.2.6）：

# Get a list of commands for the imported Az.Blueprint module
Get-Command -Module 'Az.Blueprint' -CommandType 'Cmdlet'

获取蓝图定义

处理分配的第一步通常是获取对蓝图定义的引用。此 Get-AzBlueprint cmdlet 获取一个或多个蓝图定义。该 cmdlet 可使用 -ManagementGroupId {mgId} 从管理组获取蓝图定义，也可使用 -SubscriptionId {subId} 从订阅获取蓝图定义。 Name 参数获取蓝图定义，但必须与 ManagementGroupId 或 SubscriptionId 一起使用。 Version 可以与 Name 一起使用，以更明确地指定返回哪个蓝图定义。开关 -LatestPublished（而非“Version”）可以获取最新发布的版本。

以下示例使用 Get-AzBlueprint 从以 {subId} 表示的特定订阅中获取名为“101-blueprints-definition-subscription”的蓝图定义的所有版本：

# Login first with Connect-AzAccount if not using Cloud Shell

# Get all versions of the blueprint definition in the specified subscription
$blueprints = Get-AzBlueprint -SubscriptionId '{subId}' -Name '101-blueprints-definition-subscription'

# Display the blueprint definition object
$blueprints

具有多个版本的蓝图定义的示例输出如下所示：

Name                 : 101-blueprints-definition-subscription
Id                   : /subscriptions/{subId}/providers/Microsoft.Blueprint/blueprints/101
                       -blueprints-definition-subscription
DefinitionLocationId : {subId}
Versions             : {1.0, 1.1}
TimeCreated          : 2019-02-25
TargetScope          : Subscription
Parameters           : {storageAccount_storageAccountType, storageAccount_location,
                       allowedlocations_listOfAllowedLocations, [Usergrouporapplicationname]:Reader_RoleAssignmentName}
ResourceGroups       : ResourceGroup

可以扩展蓝图定义上的蓝图参数，以提供更多信息。

$blueprints.Parameters

Key                                                    Value
---                                                    -----
storageAccount_storageAccountType                      Microsoft.Azure.Commands.Blueprint.Models.PSParameterDefinition
storageAccount_location                                Microsoft.Azure.Commands.Blueprint.Models.PSParameterDefinition
allowedlocations_listOfAllowedLocations                Microsoft.Azure.Commands.Blueprint.Models.PSParameterDefinition
[Usergrouporapplicationname]:Reader_RoleAssignmentName Microsoft.Azure.Commands.Blueprint.Models.PSParameterDefinition

获取蓝图分配

如果蓝图分配已存在，可以使用 Get-AzBlueprintAssignment cmdlet 获取对它的引用。该 cmdlet 采用 SubscriptionId 和 Name 作为可选参数。如果未指定 SubscriptionId ，则使用当前订阅上下文。

下面的示例使用 Get-AzBlueprintAssignment 从 {subId} 表示的特定订阅获取单个蓝图分配“Assignment-lock-resource-groups”：

# Login first with Connect-AzAccount if not using Cloud Shell

# Get the blueprint assignment in the specified subscription
$blueprintAssignment = Get-AzBlueprintAssignment -SubscriptionId '{subId}' -Name 'Assignment-lock-resource-groups'

# Display the blueprint assignment object
$blueprintAssignment

蓝图分配的示例输出如下所示：

Name              : Assignment-lock-resource-groups
Id                : /subscriptions/{subId}/providers/Microsoft.Blueprint/blueprintAssignme
                    nts/Assignment-lock-resource-groups
Scope             : /subscriptions/{subId}
LastModified      : 2019-02-19
LockMode          : AllResourcesReadOnly
ProvisioningState : Succeeded
Parameters        :
ResourceGroups    : ResourceGroup

创建蓝图分配任务

如果该蓝图分配尚不存在，则可以使用 New-AzBlueprintAssignment cmdlet 创建它。此 cmdlet 使用以下参数：

名称 [必需]
- 指定蓝图分配的名称
- 必须唯一，且不得已存在于 SubscriptionId 中
蓝图 [必需]
- 指定要分配的蓝图定义
- 使用 Get-AzBlueprint 获取引用对象
位置 [必需]
- 指定区域，以便在其中创建系统分配的托管标识和订阅部署对象
订阅（可选）
- 指定要将分配部署到的订阅
- 如果未提供，则默认使用当前订阅上下文
锁定（可选）
- 定义用于已部署资源的蓝图资源锁定
- 支持的选项： None、 AllResourcesReadOnly、 AllResourcesDoNotDelete
- 如果未提供，则默认为 None
SystemAssignedIdentity （可选）
- 选择此参数创建系统分配的托管标识，以用于分配并用于部署资源
- “identity”参数集的默认值
- 不能与 UserAssignedIdentity 一起使用
UserAssignedIdentity （可选）
- 指定用户分配的托管标识，以用于分配并用于部署资源
- “identity”参数集的一部分
- 不能与 SystemAssignedIdentity 一起使用
参数（可选）
- 用于设置蓝图分配的动态参数的键/值对的哈希表
- 动态参数的默认值是定义中的 defaultValue
- 如果未提供参数且没有 defaultValue，则参数不可选
  
  Note
  
  参数不支持 secureStrings。
ResourceGroupParameter （可选）
- 资源组项目的哈希表
- 每个资源组项目占位符都有键/值对，用于在该资源组项目上动态设置名称和位置
- 如果未提供资源组参数且没有 defaultValue，则资源组参数不是可选的
AssignmentFile （可选）
- 蓝图分配的 JSON 文件表示形式的路径
- 此参数是 PowerShell 参数集的一部分，仅包括 Name、 Blueprint 和 SubscriptionId，以及通用参数。

示例 1：提供参数

以下示例创建使用 Get-AzBlueprint 获取的“my-blueprint”蓝图定义“1.1”版本的新分配，将托管标识和分配对象位置设置为“westus2”，使用 AllResourcesReadOnly 锁定资源，并针对由 {subId} 表示的特定订阅，为 Parameter 和 ResourceGroupParameter 设置哈希表：

# Login first with Connect-AzAccount if not using Cloud Shell

# Get version '1.1' of the blueprint definition in the specified subscription
$bpDefinition = Get-AzBlueprint -SubscriptionId '{subId}' -Name 'my-blueprint' -Version '1.1'

# Create the hash table for Parameters
$bpParameters = @{storageAccount_storageAccountType='Standard_GRS'}

# Create the hash table for ResourceGroupParameters
# ResourceGroup is the resource group artifact placeholder name
$bpRGParameters = @{ResourceGroup=@{name='storage_rg';location='westus2'}}

# Create the new blueprint assignment
$bpAssignment = New-AzBlueprintAssignment -Name 'my-blueprint-assignment' -Blueprint $bpDefinition `
    -SubscriptionId '{subId}' -Location 'westus2' -Lock AllResourcesReadOnly `
    -Parameter $bpParameters -ResourceGroupParameter $bpRGParameters

用于创建蓝图分配的示例输出如下所示：

Name              : my-blueprint-assignment
Id                : /subscriptions/{subId}/providers/Microsoft.Blueprint/blueprintAssi
                    gnments/my-blueprint-assignment
Scope             : /subscriptions/{subId}
LastModified      : 2019-03-13
LockMode          : AllResourcesReadOnly
ProvisioningState : Creating
Parameters        : {storageAccount_storageAccountType}
ResourceGroups    : ResourceGroup

示例 2：使用 JSON 分配定义文件

以下示例创建与示例 1 几乎相同的分配。该示例演示如何使用 JSON 分配定义文件和 AssignmentFile 参数，而不是将参数传递给 cmdlet。此外，excludedPrincipals 属性作为 locks 的一部分进行配置。没有用于 excludedPrincipals 的 PowerShell 参数，并且该属性只能通过在 JSON 分配定义文件中进行设置来配置。

{
  "identity": {
    "type": "SystemAssigned"
  },
  "location": "westus2",
  "properties": {
    "description": "Assignment of the 101-blueprint-definition-subscription",
    "blueprintId": "/subscriptions/{subId}/providers/Microsoft.Blueprint/blueprints/101-blueprints-definition-subscription",
    "locks": {
      "mode": "AllResourcesReadOnly",
      "excludedPrincipals": [
          "7be2f100-3af5-4c15-bcb7-27ee43784a1f",
          "38833b56-194d-420b-90ce-cff578296714"
      ]
    },
    "parameters": {
      "storageAccount_storageAccountType": {
        "value": "Standard_GRS"
      }
    },
    "resourceGroups": {
      "ResourceGroup": {
        "name": "storage_rg",
        "location": "westus2"
      }
    }
  }
}

# Login first with Connect-AzAccount if not using Cloud Shell

# Create the new blueprint assignment
$bpAssignment = New-AzBlueprintAssignment -Name 'my-blueprint-assignment' -SubscriptionId '{subId}' `
    -AssignmentFile '.\assignment.json'

有关用户分配托管标识的 JSON 分配定义文件的示例，请参阅示例：使用 REST API 的用户分配托管标识进行分配的请求正文。

更新蓝图分配

有时可能需要更新已创建的蓝图分配任务。 Set-AzBlueprintAssignment cmdlet 负责处理此操作。该 cmdlet 使用了与 New-AzBlueprintAssignment cmdlet 大致相同的大多数参数，因此可以更新分配上已设置的任何内容。例外是 Name、 Blueprint 和 SubscriptionId。仅会更新已提供的值。

若要了解更新蓝图分配时会发生什么情况，请参阅更新分配的规则。

名称 [必需]
- 指定要更新的蓝图分配的名称
- 用于定位要更新的分配项，而不是用于更改分配项
蓝图 [必需]
- 指定蓝图分配的蓝图定义
- 使用 Get-AzBlueprint 获取引用对象
- 用于定位要更新的分配项，而不是修改该分配项
位置（可选）
- 指定区域，以便在其中创建系统分配的托管标识和订阅部署对象
订阅（可选）
- 指定要将分配部署到的订阅
- 如果未提供，则默认使用当前订阅上下文
- 用于定位要更新的分配项，而不是修改该分配项
锁定（可选）
- 定义用于已部署资源的蓝图资源锁定
- 支持的选项： None、 AllResourcesReadOnly、 AllResourcesDoNotDelete
SystemAssignedIdentity （可选）
- 选择此参数创建系统分配的托管标识，以用于分配并用于部署资源
- “identity”参数集的默认值
- 不能与 UserAssignedIdentity 一起使用
UserAssignedIdentity （可选）
- 指定用户分配的托管标识，以用于分配并用于部署资源
- “identity”参数集的一部分
- 不能与 SystemAssignedIdentity 一起使用
参数（可选）
- 用于设置蓝图分配的动态参数的键/值对的哈希表
- 动态参数的默认值是定义中的 defaultValue
- 如果未提供参数且没有 defaultValue，则参数不可选
  
  Note
  
  参数不支持 secureStrings。
ResourceGroupParameter （可选）
- 资源组项目的哈希表
- 每个资源组项目占位符都有键/值对，用于在该资源组项目上动态设置名称和位置
- 如果未提供资源组参数且没有 defaultValue，则资源组参数不是可选的

下面的示例通过更改锁模式更新使用 Get-AzBlueprint 提取的“my-blueprint”蓝图定义版本“1.1”的分配：

# Login first with Connect-AzAccount if not using Cloud Shell

# Get version '1.1' of the blueprint definition in the specified subscription
$bpDefinition = Get-AzBlueprint -SubscriptionId '{subId}' -Name 'my-blueprint' -Version '1.1'

# Update the existing blueprint assignment
$bpAssignment = Set-AzBlueprintAssignment -Name 'my-blueprint-assignment' -Blueprint $bpDefinition `
    -SubscriptionId '{subId}' -Lock AllResourcesDoNotDelete

用于创建蓝图分配的示例输出如下所示：

Name              : my-blueprint-assignment
Id                : /subscriptions/{subId}/providers/Microsoft.Blueprint/blueprintAssi
                    gnments/my-blueprint-assignment
Scope             : /subscriptions/{subId}
LastModified      : 2019-03-13
LockMode          : AllResourcesDoNotDelete
ProvisioningState : Updating
Parameters        : {storageAccount_storageAccountType}
ResourceGroups    : ResourceGroup

删除蓝图分配

当需要移除蓝图分配时，Remove-AzBlueprintAssignment cmdlet 命令会处理此操作。该 cmdlet 使用 Name 或 InputObject 来指定要删除哪个蓝图分配。 SubscriptionId是必需的 ，必须在所有情况下提供。

以下示例使用 Get-AzBlueprintAssignment 获取现有蓝图分配，然后将其从由 {subId} 表示的特定订阅中删除：

# Login first with Connect-AzAccount if not using Cloud Shell

# Get the blueprint assignment in the specified subscription
$blueprintAssignment = Get-AzBlueprintAssignment -Name 'Assignment-lock-resource-groups'

# Remove the existing blueprint assignment
Remove-AzBlueprintAssignment -InputObject $blueprintAssignment -SubscriptionId '{subId}'

代码示例

将所有步骤整合在一起后，以下示例首先获取蓝图定义，然后在由 {subId} 表示的特定订阅中创建、更新并删除蓝图分配：

# Login first with Connect-AzAccount if not using Cloud Shell

#region GetBlueprint
# Get version '1.1' of the blueprint definition in the specified subscription
$bpDefinition = Get-AzBlueprint -SubscriptionId '{subId}' -Name 'my-blueprint' -Version '1.1'
#endregion

#region CreateAssignment
# Create the hash table for Parameters
$bpParameters = @{storageAccount_storageAccountType='Standard_GRS'}

# Create the hash table for ResourceGroupParameters
# ResourceGroup is the resource group artifact placeholder name
$bpRGParameters = @{ResourceGroup=@{name='storage_rg';location='westus2'}}

# Create the new blueprint assignment
$bpAssignment = New-AzBlueprintAssignment -Name 'my-blueprint-assignment' -Blueprint $bpDefinition `
    -SubscriptionId '{subId}' -Location 'westus2' -Lock AllResourcesReadOnly `
    -Parameter $bpParameters -ResourceGroupParameter $bpRGParameters
#endregion CreateAssignment

# Wait for the blueprint assignment to finish deployment prior to the next steps

#region UpdateAssignment
# Update the existing blueprint assignment
$bpAssignment = Set-AzBlueprintAssignment -Name 'my-blueprint-assignment' -Blueprint $bpDefinition `
    -SubscriptionId '{subId}' -Lock AllResourcesDoNotDelete
#endregion UpdateAssignment

# Wait for the blueprint assignment to finish deployment prior to the next steps

#region RemoveAssignment
# Remove the existing blueprint assignment
Remove-AzBlueprintAssignment -InputObject $bpAssignment -SubscriptionId '{subId}'
#endregion

后续步骤

了解蓝图生命周期。
了解如何使用静态和动态参数。
了解如何自定义蓝图排序顺序。
了解如何利用蓝图资源锁定。
通过常规故障排除解决蓝图分配过程中的问题。

反馈

此页面是否有帮助？

Last updated on 2026-07-02