Toewijzingen beheren met PowerShell

Important

Azure Blueprints (preview) wordt op 31 januari 2027 buiten gebruik gesteld met een gefaseerde buitengebruikstelling vanaf 31 juli 2026. Migreer uw bestaande blauwdrukdefinities en -toewijzingen naar implementatiestacks (aanbevolen) en sjabloonspecificaties. Blueprint-artefacten worden omgezet in ARM JSON-sjablonen of Bicep-bestanden die worden gebruikt om deploymentstacks te definiëren. Zie voor de volledige gefaseerde tijdlijn, impact en veelgestelde vragen Azure Blueprints buitengebruikstelling of https://aka.ms/AzureBlueprintsRetirement. Voor instructies over het opstellen van een artefact als een ARM-resource, zie:

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 ophalen over bestaande blauwdrukdefinities. In dit artikel wordt beschreven hoe u de module installeert en deze gaat gebruiken.

De Az.Blueprint-module toevoegen

Als u Azure PowerShell wilt inschakelen voor het beheren van blauwdruktoewijzingen, 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ën.

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 niet is geïnstalleerd of bijgewerkt, volgt u deze instructies.

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

    Note

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

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

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

Blueprint-definities ophalen

De eerste stap om met een toewijzing te werken, is vaak het verkrijgen van een verwijzing naar een blueprint-definitie. 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}. De naamparameter haalt een blauwdrukdefinitie op, maar moet worden gebruikt met ManagementGroupId of SubscriptionId. Versie kan worden gebruikt met Name om explicieter te zijn over welke blauwdrukdefinitie wordt geretourneerd. In plaats van versie haalt de schakeloptie -LatestPublished de laatst gepubliceerde versie op.

In het volgende voorbeeld Get-AzBlueprint worden alle versies van een blauwdrukdefinitie met de naam 101-blueprints-definition-subscription opgehaald 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 voor meer informatie.

$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 ernaar verwijzen met de cmdlet Get-AzBlueprintAssignment. De cmdlet gebruikt SubscriptionId en Name als optionele parameters. Als SubscriptionId niet is opgegeven, wordt de huidige abonnementscontext gebruikt.

In het volgende voorbeeld wordt Get-AzBlueprintAssignment gebruikt om één blueprinttoewijzing met de naam 'Assignment-lock-resource-groups' op te halen 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

Blueprinttoewijzingen 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 niet al bestaan in SubscriptionId

  • Blauwdruk [vereist]

    • Hiermee geeft u de blauwdrukdefinitie op die wordt toegewezen
    • Gebruiken Get-AzBlueprint om het referentieobject op te halen

  • Locatie [vereist]

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

  • Abonnement (optioneel)

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

  • Vergrendelen (optioneel)

    • Definieert de blueprint-resourcevergrendeling die moet worden gebruikt voor geïmplementeerde resources
    • Ondersteunde opties: Geen, AllResourcesReadOnly, AllResourcesDoNotDelete
    • Als dit niet is opgegeven, wordt standaard ingesteld op Geen

  • SystemAssignedIdentity (optioneel)

    • Selecteer deze optie om een door het systeem toegewezen beheerde identiteit te maken voor de toewijzing en om de resources te implementeren
    • Standaardwaarde 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 hash-tabel met sleutel-/waardeparen voor het instellen van dynamische parameters voor de blauwdruktoewijzing

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

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

      Note

      De parameter biedt geen ondersteuning voor secureStrings.

  • ResourceGroupParameter (optioneel)

    • Een hash-tabel met artefacten van resourcegroepen
    • Elke tijdelijke aanduiding voor resourcegroepartefacten heeft sleutel-waardeparen voor het dynamisch instellen van naam en locatie op dat artefact van de resourcegroep
    • Als er geen parameter voor een resourcegroep is opgegeven en geen defaultValue heeft, is de parameter van de resourcegroep niet optioneel

  • AssignmentFile (optioneel)

    • Het pad naar een JSON-bestandsweergave van een blauwdruktoewijzing
    • Deze parameter maakt deel uit van een PowerShell-parameterset die alleen naam, blauwdruk 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 hashtabellen ingesteld voor zowel parameter als ResourceGroupParameter 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 nagenoeg 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'

Voor een voorbeeld van het JSON-toewijzingsdefinitiebestand voor een door de gebruiker toegewezen beheerde identiteit, raadpleegt u de hoofdtekst van de aanvraag in voorbeeld: Toewijzing met door de gebruiker toegewezen beheerde identiteit voor REST API.

Toewijzingen voor sjablonen bijwerken

Soms is het nodig om een blueprint-toewijzing bij te werken die al is aangemaakt. De Set-AzBlueprintAssignment cmdlet verwerkt deze actie. De cmdlet neemt grotendeels dezelfde parameters als de New-AzBlueprintAssignment-cmdlet, waardoor alles wat voor de toewijzing is ingesteld, kan worden bijgewerkt. De uitzonderingen zijn de naam, blauwdruk en SubscriptionId. Alleen de opgegeven waarden worden bijgewerkt.

Als u wilt weten wat er gebeurt wanneer u een blauwdruktoewijzing bijwerkt, raadpleegt u de regels voor het bijwerken van toewijzingen.

  • Naam [vereist]

    • Hiermee geeft u de naam 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 wordt de blauwdrukdefinitie van de blauwdruktoewijzing opgegeven
    • Gebruiken 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 voor de door het systeem toegewezen beheerde identiteit en het abonnementsimplementatieobject dat moet worden gemaakt in

  • Abonnement (optioneel)

    • Hiermee geeft u het abonnement op waarnaar de toewijzing is geïmplementeerd
    • Als dit 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 blueprint-resourcevergrendeling die moet worden gebruikt voor geïmplementeerde resources
    • Ondersteunde opties: Geen, AllResourcesReadOnly, AllResourcesDoNotDelete

  • SystemAssignedIdentity (optioneel)

    • Selecteer deze optie om een door het systeem toegewezen beheerde identiteit te maken voor de toewijzing en om de resources te implementeren
    • Standaardwaarde 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 hash-tabel met sleutel-/waardeparen voor het instellen van dynamische parameters voor de blauwdruktoewijzing

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

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

      Note

      De parameter biedt geen ondersteuning voor secureStrings.

  • ResourceGroupParameter (optioneel)

    • Een hash-tabel met artefacten van resourcegroepen
    • Elke tijdelijke aanduiding voor resourcegroepartefacten heeft sleutel-waardeparen voor het dynamisch instellen van naam en locatie op dat artefact van de resourcegroep
    • Als er geen parameter voor een resourcegroep is opgegeven en geen defaultValue heeft, is de parameter van de resourcegroep niet optioneel

In het volgende voorbeeld wordt de toekenning van versie '1.1' van de blauwdrukdefinitie 'my-blueprint', opgehaald met Get-AzBlueprint, bijgewerkt 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 en Get-AzBlueprintAssignment 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, wordt in het volgende voorbeeld de blauwdrukdefinitie opgehaald, 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 

  • Last updated on