Toewijzingen beheren met PowerShell

  • Artikel

Belangrijk

Op 11 juli 2026 worden blauwdrukken (preview) afgeschaft. Migreer uw bestaande blauwdrukdefinities en -toewijzingen naar sjabloonspecificaties en implementatiestacks. Blauwdrukartefacten moeten worden geconverteerd naar ARM JSON-sjablonen of Bicep-bestanden die worden gebruikt om implementatiestacks te definiëren. Zie voor meer informatie over het ontwerpen van een artefact als een ARM-resource:

Een blauwdruktoewijzing kan worden beheerd met behulp van de module Az.Blueprint Azure PowerShell. De module ondersteunt het ophalen, maken, bijwerken en verwijderen van toewijzingen. De module kan ook details over bestaande blauwdrukdefinities ophalen. In dit artikel wordt beschreven hoe u de module installeert en gaat gebruiken.

De Module Az.Blueprint toevoegen

Als u Azure PowerShell blauwdruktoewijzingen wilt beheren, moet de module worden toegevoegd. Deze module kan worden gebruikt met lokaal geïnstalleerde PowerShell, met Azure Cloud Shell of met de Azure PowerShell Docker-installatiekopie.

Basisvereisten

Voor de Azure Blueprints-module is de volgende software vereist:

  • Azure PowerShell 1.5.0 of hoger. Als deze nog niet is geïnstalleerd, volgt u deze instructies op.
  • PowerShellGet 2.0.1 of hoger. Als deze nog niet is geïnstalleerd of bijgewerkt, volgt u deze instructies op.

Installeer de module

De Azure Blueprints-module voor PowerShell is Az.Blueprint.

  1. Voer vanuit een PowerShell-prompt met beheerdersrechten de volgende opdracht uit:

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

    Notitie

    Als Az.Accounts al is geïnstalleerd, kan het nodig zijn om de -AllowClobber installatie af te dwingen.

  2. Controleer of de module is geïmporteerd en de juiste versie heeft (0.2.6):

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

Blauwdrukdefinities ophalen

De eerste stap bij het werken met een toewijzing bestaat vaak uit het verkrijgen van een verwijzing naar een blauwdrukdefinitie. De Get-AzBlueprint cmdlet haalt een of meer blauwdrukdefinities op. De cmdlet kan blauwdrukdefinities ophalen uit een beheergroep met -ManagementGroupId {mgId} of een abonnement met -SubscriptionId {subId}. Met de parameter Name wordt een blauwdrukdefinitie opgehaald, maar deze moet worden gebruikt met ManagementGroupId of SubscriptionId. Versie kan worden gebruikt met Naam om explicieter te zijn over welke blauwdrukdefinitie wordt geretourneerd. In plaats van Versie wordt met de schakeloptie -LatestPublished de meest recent gepubliceerde versie opgehaald.

In het volgende voorbeeld wordt gebruikt Get-AzBlueprint om alle versies van een blauwdrukdefinitie met de naam '101-blueprints-definition-subscription' op te halen uit een specifiek abonnement dat wordt weergegeven als {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

De voorbeelduitvoer voor een blauwdrukdefinitie met meerdere versies ziet er als volgt uit:

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

De blauwdrukparameters in de blauwdrukdefinitie kunnen worden uitgebreid om meer informatie te bieden.

$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

Blauwdruktoewijzingen ophalen

Als de blauwdruktoewijzing al bestaat, kunt u er een verwijzing naar krijgen met de Get-AzBlueprintAssignment cmdlet. De cmdlet gebruikt SubscriptionId en Name als optionele parameters. Als SubscriptionId niet is opgegeven, wordt de huidige abonnementscontext gebruikt.

In het volgende voorbeeld wordt gebruikt Get-AzBlueprintAssignment om één blauwdruktoewijzing op te halen met de naam 'Assignment-lock-resource-groups' van een specifiek abonnement dat wordt weergegeven als {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

De voorbeelduitvoer voor een blauwdruktoewijzing ziet er als volgt uit:

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

Blauwdruktoewijzingen maken

Als de blauwdruktoewijzing nog niet bestaat, kunt u deze maken met de New-AzBlueprintAssignment cmdlet. Deze cmdlet gebruikt de volgende parameters:

  • Naam [vereist]

    • Hiermee geeft u de naam van de blauwdruktoewijzing op
    • Moet uniek zijn en nog niet bestaan in SubscriptionId

  • Blauwdruk [vereist]

    • Hiermee geeft u de blauwdrukdefinitie toe te wijzen
    • Gebruik Get-AzBlueprint om het referentieobject op te halen

  • Locatie [vereist]

    • Hiermee geeft u de regio op voor het door het systeem toegewezen beheerde identiteit en abonnementsimplementatieobject dat moet worden gemaakt in

  • Abonnement (optioneel)

    • Hiermee geeft u het abonnement op waarin de toewijzing wordt geïmplementeerd
    • Als deze niet is opgegeven, wordt standaard de huidige abonnementscontext gebruikt

  • Vergrendelen (optioneel)

    • Definieert de blauwdrukresourcevergrendeling die moet worden gebruikt voor geïmplementeerde resources
    • Ondersteunde opties: None, AllResourcesReadOnly, AllResourcesDoNotDelete
    • Als deze niet is opgegeven, wordt standaard ingesteld op Geen

  • SystemAssignedIdentity (optioneel)

    • Selecteer om een door het systeem toegewezen beheerde identiteit te maken voor de toewijzing en om de resources te implementeren
    • Standaardinstelling voor de parameterset 'identiteit'
    • Kan niet worden gebruikt met UserAssignedIdentity

  • UserAssignedIdentity (optioneel)

    • Hiermee geeft u de door de gebruiker toegewezen beheerde identiteit op die moet worden gebruikt voor de toewijzing en om de resources te implementeren
    • Onderdeel van de parameterset 'identiteit'
    • Kan niet worden gebruikt met SystemAssignedIdentity

  • Parameter (optioneel)

    • Een hashtabel met sleutel-waardeparen voor het instellen van dynamische parameters voor de blauwdruktoewijzing

    • De standaardwaarde voor een dynamische parameter is de standaardwaarde in de definitie

    • Als er geen parameter is opgegeven en geen defaultValue heeft, is de parameter niet optioneel

      Notitie

      Parameter biedt geen ondersteuning voor secureStrings.

  • ResourceGroupParameter (optioneel)

    • Een hashtabel met resourcegroepartefacten
    • Elke tijdelijke aanduiding voor een resourcegroepartefact bevat sleutel-waardeparen voor het dynamisch instellen van naam en locatie op dat resourcegroepartefact
    • Als er geen resourcegroepparameter is opgegeven en geen defaultValue heeft, is de parameter van de resourcegroep niet optioneel

  • Toewijzingsbestand (optioneel)

    • Het pad naar een JSON-bestandsweergave van een blauwdruktoewijzing
    • Deze parameter maakt deel uit van een PowerShell-parameterset die alleen Name, Blueprint en SubscriptionId bevat, plus de algemene parameters.

Voorbeeld 1: Parameters opgeven

In het volgende voorbeeld wordt een nieuwe toewijzing gemaakt van versie '1.1' van de blauwdrukdefinitie 'my-blueprint', opgehaald met Get-AzBlueprint, wordt de beheerde identiteit en de locatie van het toewijzingsobject ingesteld op 'westus2', worden de resources vergrendeld met AllResourcesReadOnly en worden de hash-tabellen ingesteld voor parameter enResourceGroupParameter voor een specifiek abonnement dat wordt weergegeven als {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

De voorbeelduitvoer voor het maken van een blauwdruktoewijzing ziet er als volgt uit:

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

Voorbeeld 2: Een JSON-toewijzingsdefinitiebestand gebruiken

In het volgende voorbeeld wordt bijna dezelfde toewijzing gemaakt als in voorbeeld 1. In plaats van parameters door te geven aan de cmdlet, toont het voorbeeld het gebruik van een JSON-toewijzingsdefinitiebestand en de parameter AssignmentFile . Daarnaast wordt de eigenschap excludedPrincipals geconfigureerd als onderdeel van vergrendelingen. Er is geen PowerShell-parameter voor excludedPrincipals en de eigenschap kan alleen worden geconfigureerd door deze in te stellen via het JSON-toewijzingsdefinitiebestand.

{
  "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'

Zie voor een voorbeeld van het JSON-toewijzingsdefinitiebestand voor een door de gebruiker toegewezen beheerde identiteit de aanvraagbody in Voorbeeld: Toewijzing met door de gebruiker toegewezen beheerde identiteit voor REST API.

Blauwdruktoewijzingen bijwerken

Soms is het nodig om een blauwdruktoewijzing bij te werken die al is gemaakt. De Set-AzBlueprintAssignment cmdlet verwerkt deze actie. De cmdlet gebruikt de meeste parameters die de New-AzBlueprintAssignment cmdlet doet, zodat alles wat voor de toewijzing is ingesteld, kan worden bijgewerkt. De uitzonderingen zijn de Naam, Blauwdruk en SubscriptionId. Alleen de opgegeven waarden worden bijgewerkt.

Zie Regels voor het bijwerken van toewijzingen voor meer informatie over wat er gebeurt bij het bijwerken van een blauwdruktoewijzing.

  • Naam [vereist]

    • Hiermee geeft u de naam op van de blauwdruktoewijzing die moet worden bijgewerkt
    • Wordt gebruikt om de toewijzing te vinden die moet worden bijgewerkt, niet om de toewijzing te wijzigen

  • Blauwdruk [vereist]

    • Hiermee geeft u de blauwdrukdefinitie van de blauwdruktoewijzing op
    • Gebruik Get-AzBlueprint om het referentieobject op te halen
    • Wordt gebruikt om de toewijzing te vinden die moet worden bijgewerkt, niet om de toewijzing te wijzigen

  • Locatie (optioneel)

    • Hiermee geeft u de regio op voor het door het systeem toegewezen beheerde identiteit en abonnementsimplementatieobject dat moet worden gemaakt in

  • Abonnement (optioneel)

    • Hiermee geeft u het abonnement op waarin de toewijzing wordt geïmplementeerd
    • Als deze niet is opgegeven, wordt standaard de huidige abonnementscontext gebruikt
    • Wordt gebruikt om de toewijzing te vinden die moet worden bijgewerkt, niet om de toewijzing te wijzigen

  • Vergrendelen (optioneel)

    • Definieert de blauwdrukresourcevergrendeling die moet worden gebruikt voor geïmplementeerde resources
    • Ondersteunde opties: None, AllResourcesReadOnly, AllResourcesDoNotDelete

  • SystemAssignedIdentity (optioneel)

    • Selecteer om een door het systeem toegewezen beheerde identiteit te maken voor de toewijzing en om de resources te implementeren
    • Standaardinstelling voor de parameterset 'identiteit'
    • Kan niet worden gebruikt met UserAssignedIdentity

  • UserAssignedIdentity (optioneel)

    • Hiermee geeft u de door de gebruiker toegewezen beheerde identiteit op die moet worden gebruikt voor de toewijzing en om de resources te implementeren
    • Onderdeel van de parameterset 'identiteit'
    • Kan niet worden gebruikt met SystemAssignedIdentity

  • Parameter (optioneel)

    • Een hashtabel met sleutel-waardeparen voor het instellen van dynamische parameters voor de blauwdruktoewijzing

    • De standaardwaarde voor een dynamische parameter is de standaardwaarde in de definitie

    • Als er geen parameter is opgegeven en geen defaultValue heeft, is de parameter niet optioneel

      Notitie

      Parameter biedt geen ondersteuning voor secureStrings.

  • ResourceGroupParameter (optioneel)

    • Een hashtabel met resourcegroepartefacten
    • Elke tijdelijke aanduiding voor een resourcegroepartefact bevat sleutel-waardeparen voor het dynamisch instellen van naam en locatie op dat resourcegroepartefact
    • Als er geen resourcegroepparameter is opgegeven en geen defaultValue heeft, is de parameter van de resourcegroep niet optioneel

In het volgende voorbeeld wordt de toewijzing van versie '1.1' van de blauwdrukdefinitie 'my-blueprint' bijgewerkt met Get-AzBlueprint door de vergrendelingsmodus te wijzigen:

# 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

De voorbeelduitvoer voor het maken van een blauwdruktoewijzing ziet er als volgt uit:

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

Blauwdruktoewijzingen verwijderen

Wanneer het tijd is om een blauwdruktoewijzing te verwijderen, verwerkt de Remove-AzBlueprintAssignment cmdlet deze actie. De cmdlet gebruikt Name of InputObject om op te geven welke blauwdruktoewijzing moet worden verwijderd. SubscriptionId is vereist en moet in alle gevallen worden opgegeven.

In het volgende voorbeeld wordt een bestaande blauwdruktoewijzing opgehaald met Get-AzBlueprintAssignment en vervolgens verwijderd uit het specifieke abonnement dat wordt weergegeven als {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}'

Voorbeeld van code

Als u alle stappen samenbrengt, haalt het volgende voorbeeld de blauwdrukdefinitie op en wordt vervolgens een blauwdruktoewijzing gemaakt, bijgewerkt en verwijderd in het specifieke abonnement dat wordt weergegeven als {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

Volgende stappen