Come gestire le assegnazioni con PowerShell

  • Articolo

Importante

Il 11 luglio 2026, Blueprints (anteprima) sarà deprecato. Eseguire la migrazione delle definizioni e delle assegnazioni di progetto esistenti a Specifiche modello e stack di distribuzione. Gli artefatti del progetto devono essere convertiti in modelli JSON arm o file Bicep usati per definire gli stack di distribuzione. Per informazioni su come creare un artefatto come risorsa arm, vedere:

Un'assegnazione di progetto può essere gestita usando il modulo Az.Blueprint Azure PowerShell. Il modulo supporta il recupero, la creazione, l'aggiornamento e la rimozione di assegnazioni. Il modulo può anche recuperare i dettagli sulle definizioni di progetto esistenti. Questo articolo illustra come installare il modulo e iniziare a usarlo.

Aggiungere il modulo Az.Blueprint

Per abilitare Azure PowerShell per gestire le assegnazioni di progetto, è necessario aggiungere il modulo. Questo modulo può essere usato con PowerShell installato in locale, con Azure Cloud Shell o con l'immagine Docker di Azure PowerShell.

Requisiti di base

Il modulo Azure Blueprints richiede il software seguente:

  • Azure PowerShell 1.5.0 o versione successiva. Se non è ancora installato, seguire queste istruzioni.
  • PowerShellGet 2.0.1 o versione successiva. Se non è installato o aggiornato, seguire queste istruzioni.

Installare il modulo

Il modulo Azure Blueprints per PowerShell è Az.Blueprint.

  1. Da un prompt di PowerShell amministrativo eseguire i comandi seguenti:

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

    Nota

    Se Az.Accounts è già installato, potrebbe essere necessario usare -AllowClobber per forzare l'installazione.

  2. Verificare che il modulo sia stato importato ed è la versione corretta (0.2.6):

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

Ottenere le definizioni di progetto

Il primo passaggio da usare con un'assegnazione è spesso ottenere un riferimento a una definizione di progetto. Il Get-AzBlueprint cmdlet ottiene una o più definizioni di progetto. Il cmdlet può ottenere definizioni di progetto da un gruppo di gestione con o una sottoscrizione con -ManagementGroupId {mgId}-SubscriptionId {subId}. Il parametro Name ottiene una definizione del progetto, ma deve essere usato con ManagementGroupId o SubscriptionId. La versione può essere usata con Name per essere più esplicita sulla definizione del progetto restituita. Invece della versione, il commutatore -LatestPublished afferra la versione pubblicata più di recente.

Nell'esempio seguente viene usato Get-AzBlueprint per ottenere tutte le versioni di una definizione di progetto denominata '101-blueprints-definition-subscription' da una sottoscrizione specifica rappresentata come {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

L'output di esempio per una definizione di progetto con più versioni è simile al seguente:

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

I parametri del progetto nella definizione del progetto possono essere espansi per fornire altre informazioni.

$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

Ottenere assegnazioni di progetto

Se l'assegnazione del progetto esiste già, è possibile ottenere un riferimento al progetto con il Get-AzBlueprintAssignment cmdlet. Il cmdlet accetta SubscriptionId e Name come parametri facoltativi. Se SubscriptionId non viene specificato, viene usato il contesto della sottoscrizione corrente.

L'esempio seguente usa Get-AzBlueprintAssignment per ottenere un'assegnazione di progetto singola denominata 'Assignment-lock-resource-groups' da una sottoscrizione specifica rappresentata come {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

L'output di esempio per un'assegnazione di progetto è simile al seguente:

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

Creare assegnazioni di progetto

Se l'assegnazione del progetto non esiste ancora, è possibile crearla con il New-AzBlueprintAssignment cmdlet. Questo cmdlet usa i parametri seguenti:

  • Nome [obbligatorio]

    • Specifica il nome dell'assegnazione del progetto
    • Deve essere univoco e non esiste già in SubscriptionId

  • Progetto [obbligatorio]

    • Specifica la definizione del progetto da assegnare
    • Usare Get-AzBlueprint per ottenere l'oggetto reference

  • Posizione [obbligatorio]

    • Specifica l'area per l'oggetto di distribuzione gestito e identità gestita assegnata dal sistema da creare in

  • Sottoscrizione (facoltativa)

    • Specifica la sottoscrizione in cui viene distribuita l'assegnazione
    • Se non specificato, l'impostazione predefinita è il contesto di sottoscrizione corrente

  • Blocco (facoltativo)

    • Definisce il blocco delle risorse del progetto da usare per le risorse distribuite
    • Opzioni supportate: Nessuna, AllResourcesReadOnly, AllResourcesDoNotDelete
    • Se non specificato, l'impostazione predefinita è Nessuna

  • SystemAssignedIdentity (facoltativo)

    • Selezionare per creare un'identità gestita assegnata dal sistema per l'assegnazione e distribuire le risorse
    • Impostazione predefinita per il set di parametri "identity"
    • Impossibile usare userAssignedIdentity

  • UserAssignedIdentity (facoltativo)

    • Specifica l'identità gestita assegnata dall'utente da usare per l'assegnazione e per distribuire le risorse
    • Parte del set di parametri "identity"
    • Impossibile usare SystemAssignedIdentity

  • Parametro (facoltativo)

    • Tabella hash di coppie chiave/valore per l'impostazione di parametri dinamici nell'assegnazione del progetto

    • Il valore predefinito per un parametro dinamico è il valore predefinitoValue nella definizione

    • Se un parametro non è specificato e non ha valore predefinitoValue, il parametro non è facoltativo

      Nota

      Il parametro non supporta secureStrings.

  • ResourceGroupParameter (facoltativo)

    • Tabella hash degli artefatti del gruppo di risorse
    • Ogni segnaposto dell'elemento del gruppo di risorse ha coppie chiave/valore per l'impostazione dinamica nome e posizione nell'artefatto del gruppo di risorse
    • Se un parametro del gruppo di risorse non è specificato e non ha valore predefinitoValue, il parametro del gruppo di risorse non è facoltativo

  • AssignmentFile (facoltativo)

    • Percorso di una rappresentazione di file JSON di un'assegnazione di progetto
    • Questo parametro fa parte di un set di parametri di PowerShell che include solo Name, Blueprint e SubscriptionId, oltre ai parametri comuni.

Esempio 1: Fornire parametri

Nell'esempio seguente viene creata una nuova assegnazione della versione '1.1' della definizione del progetto 'my-blueprint' recuperata con Get-AzBlueprint, imposta la posizione dell'oggetto identità e assegnazione gestita su 'westus2', blocca le risorse con AllResourcesReadOnly e imposta le tabelle hash per Parametri e ResourceGroupParameter in una sottoscrizione specifica rappresentata come {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

L'output di esempio per la creazione di un'assegnazione di progetto è simile al seguente:

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

Esempio 2: Usare un file di definizione di assegnazione JSON

Nell'esempio seguente viene creata quasi la stessa assegnazione dell'esempio 1. Anziché passare parametri al cmdlet, nell'esempio viene illustrato l'uso di un file di definizione di assegnazione JSON e del parametro AssignmentFile . Inoltre, la proprietà excludedPrincipals è configurata come parte dei blocchi. Non esiste un parametro di PowerShell per gli esclusiPrincipal e la proprietà può essere configurata solo impostandola tramite il file di definizione dell'assegnazione 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'

Per un esempio del file di definizione di assegnazione JSON per un'identità gestita assegnata dall'utente, vedere il corpo della richiesta in Esempio: Assegnazione con identità gestita assegnata dall'utente per l'API REST.

Aggiornare le assegnazioni di progetto

A volte è necessario aggiornare un'assegnazione di progetto già creata. Il Set-AzBlueprintAssignment cmdlet gestisce questa azione. Il cmdlet accetta la maggior parte degli stessi parametri che il New-AzBlueprintAssignment cmdlet esegue, consentendo l'aggiornamento di qualsiasi elemento impostato sull'assegnazione. Le eccezioni sono Nome, Progetto e SubscriptionId. Vengono aggiornati solo i valori specificati.

Per comprendere cosa accade quando si aggiorna un'assegnazione di progetto, vedere regole per l'aggiornamento delle assegnazioni.

  • Nome [obbligatorio]

    • Specifica il nome dell'assegnazione del progetto da aggiornare
    • Usato per individuare l'assegnazione da aggiornare, non modificare l'assegnazione

  • Progetto [obbligatorio]

    • Specifica la definizione del progetto dell'assegnazione del progetto
    • Usare Get-AzBlueprint per ottenere l'oggetto reference
    • Usato per individuare l'assegnazione da aggiornare, non modificare l'assegnazione

  • Posizione (facoltativo)

    • Specifica l'area per l'oggetto di distribuzione gestito e identità gestita assegnata dal sistema da creare in

  • Sottoscrizione (facoltativa)

    • Specifica la sottoscrizione in cui viene distribuita l'assegnazione
    • Se non specificato, l'impostazione predefinita è il contesto di sottoscrizione corrente
    • Usato per individuare l'assegnazione da aggiornare, non modificare l'assegnazione

  • Blocco (facoltativo)

  • SystemAssignedIdentity (facoltativo)

    • Selezionare per creare un'identità gestita assegnata dal sistema per l'assegnazione e distribuire le risorse
    • Impostazione predefinita per il set di parametri "identity"
    • Impossibile usare userAssignedIdentity

  • UserAssignedIdentity (facoltativo)

    • Specifica l'identità gestita assegnata dall'utente da usare per l'assegnazione e per distribuire le risorse
    • Parte del set di parametri "identity"
    • Impossibile usare SystemAssignedIdentity

  • Parametro (facoltativo)

    • Tabella hash di coppie chiave/valore per l'impostazione di parametri dinamici nell'assegnazione del progetto

    • Il valore predefinito per un parametro dinamico è il valore predefinitoValue nella definizione

    • Se un parametro non è specificato e non ha valore predefinitoValue, il parametro non è facoltativo

      Nota

      Il parametro non supporta secureStrings.

  • ResourceGroupParameter (facoltativo)

    • Tabella hash degli artefatti del gruppo di risorse
    • Ogni segnaposto dell'elemento del gruppo di risorse ha coppie chiave/valore per l'impostazione dinamica nome e posizione nell'artefatto del gruppo di risorse
    • Se un parametro del gruppo di risorse non è specificato e non ha valore predefinitoValue, il parametro del gruppo di risorse non è facoltativo

Nell'esempio seguente viene aggiornata l'assegnazione della versione '1.1' della definizione del progetto "my-blueprint" recuperata con Get-AzBlueprint modificando la modalità di blocco:

# 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

L'output di esempio per la creazione di un'assegnazione di progetto è simile al seguente:

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

Rimuovere le assegnazioni di progetto

Quando è necessario rimuovere un'assegnazione di progetto, il Remove-AzBlueprintAssignment cmdlet gestisce questa azione. Il cmdlet accetta Nome o InputObject per specificare l'assegnazione di progetto da rimuovere. SubscriptionId è obbligatorio e deve essere fornito in tutti i casi.

Nell'esempio seguente viene recuperata un'assegnazione di progetto esistente con Get-AzBlueprintAssignment e quindi la rimuove dalla sottoscrizione specifica rappresentata come {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}'

Esempio di codice

Insieme tutti i passaggi, l'esempio seguente ottiene la definizione del progetto, quindi crea, aggiorna e rimuove un'assegnazione di progetto nella sottoscrizione specifica rappresentata come {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

Passaggi successivi