如何使用 PowerShell 管理指派

  • 發行項

重要

在 2026 年 7 月 11 日，藍圖 (預覽) 將會淘汰。 將現有的藍圖定義和指派移轉至範本規格和部署堆疊。 藍圖成品會轉換成用來定義部署堆疊的 ARM JSON 範本或 Bicep 檔案。 若要了解如何將成品撰寫為 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。

  1. 從系統管理 PowerShell 提示字元中，執行下列命令：

    # Install the Azure Blueprints module from PowerShell Gallery
Install-Module -Name Az.Blueprint

    注意

    如果已安裝 Az.Accounts，則可能需要使用 -AllowClobber 來強制安裝。

  2. 驗證已匯入模組，而且是正確的版本 (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 使用，以更明確地說明要傳回哪個藍圖定義。 相對於 Version，參數 -LatestPublished 會擷取最近發行的版本。

下列範例使用 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 會使用下列參數：

  • Name [必要]

    • 指定藍圖指派的名稱
    • 必須是唯一的且尚未存在於 SubscriptionId 中

  • Blueprint [必要]

    • 指定要指派的藍圖定義
    • 使用 Get-AzBlueprint 取得參考物件

  • Location [必要]

    • 指定要在其中建立系統指派受控識別和訂閱部署物件的區域

  • Subscription (選擇性)

    • 指定要部署指派的目的地訂閱
    • 如果未提供，則預設為目前的訂閱內容

  • Lock (選擇性)

    • 定義要用於已部署資源的藍圖資源鎖定
    • 支援的選項：None、AllResourcesReadOnly、AllResourcesDoNotDelete
    • 如果未提供，則預設為 None。

  • SystemAssignedIdentity (選擇性)

    • 選取以為指派建立系統指派的受控識別並部署資源
    • 「身分識別」參數集的預設值
    • 無法搭配 UserAssignedIdentity 使用

  • UserAssignedIdentity (選擇性)

    • 指定要用於指派和部署資源的使用者指派受控識別
    • 「身分識別」參數集的一部分
    • 無法搭配 SystemAssignedIdentity 使用

  • Parameter (選擇性)

    • 索引鍵/值組的雜湊表，用於設定藍圖指派的動態參數

    • 動態參數的預設值是定義中的 defaultValue

    • 如果未提供參數且沒有 defaultValue，則參數不可省略

      注意

      Parameter 不支援 secureStrings。

  • ResourceGroupParameter (選擇性)

    • 資源群組成品的雜湊表
    • 每個資源群組成品預留位置都有索引鍵/值組，可在該資源群組成品上動態設定 Name 和 Location
    • 如果未提供資源群組參數且沒有 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 屬性會設定為鎖定的一部分。 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 則例外。 只會更新所提供的值。

若要了解更新藍圖指派時會發生什麼情況，請參閱用於更新指派的規則。

  • Name [必要]

    • 指定要更新的藍圖指派名稱
    • 用於找出要更新的指派，而不是變更指派

  • Blueprint [必要]

    • 指定藍圖指派的藍圖定義
    • 使用 Get-AzBlueprint 取得參考物件
    • 用於找出要更新的指派，而不是變更指派

  • Location (選擇性)

    • 指定要在其中建立系統指派受控識別和訂閱部署物件的區域

  • Subscription (選擇性)

    • 指定要部署指派的目的地訂閱
    • 如果未提供，則預設為目前的訂閱內容
    • 用於找出要更新的指派，而不是變更指派

  • Lock (選擇性)

    • 定義要用於已部署資源的藍圖資源鎖定
    • 支援的選項：None、AllResourcesReadOnly、AllResourcesDoNotDelete

  • SystemAssignedIdentity (選擇性)

    • 選取以為指派建立系統指派的受控識別並部署資源
    • 「身分識別」參數集的預設值
    • 無法搭配 UserAssignedIdentity 使用

  • UserAssignedIdentity (選擇性)

    • 指定要用於指派和部署資源的使用者指派受控識別
    • 「身分識別」參數集的一部分
    • 無法搭配 SystemAssignedIdentity 使用

  • Parameter (選擇性)

    • 索引鍵/值組的雜湊表，用於設定藍圖指派的動態參數

    • 動態參數的預設值是定義中的 defaultValue

    • 如果未提供參數且沒有 defaultValue，則參數不可省略

      注意

      Parameter 不支援 secureStrings。

  • ResourceGroupParameter (選擇性)

    • 資源群組成品的雜湊表
    • 每個資源群組成品預留位置都有索引鍵/值組，可在該資源群組成品上動態設定 Name 和 Location
    • 如果未提供資源群組參數且沒有 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

下一步