Dela via

Hantera tilldelningar med PowerShell

  • Artikel

Viktigt

Den 11 juli 2026 blir skisser (förhandsversion) inaktuella. Migrera dina befintliga skissdefinitioner och tilldelningar till mallspecifikationer och distributionsstackar. Skissartefakter ska konverteras till ARM JSON-mallar eller Bicep-filer som används för att definiera distributionsstackar. Information om hur du skapar en artefakt som en ARM-resurs finns i:

En skisstilldelning kan hanteras med hjälp av modulen Az.Blueprint Azure PowerShell. Modulen stöder hämtning, skapande, uppdatering och borttagning av tilldelningar. Modulen kan också hämta information om befintliga skissdefinitioner. Den här artikeln beskriver hur du installerar modulen och börjar använda den.

Lägg till Az.Blueprint-modulen

Om du vill aktivera Azure PowerShell för att hantera skisstilldelningar måste modulen läggas till. Den här modulen kan användas med lokalt installerat PowerShell, med Azure Cloud Shell eller med Azure PowerShell Docker-avbildningen.

Grundläggande krav

Azure Blueprints-modulen kräver följande programvara:

Installera modulen

Azure Blueprints-modulen för PowerShell är Az.Blueprint.

  1. Från en administrativ PowerShell-prompt kör du följande kommando:

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

    Anteckning

    Om Az.Accounts redan är installerat kan det vara nödvändigt att använda -AllowClobber för att tvinga installationen.

  2. Kontrollera att modulen har importerats och är rätt version (0.2.6):

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

Hämta skissdefinitioner

Det första steget för att arbeta med en tilldelning är ofta att få en referens till en skissdefinition. Cmdleten Get-AzBlueprint hämtar en eller flera skissdefinitioner. Cmdleten kan hämta skissdefinitioner från en hanteringsgrupp med -ManagementGroupId {mgId} eller en prenumeration med -SubscriptionId {subId}. Parametern Namn hämtar en skissdefinition, men måste användas med ManagementGroupId eller SubscriptionId. Version kan användas med Namn för att vara mer explicit om vilken skissdefinition som returneras. I stället för Version hämtar växeln -LatestPublished den senast publicerade versionen.

I följande exempel används Get-AzBlueprint för att hämta alla versioner av en skissdefinition med namnet "101-blueprints-definition-subscription" från en specifik prenumeration som representeras som {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

Exempelutdata för en skissdefinition med flera versioner ser ut så här:

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

Skissparametrarna i skissdefinitionen kan utökas för att ge mer information.

$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

Hämta skisstilldelningar

Om skisstilldelningen redan finns kan du hämta en referens till den med cmdleten Get-AzBlueprintAssignment . Cmdleten tar SubscriptionId och Name som valfria parametrar. Om SubscriptionId inte har angetts används den aktuella prenumerationskontexten.

I följande exempel används Get-AzBlueprintAssignment för att hämta en enda skisstilldelning med namnet "Assignment-lock-resource-groups" från en specifik prenumeration som representeras som {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

Exempelutdata för en skisstilldelning ser ut så här:

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

Skapa skisstilldelningar

Om skisstilldelningen inte finns ännu kan du skapa den med cmdleten New-AzBlueprintAssignment . Den här cmdleten använder följande parametrar:

  • Namn [krävs]

    • Anger namnet på skisstilldelningen
    • Måste vara unikt och finns inte redan i SubscriptionId

  • Skiss [krävs]

    • Anger skissdefinitionen som ska tilldelas
    • Använd Get-AzBlueprint för att hämta referensobjektet

  • Plats [krävs]

    • Anger regionen för den systemtilldelade hanterade identiteten och prenumerationsdistributionsobjektet som ska skapas i

  • Prenumeration (valfritt)

    • Anger den prenumeration som tilldelningen distribueras till
    • Om det inte anges används standardinställningen för den aktuella prenumerationskontexten

  • Lås (valfritt)

    • Definierar den skissresurslåsning som ska användas för distribuerade resurser
    • Alternativ som stöds: None, AllResourcesReadOnly, AllResourcesDoNotDelete
    • Om det inte anges är standardvärdet Ingen

  • SystemAssignedIdentity (valfritt)

    • Välj att skapa en systemtilldelad hanterad identitet för tilldelningen och distribuera resurserna
    • Standard för parameteruppsättningen "identitet"
    • Det går inte att använda med UserAssignedIdentity

  • UserAssignedIdentity (valfritt)

    • Anger den användartilldelade hanterade identiteten som ska användas för tilldelningen och för att distribuera resurserna
    • Del av parameteruppsättningen "identitet"
    • Det går inte att använda med SystemAssignedIdentity

  • Parameter (valfritt)

    • En hash-tabell med nyckel/värde-par för att ange dynamiska parametrar för skisstilldelningen

    • Standard för en dynamisk parameter är defaultValue i definitionen

    • Om en parameter inte tillhandahålls och inte har något defaultValue är parametern inte valfri

      Anteckning

      Parametern stöder inte secureStrings.

  • ResourceGroupParameter (valfritt)

    • En hash-tabell med resursgruppsartefakter
    • Varje resursgruppsartefaktplatshållare har nyckel/värde-par för dynamisk inställning av namn och plats för resursgruppens artefakt
    • Om en resursgruppsparameter inte tillhandahålls och inte har någon defaultValue är resursgruppsparametern inte valfri

  • AssignmentFile (valfritt)

    • Sökvägen till en JSON-filrepresentation av en skisstilldelning
    • Den här parametern är en del av en PowerShell-parameteruppsättning som endast innehåller Namn, Skiss och SubscriptionId, plus de vanliga parametrarna.

Exempel 1: Ange parametrar

I följande exempel skapas en ny tilldelning av version 1.1 av skissdefinitionen "my-blueprint" som hämtats med Get-AzBlueprint, anger platsen för den hanterade identiteten och tilldelningsobjektet till "westus2", låser resurserna med AllResourcesReadOnly och anger hash-tabellerna för både Parameter och ResourceGroupParameter för en specifik prenumeration som representeras som {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

Exempelutdata för att skapa en skisstilldelning ser ut så här:

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

Exempel 2: Använd en JSON-tilldelningsdefinitionsfil

I följande exempel skapas nästan samma tilldelning som exempel 1. I stället för att skicka parametrar till cmdleten visar exemplet användning av en JSON-tilldelningsdefinitionsfil och parametern AssignmentFile . Dessutom konfigureras egenskapen excludedPrincipals som en del av låsen. Det finns ingen PowerShell-parameter för excludedPrincipals och egenskapen kan bara konfigureras genom att ange den via JSON-tilldelningsdefinitionsfilen.

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

Ett exempel på JSON-tilldelningsdefinitionsfilen för en användartilldelad hanterad identitet finns i begärandetexten i Exempel: Tilldelning med användartilldelad hanterad identitet för REST API.

Uppdatera skisstilldelningar

Ibland är det nödvändigt att uppdatera en skisstilldelning som redan har skapats. Cmdleten Set-AzBlueprintAssignment hanterar den här åtgärden. Cmdleten tar de flesta av samma parametrar som cmdleten New-AzBlueprintAssignment gör, vilket gör att allt som har angetts för tilldelningen kan uppdateras. Undantagen är Namn, Skiss och SubscriptionId. Endast de angivna värdena uppdateras.

Information om vad som händer när du uppdaterar en skisstilldelning finns i Regler för uppdatering av tilldelningar.

  • Namn [krävs]

    • Anger namnet på skisstilldelningen som ska uppdateras
    • Används för att hitta tilldelningen som ska uppdateras, inte för att ändra tilldelningen

  • Skiss [krävs]

    • Anger skissdefinitionen för skisstilldelningen
    • Använd Get-AzBlueprint för att hämta referensobjektet
    • Används för att hitta tilldelningen som ska uppdateras, inte för att ändra tilldelningen

  • Plats (valfritt)

    • Anger regionen för den systemtilldelade hanterade identiteten och prenumerationsdistributionsobjektet som ska skapas i

  • Prenumeration (valfritt)

    • Anger den prenumeration som tilldelningen distribueras till
    • Om det inte anges används standardinställningen för den aktuella prenumerationskontexten
    • Används för att hitta tilldelningen som ska uppdateras, inte för att ändra tilldelningen

  • Lås (valfritt)

    • Definierar den skissresurslåsning som ska användas för distribuerade resurser
    • Alternativ som stöds: None, AllResourcesReadOnly, AllResourcesDoNotDelete

  • SystemAssignedIdentity (valfritt)

    • Välj att skapa en systemtilldelad hanterad identitet för tilldelningen och distribuera resurserna
    • Standard för parameteruppsättningen "identitet"
    • Det går inte att använda med UserAssignedIdentity

  • UserAssignedIdentity (valfritt)

    • Anger den användartilldelade hanterade identiteten som ska användas för tilldelningen och för att distribuera resurserna
    • Del av parameteruppsättningen "identitet"
    • Det går inte att använda med SystemAssignedIdentity

  • Parameter (valfritt)

    • En hash-tabell med nyckel/värde-par för att ange dynamiska parametrar för skisstilldelningen

    • Standardvärdet för en dynamisk parameter är defaultValue i definitionen

    • Om en parameter inte anges och inte har något defaultValue är parametern inte valfri

      Anteckning

      Parametern stöder inte secureStrings.

  • ResourceGroupParameter (valfritt)

    • En hash-tabell med resursgruppsartefakter
    • Varje platshållare för resursgruppsartefakter har nyckel/värde-par för dynamisk inställning av namn och plats för resursgruppens artefakt
    • Om en resursgruppsparameter inte anges och inte har någon defaultValue är resursgruppsparametern inte valfri

I följande exempel uppdateras tilldelningen av version 1.1 av skissdefinitionen "my-blueprint" som hämtats med Get-AzBlueprint genom att ändra låsläget:

# 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

Exempelutdata för att skapa en skisstilldelning ser ut så här:

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

Ta bort skisstilldelningar

När det är dags att ta bort en skisstilldelning hanterar cmdleten den Remove-AzBlueprintAssignment här åtgärden. Cmdleten tar antingen Namn eller InputObject för att ange vilken skisstilldelning som ska tas bort. SubscriptionIdkrävs och måste anges i alla fall.

Följande exempel hämtar en befintlig skisstilldelning med Get-AzBlueprintAssignment och tar sedan bort den från den specifika prenumerationen som representeras som {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}'

Kodexempel

När du sammanför alla steg hämtar följande exempel skissdefinitionen, skapar, uppdaterar och tar bort en skisstilldelning i den specifika prenumerationen som representeras som {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

Nästa steg