Správa přiřazení pomocí PowerShellu

  • Článek

Důležité

11. července 2026 budou podrobné plány (Preview) zastaralé. Migrujte existující definice a přiřazení podrobných plánů do specifikací šablon a zásobníků nasazení. Artefakty podrobného plánu se mají převést na šablony JSON ARM nebo soubory Bicep, které se používají k definování zásobníků nasazení. Informace o tom, jak vytvořit artefakt jako prostředek ARM, najdete tady:

Přiřazení podrobného plánu je možné spravovat pomocí modulu Az.Blueprint Azure PowerShell. Modul podporuje načítání, vytváření, aktualizaci a odebírání přiřazení. Modul může také načíst podrobnosti o existujících definicích podrobných plánů. Tento článek popisuje, jak modul nainstalovat a začít ho používat.

Přidání modulu Az.Blueprint

Pokud chcete Azure PowerShell povolit správu přiřazení podrobných plánů, je nutné přidat modul. Tento modul je možné použít s místně nainstalovaným Prostředím PowerShell, s Azure Cloud Shell nebo s imagí Azure PowerShell Dockeru.

Základní požadavky

Modul Azure Blueprints vyžaduje následující software:

  • Azure PowerShell 1.5.0 nebo vyšší. Pokud ještě není nainstalovaný, postupujte podle těchto pokynů.
  • PowerShellGet 2.0.1 nebo novější. Pokud není nainstalovaný nebo aktualizovaný, postupujte podle těchto pokynů.

Instalace modulu

Modul Azure Blueprints pro PowerShell je Az.Blueprint.

  1. Na příkazovém řádku PowerShellu pro správu spusťte následující příkaz:

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

    Poznámka

    Pokud je az.Accounts už nainstalovaný, může být nutné použít -AllowClobber k vynucení instalace.

  2. Ověřte, že se modul naimportoval a má správnou verzi (0.2.6):

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

Získání definic podrobného plánu

Prvním krokem při práci s přiřazením je často získání odkazu na definici podrobného plánu. Rutina Get-AzBlueprint získá jednu nebo více definic podrobného plánu. Rutina může získat definice podrobného plánu ze skupiny pro správu nebo -ManagementGroupId {mgId} předplatného pomocí -SubscriptionId {subId}. Parametr Name získá definici podrobného plánu, ale musí se použít s ManagementGroupId nebo SubscriptionId. Verzi je možné použít s názvem , aby byla explicitnější o tom, která definice podrobného plánu se vrátí. Místo verze přepínač -LatestPublished uchopí naposledy publikovanou verzi.

Následující příklad používá Get-AzBlueprint k získání všech verzí definice podrobného plánu s názvem "101-blueprints-definition-subscription" z konkrétního předplatného reprezentované jako {subId}:

# 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

Příklad výstupu definice podrobného plánu s více verzemi vypadá takto:

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

Parametry podrobného plánu v definici podrobného plánu je možné rozbalit a poskytnout tak další informace.

$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

Získání přiřazení podrobného plánu

Pokud přiřazení podrobného plánu již existuje, můžete na něj získat odkaz pomocí rutiny Get-AzBlueprintAssignment . Rutina přebírá id předplatného a název jako volitelné parametry. Pokud id předplatného není zadané, použije se aktuální kontext předplatného.

Následující příklad používá Get-AzBlueprintAssignment k získání jednoho přiřazení podrobného plánu s názvem Assignment-lock-resource-groups z konkrétního předplatného reprezentované jako {subId}:

# 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

Příklad výstupu přiřazení podrobného plánu vypadá takto:

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

Vytváření přiřazení podrobného plánu

Pokud přiřazení podrobného plánu ještě neexistuje, můžete ho vytvořit pomocí rutiny New-AzBlueprintAssignment . Tato rutina používá následující parametry:

  • Název [povinné]

    • Určuje název přiřazení podrobného plánu.
    • Musí být jedinečný a v Id předplatného ještě neexistuje.

  • Podrobný plán [povinný]

    • Určuje definici podrobného plánu, která se má přiřadit.
    • Slouží k získání referenčního objektu.Get-AzBlueprint

  • Umístění [povinné]

    • Určuje oblast pro spravovanou identitu přiřazenou systémem a objekt nasazení předplatného, ve které se má vytvořit.

  • Předplatné (volitelné)

    • Určuje předplatné, do které se přiřazení nasadí.
    • Pokud není zadaný, ve výchozím nastavení se nastaví kontext aktuálního předplatného.

  • Zámek (volitelné)

    • Definuje uzamčení prostředků podrobného plánu , které se má použít pro nasazené prostředky.
    • Podporované možnosti: None, AllResourcesReadOnly, AllResourcesDoNotDelete
    • Pokud není k dispozici, výchozí hodnota je Žádná.

  • SystemAssignedIdentity (volitelné)

    • Výběrem vytvoříte spravovanou identitu přiřazenou systémem pro přiřazení a nasadíte prostředky.
    • Výchozí pro sadu parametrů identity
    • Nejde použít s userAssignedIdentity

  • UserAssignedIdentity (volitelné)

    • Určuje spravovanou identitu přiřazenou uživatelem, která se má použít pro přiřazení a nasazení prostředků.
    • Část sady parametrů identity
    • Nejde použít s SystemAssignedIdentity

  • Parametr (volitelné)

    • Tabulka hodnot hash párů klíč/hodnota pro nastavení dynamických parametrů pro přiřazení podrobného plánu

    • Výchozí hodnota dynamického parametru je defaultValue v definici.

    • Pokud parametr není zadaný a nemá žádnou hodnotu defaultValue, parametr není volitelný.

      Poznámka

      Parametr nepodporuje secureStrings.

  • ResourceGroupParameter (volitelné)

    • Tabulka hodnot hash artefaktů skupin prostředků
    • Každý zástupný symbol artefaktu skupiny prostředků obsahuje páry klíč/hodnota pro dynamické nastavení názvu a umístění v artefaktu dané skupiny prostředků.
    • Pokud parametr skupiny prostředků není zadaný a nemá žádnou hodnotu defaultValue, parametr skupiny prostředků není volitelný.

  • AssignmentFile (volitelné)

    • Cesta k souboru JSON reprezentace přiřazení podrobného plánu
    • Tento parametr je součástí sady parametrů PowerShellu, která obsahuje jenom name, blueprint a SubscriptionId a společné parametry.

Příklad 1: Zadání parametrů

Následující příklad vytvoří nové přiřazení verze 1.1 definice podrobného plánu my-blueprint načtené pomocí Get-AzBlueprint, nastaví spravovanou identitu a umístění objektu přiřazení na westus2, uzamkne prostředky pomocí AllResourcesReadOnly a nastaví tabulky hash pro Parametr i ResourceGroupParameter u konkrétního předplatného reprezentovaného jako {subId}:

# 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

Ukázkový výstup pro vytvoření přiřazení podrobného plánu vypadá takto:

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

Příklad 2: Použití souboru definice přiřazení JSON

Následující příklad vytvoří téměř stejné přiřazení jako příklad 1. Místo předání parametrů rutině ukazuje příklad použití souboru definice přiřazení JSON a parametru AssignmentFile . Vlastnost excludedPrincipals je navíc nakonfigurována jako součást zámků. Pro excludedPrincipals neexistuje parametr PowerShellu a vlastnost se dá nakonfigurovat pouze nastavením prostřednictvím souboru definice přiřazení 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'

Příklad souboru definice přiřazení JSON pro spravovanou identitu přiřazenou uživatelem najdete v textu požadavku v tématu Příklad: Přiřazení spravované identity přiřazené uživatelem pro rozhraní REST API.

Aktualizace přiřazení podrobného plánu

Někdy je potřeba aktualizovat přiřazení podrobného plánu, které už bylo vytvořeno. Rutina Set-AzBlueprintAssignment tuto akci zpracuje. Rutina přijímá většinu stejných parametrů jako rutina New-AzBlueprintAssignment a umožňuje aktualizaci všeho, co bylo u přiřazení nastaveno. Mezi výjimky patří Název, Podrobný plán a Id předplatného. Aktualizují se jenom zadané hodnoty.

Pokud chcete zjistit, co se stane při aktualizaci přiřazení podrobného plánu, přečtěte si pravidla pro aktualizaci přiřazení.

  • Název [povinné]

    • Určuje název přiřazení podrobného plánu, který se má aktualizovat.
    • Slouží k vyhledání přiřazení, které se má aktualizovat, nikoli ke změně přiřazení.

  • Podrobný plán [povinný]

    • Určuje definici podrobného plánu přiřazení podrobného plánu.
    • Slouží k získání referenčního objektu.Get-AzBlueprint
    • Slouží k vyhledání přiřazení, které se má aktualizovat, nikoli ke změně přiřazení.

  • Umístění (volitelné)

    • Určuje oblast pro spravovanou identitu přiřazenou systémem a objekt nasazení předplatného, ve které se má vytvořit.

  • Předplatné (volitelné)

    • Určuje předplatné, do které se přiřazení nasadí.
    • Pokud není zadaný, ve výchozím nastavení se nastaví kontext aktuálního předplatného.
    • Slouží k vyhledání přiřazení, které se má aktualizovat, nikoli ke změně přiřazení.

  • Zámek (volitelné)

  • SystemAssignedIdentity (volitelné)

    • Výběrem vytvoříte spravovanou identitu přiřazenou systémem pro přiřazení a nasadíte prostředky.
    • Výchozí pro sadu parametrů identity
    • Nejde použít s userAssignedIdentity

  • UserAssignedIdentity (volitelné)

    • Určuje spravovanou identitu přiřazenou uživatelem, která se má použít pro přiřazení a nasazení prostředků.
    • Část sady parametrů identity
    • Nejde použít s SystemAssignedIdentity

  • Parametr (volitelné)

    • Tabulka hodnot hash párů klíč/hodnota pro nastavení dynamických parametrů pro přiřazení podrobného plánu

    • Výchozí hodnota dynamického parametru je defaultValue v definici.

    • Pokud parametr není zadaný a nemá žádnou hodnotu defaultValue, parametr není volitelný.

      Poznámka

      Parametr nepodporuje secureStrings.

  • ResourceGroupParameter (volitelné)

    • Tabulka hodnot hash artefaktů skupin prostředků
    • Každý zástupný symbol artefaktu skupiny prostředků obsahuje páry klíč/hodnota pro dynamické nastavení názvu a umístění v artefaktu dané skupiny prostředků.
    • Pokud parametr skupiny prostředků není zadaný a nemá žádnou hodnotu defaultValue, parametr skupiny prostředků není volitelný.

Následující příklad aktualizuje přiřazení verze 1.1 definice podrobného plánu my-blueprint načtené Get-AzBlueprint změnou režimu uzamčení:

# 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

Ukázkový výstup pro vytvoření přiřazení podrobného plánu vypadá takto:

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

Odebrání přiřazení podrobného plánu

Když nastane čas na odebrání přiřazení podrobného plánu, rutina Remove-AzBlueprintAssignment tuto akci zpracuje. Rutina přijme název nebo InputObject a určí, které přiřazení podrobného plánu se má odebrat. Id předplatného je povinné a musí být zadané ve všech případech.

Následující příklad načte existující přiřazení podrobného plánu pomocí Get-AzBlueprintAssignment a pak ho odebere z konkrétního předplatného reprezentované jako {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}'

Příklad kódu

Když všechny kroky spojíte dohromady, následující příklad získá definici podrobného plánu, pak vytvoří, aktualizuje a odebere přiřazení podrobného plánu v konkrétním předplatném reprezentované jako {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

Další kroky