Guida introduttiva: Definire e assegnare un progetto di Azure con PowerShell

Articolo
03/08/2024

Importante

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

In questa esercitazione viene descritto come usare Azure Blueprints per eseguire alcune della attività comuni di creazione, pubblicazione e assegnazione di un progetto all'interno dell'organizzazione. Questa competenza consente di definire modelli comuni per sviluppare configurazioni riutilizzabili e rapidamente distribuibili, basate su modelli, criteri e sicurezza di Azure Resource Manager (ARM).

Prerequisiti

Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.
Se il modulo Az.Blueprint non è già installato, seguire le istruzioni contenute in Aggiungere il modulo Az.Blueprint per installarlo e convalidarlo da PowerShell Gallery.
Se azure Blueprints non è stato usato in precedenza, registrare il provider di risorse tramite Azure PowerShell con Register-AzResourceProvider -ProviderNamespace Microsoft.Blueprint.

Azure Cloud Shell

Azure Cloud Shell è un ambiente di shell interattivo ospitato in Azure e usato tramite il browser. È possibile usare Bash o PowerShell con Cloud Shell per usare i servizi di Azure. È possibile usare i comandi preinstallati di Cloud Shell per eseguire il codice in questo articolo, senza dover installare alcun elemento nell'ambiente locale.

Per avviare Azure Cloud Shell:

Opzione	Esempio/Collegamento
Selezionare Prova nell'angolo superiore destro di un codice o di un blocco di comandi. Selezionando Prova non viene copiato automaticamente il codice o il comando in Cloud Shell.
Passare a https://shell.azure.com o selezionare il pulsante Avvia Cloud Shell per aprire Cloud Shell nel browser.
Selezionare il pulsante Cloud Shell nella barra dei menu nell'angolo in alto a destra del portale di Azure.

Per usare Azure Cloud Shell:

Avviare Cloud Shell.
Selezionare il pulsante Copia in un blocco di codice (o blocco di comandi) per copiare il codice o il comando.
Incollare il codice o il comando nella sessione di Cloud Shell selezionando CTRL+MAIUSC+V in Windows e Linux oppure selezionando CMD+MAIUSC+V in macOS.
Selezionare INVIO per eseguire il codice o il comando.

Creare un progetto

Il primo passaggio nella definizione di un modello standard per la conformità è la creazione di un progetto dalle risorse disponibili. Si creerà ora un progetto denominato MyBlueprint per configurare le assegnazioni di ruoli e criteri per la sottoscrizione. Aggiungere quindi un gruppo di risorse, un modello di Resource Manager e un'assegnazione di ruolo nel gruppo di risorse.

Nota

Quando si usa PowerShell, l'oggetto progetto viene creato per primo. Per ogni artefatto da aggiungere con parametri, definire i parametri in anticipo nel progetto iniziale.

Creare l'oggetto progetto iniziale. Il BlueprintFile parametro accetta un file JSON che include proprietà sul progetto, tutti i gruppi di risorse da creare e tutti i parametri a livello di progetto. I parametri vengono impostati durante l'assegnazione e vengono usati dagli artefatti aggiunti nei passaggi successivi.

File JSON - blueprint.json

{
    "properties": {
        "description": "This blueprint sets tag policy and role assignment on the subscription, creates a ResourceGroup, and deploys a resource template and role assignment to that ResourceGroup.",
        "targetScope": "subscription",
        "parameters": {
            "storageAccountType": {
                "type": "string",
                "defaultValue": "Standard_LRS",
                "allowedValues": [
                    "Standard_LRS",
                    "Standard_GRS",
                    "Standard_ZRS",
                    "Premium_LRS"
                ],
                "metadata": {
                    "displayName": "storage account type.",
                    "description": null
                }
            },
            "tagName": {
                "type": "string",
                "metadata": {
                    "displayName": "The name of the tag to provide the policy assignment.",
                    "description": null
                }
            },
            "tagValue": {
                "type": "string",
                "metadata": {
                    "displayName": "The value of the tag to provide the policy assignment.",
                    "description": null
                }
            },
            "contributors": {
                "type": "array",
                "metadata": {
                    "description": "List of AAD object IDs that is assigned Contributor role at the subscription",
                    "strongType": "PrincipalId"
                }
            },
            "owners": {
                "type": "array",
                "metadata": {
                    "description": "List of AAD object IDs that is assigned Owner role at the resource group",
                    "strongType": "PrincipalId"
                }
            }
        },
        "resourceGroups": {
            "storageRG": {
                "description": "Contains the resource template deployment and a role assignment."
            }
        }
    }
}

Comando di PowerShell
```
# Login first with Connect-AzAccount if not using Cloud Shell

# Get a reference to the new blueprint object, we'll use it in subsequent steps
$blueprint = New-AzBlueprint -Name 'MyBlueprint' -BlueprintFile .\blueprint.json
```
Nota

Usare il nome file blueprint.json quando si creano definizioni di progetto a livello di codice. Questo nome file viene usato quando si chiama Import-AzBlueprintWithArtifact.

Per impostazione predefinita, l'oggetto progetto viene creato nella sottoscrizione predefinita. Per specificare il gruppo di gestione, usare il parametro ManagementGroupId. Per specificare la sottoscrizione, usare il parametro SubscriptionId.

Aggiungere un'assegnazione di ruolo nella sottoscrizione. ArtifactFile definisce il tipo di artefatto, le proprietà sono allineate all'identificatore di definizione del ruolo e le identità dell'entità vengono passate come matrice di valori. Nell'esempio seguente, le identità dell'entità a cui è stato concesso il ruolo specificato vengono configurate in un parametro impostato durante l'assegnazione del progetto. In questo esempio viene usato il Contributor ruolo predefinito, con un GUID di b24988ac-6180-42a0-ab88-20f7382dd24c.
- File JSON - \artifacts\roleContributor.json
```
{
    "kind": "roleAssignment",
    "properties": {
        "roleDefinitionId": "/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c",
        "principalIds": "[parameters('contributors')]"
    }
}
```
- Comando di PowerShell
```
# Use the reference to the new blueprint object from the previous steps
New-AzBlueprintArtifact -Blueprint $blueprint -Name 'roleContributor' -ArtifactFile .\artifacts\roleContributor.json
```

Aggiungere un'assegnazione di criteri nella sottoscrizione. ArtifactFile definisce il tipo di artefatto, le proprietà sono allineate a una definizione di criteri o iniziative e l'assegnazione dei criteri è configurata per l'uso dei parametri di progetto definiti durante l'assegnazione del progetto. In questo esempio vengono usati i Apply tag and its default value to resource groups criteri predefiniti, con un GUID di 49c88fc8-6fd1-46fd-a676-f12d1d3a4c71.

File JSON - \artifacts\policyTags.json

{
    "kind": "policyAssignment",
    "properties": {
        "displayName": "Apply tag and its default value to resource groups",
        "description": "Apply tag and its default value to resource groups",
        "policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/49c88fc8-6fd1-46fd-a676-f12d1d3a4c71",
        "parameters": {
            "tagName": {
                "value": "[parameters('tagName')]"
            },
            "tagValue": {
                "value": "[parameters('tagValue')]"
            }
        }
    }
}

Comando di PowerShell

# Use the reference to the new blueprint object from the previous steps
New-AzBlueprintArtifact -Blueprint $blueprint -Name 'policyTags' -ArtifactFile .\artifacts\policyTags.json

Aggiungere un'altra assegnazione di criteri per il tag di archiviazione (riutilizzando storageAccountType_ parameter) nella sottoscrizione. Questo elemento di assegnazione di criteri aggiuntivo indica che un parametro definito nel progetto può essere usato da più di un elemento. Nell'esempio si usa per storageAccountType impostare un tag nel gruppo di risorse. Questo valore fornisce informazioni sull'account di archiviazione creato nel passaggio successivo. In questo esempio vengono usati i Apply tag and its default value to resource groups criteri predefiniti, con un GUID di 49c88fc8-6fd1-46fd-a676-f12d1d3a4c71.

File JSON - \artifacts\policy Archiviazione Tags.json

{
    "kind": "policyAssignment",
    "properties": {
        "displayName": "Apply storage tag to resource group",
        "description": "Apply storage tag and the parameter also used by the template to resource groups",
        "policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/49c88fc8-6fd1-46fd-a676-f12d1d3a4c71",
        "parameters": {
            "tagName": {
                "value": "StorageType"
            },
            "tagValue": {
                "value": "[parameters('storageAccountType')]"
            }
        }
    }
}

Comando di PowerShell

# Use the reference to the new blueprint object from the previous steps
New-AzBlueprintArtifact -Blueprint $blueprint -Name 'policyStorageTags' -ArtifactFile .\artifacts\policyStorageTags.json

Aggiungere un modello nel gruppo di risorse. Per TemplateFile un modello di Resource Manager è incluso il normale componente JSON del modello. Il modello riutilizza anche i storageAccountTypeparametri del progetto , tagNamee tagValue passando ognuno al modello. I parametri del progetto sono disponibili per il modello usando il parametro TemplateParameterFilee all'interno del modello JSON che viene usata la coppia chiave-valore per inserire il valore. I nomi dei parametri del progetto e del modello potrebbero essere uguali.

File di modello DI Resource Manager JSON - \artifacts\template Archiviazione.json

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "storageAccountTypeFromBP": {
            "type": "string",
            "metadata": {
                "description": "Storage Account type"
            }
        },
        "tagNameFromBP": {
            "type": "string",
            "defaultValue": "NotSet",
            "metadata": {
                "description": "Tag name from blueprint"
            }
        },
        "tagValueFromBP": {
            "type": "string",
            "defaultValue": "NotSet",
            "metadata": {
                "description": "Tag value from blueprint"
            }
        }
    },
    "variables": {
        "storageAccountName": "[concat(uniquestring(resourceGroup().id), 'standardsa')]"
    },
    "resources": [{
        "type": "Microsoft.Storage/storageAccounts",
        "name": "[variables('storageAccountName')]",
        "apiVersion": "2016-01-01",
        "tags": {
            "[parameters('tagNameFromBP')]": "[parameters('tagValueFromBP')]"
        },
        "location": "[resourceGroup().location]",
        "sku": {
            "name": "[parameters('storageAccountTypeFromBP')]"
        },
        "kind": "Storage",
        "properties": {}
    }],
    "outputs": {
        "storageAccountSku": {
            "type": "string",
            "value": "[variables('storageAccountName')]"
        }
    }
}

File di parametri del modello DI Resource Manager JSON - \artifacts\template Archiviazione Params.json

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "storageAccountTypeFromBP": {
            "value": "[parameters('storageAccountType')]"
        },
        "tagNameFromBP": {
            "value": "[parameters('tagName')]"
        },
        "tagValueFromBP": {
            "value": "[parameters('tagValue')]"
        }
    }
}

Comando di PowerShell

# Use the reference to the new blueprint object from the previous steps
New-AzBlueprintArtifact -Blueprint $blueprint -Type TemplateArtifact -Name 'templateStorage' -TemplateFile .\artifacts\templateStorage.json -TemplateParameterFile .\artifacts\templateStorageParams.json -ResourceGroupName storageRG

Aggiungere un'assegnazione di ruolo nel gruppo di risorse. Analogamente alla voce di assegnazione di ruolo precedente, nell'esempio seguente viene usato l'identificatore di definizione per il Owner ruolo e viene fornito un parametro diverso dal progetto. In questo esempio viene usato il Owner ruolo predefinito, con un GUID di 8e3af657-a8ff-443c-a75c-2fe8c4bcb635.

File JSON - \artifacts\roleOwner.json

{
    "kind": "roleAssignment",
    "properties": {
        "resourceGroup": "storageRG",
        "roleDefinitionId": "/providers/Microsoft.Authorization/roleDefinitions/8e3af657-a8ff-443c-a75c-2fe8c4bcb635",
        "principalIds": "[parameters('owners')]"
    }
}

Comando di PowerShell

# Use the reference to the new blueprint object from the previous steps
New-AzBlueprintArtifact -Blueprint $blueprint -Name 'roleOwner' -ArtifactFile .\artifacts\roleOwner.json

Pubblicare un progetto

Dopo aver aggiunto gli artefatti al progetto, è possibile pubblicarlo. La pubblicazione rende il progetto disponibile per l'assegnazione a una sottoscrizione.

# Use the reference to the new blueprint object from the previous steps
Publish-AzBlueprint -Blueprint $blueprint -Version '{BlueprintVersion}'

Il valore per {BlueprintVersion} è una stringa di lettere, numeri e trattini (senza spazi o altri caratteri speciali). La lunghezza massima è 20 caratteri. Usare un elemento univoco e informativo, ad esempio v20180622-135541.

Assegnare un progetto

Dopo aver pubblicato un progetto usando PowerShell, è assegnabile a una sottoscrizione. Assegnare il progetto creato a una delle sottoscrizioni nella gerarchia dei gruppi di gestione. Se il progetto viene salvato in una sottoscrizione, può essere assegnato solo a tale sottoscrizione. Il Blueprint parametro specifica il progetto da assegnare. Per fornire i nameparametri , identitylocation, lock, e blueprint , usare i parametri di PowerShell corrispondenti nel New-AzBlueprintAssignment cmdlet o specificarli nel file JSON dei AssignmentFile parametri.

Eseguire la distribuzione del progetto assegnandolo a una sottoscrizione. Poiché i contributors parametri e owners richiedono una matrice di objectIds entità a cui concedere l'assegnazione di ruolo, usare l'API Graph di Azure Active Directory per raccogliere l'oggetto per l'uso objectIds in AssignmentFile per utenti, gruppi o entità servizio personalizzati.

File JSON - blueprintAssignment.json

{
    "properties": {
        "blueprintId": "/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint",
        "resourceGroups": {
            "storageRG": {
                "name": "StorageAccount",
                "location": "eastus2"
            }
        },
        "parameters": {
            "storageAccountType": {
                "value": "Standard_GRS"
            },
            "tagName": {
                "value": "CostCenter"
            },
            "tagValue": {
                "value": "ContosoIT"
            },
            "contributors": {
                "value": [
                    "7be2f100-3af5-4c15-bcb7-27ee43784a1f",
                    "38833b56-194d-420b-90ce-cff578296714"
                ]
            },
            "owners": {
                "value": [
                    "44254d2b-a0c7-405f-959c-f829ee31c2e7",
                    "316deb5f-7187-4512-9dd4-21e7798b0ef9"
                ]
            }
        }
    },
    "identity": {
        "type": "systemAssigned"
    },
    "location": "westus"
}

Comando di PowerShell

# Use the reference to the new blueprint object from the previous steps
New-AzBlueprintAssignment -Blueprint $blueprint -Name 'assignMyBlueprint' -AssignmentFile .\blueprintAssignment.json

Identità gestita assegnata dall'utente

L'assegnazione di un progetto può anche usare un'identità gestita assegnata dall'utente. In questo caso, la identity parte del file di assegnazione JSON cambia come indicato di seguito. Sostituire {tenantId}, {subscriptionId}, {yourRG}e {userIdentity} con l'ID tenant, l'ID sottoscrizione, il nome del gruppo di risorse e il nome rispettivamente dell'identità gestita assegnata dall'utente.
```
"identity": {
    "type": "userAssigned",
    "tenantId": "{tenantId}",
    "userAssignedIdentities": {
        "/subscriptions/{subscriptionId}/resourceGroups/{yourRG}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{userIdentity}": {}
    }
},
```
L'identità gestita assegnata dall'utente può trovarsi in qualsiasi sottoscrizione e gruppo di risorse a cui l'utente che assegna il progetto dispone delle autorizzazioni.

Importante

Azure Blueprints non gestisce l'identità gestita assegnata dall'utente. Gli utenti sono responsabili dell'assegnazione di ruoli e autorizzazioni sufficienti oppure l'assegnazione del progetto avrà esito negativo.

Pulire le risorse

È possibile rimuovere un progetto da una sottoscrizione. La rimozione viene spesso eseguita quando le risorse dell'elemento non sono più necessarie. Quando un progetto viene rimosso, gli elementi assegnati nell'ambito del progetto vengono mantenuti. Per rimuovere l'assegnazione di un progetto, usare il cmdlet Remove-AzBlueprintAssignment:

assignMyBlueprint

Remove-AzBlueprintAssignment -Name 'assignMyBlueprint'

Passaggi successivi

In questa guida introduttiva è stato creato, assegnato e rimosso un progetto con PowerShell. Per altre informazioni su Azure Blueprints, passare all'articolo relativo al ciclo di vita di un progetto.

Informazioni sul ciclo di vita di un progetto

Guida introduttiva: Definire e assegnare un progetto di Azure con PowerShell

Prerequisiti

Azure Cloud Shell

Creare un progetto

Pubblicare un progetto

Assegnare un progetto

Pulire le risorse

Passaggi successivi

Risorse aggiuntive