Avvio rapido: Definire e assegnare un progetto di Azure con l'API REST

Articolo
09/07/2023

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:

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, in base ai modelli, ai criteri e alla sicurezza di Azure Resource Manager (ARM).

Prerequisiti

Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.
Registrare il provider di risorse Microsoft.Blueprint. Per istruzioni, vedere Provider e tipi di risorse.

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 Cloud Shell preinstallati 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 in alto a destra di un codice o di un blocco di comandi. Selezionando Prova non copia 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.

Introduzione ad API REST

Se non si ha familiarità con l'API REST, iniziare esaminando il riferimento all'API REST di Azure, in particolare le sezioni relative all'URI della richiesta e al corpo della richiesta. Questa guida introduttiva usa questi concetti per fornire indicazioni per l'uso di Azure Blueprints e presuppone una conoscenza funzionante di tali concetti. Gli strumenti come ARMClient possono gestire automaticamente l'autorizzazione e sono consigliati per principianti.

Per le specifiche di Azure Blueprints, vedere API REST di Azure Blueprints.

API REST e PowerShell

Se non si ha già uno strumento per effettuare chiamate API REST, provare a usare PowerShell per queste istruzioni. Di seguito è riportata un'intestazione di esempio per l'autenticazione con Azure. Generare un'intestazione di autenticazione, a volte denominata token di connessione e fornire l'URI dell'API REST per connettersi a qualsiasi parametro o a Request Body:

# Log in first with Connect-AzAccount if not using Cloud Shell

$azContext = Get-AzContext
$azProfile = [Microsoft.Azure.Commands.Common.Authentication.Abstractions.AzureRmProfileProvider]::Instance.Profile
$profileClient = New-Object -TypeName Microsoft.Azure.Commands.ResourceManager.Common.RMProfileClient -ArgumentList ($azProfile)
$token = $profileClient.AcquireAccessToken($azContext.Subscription.TenantId)
$authHeader = @{
    'Content-Type'='application/json'
    'Authorization'='Bearer ' + $token.AccessToken
}

# Invoke the REST API
$restUri = 'https://management.azure.com/subscriptions/{subscriptionId}?api-version=2020-01-01'
$response = Invoke-RestMethod -Uri $restUri -Method Get -Headers $authHeader

Sostituire {subscriptionId} nella variabile precedente $restUri per ottenere informazioni sulla sottoscrizione. La $response variabile contiene il risultato del Invoke-RestMethod cmdlet, che è possibile analizzare con cmdlet, ad esempio ConvertFrom-Json. Se l'endpoint del servizio API REST prevede un Request Bodyoggetto , specificare una variabile formattata JSON al -Body parametro di Invoke-RestMethod.

Creare un progetto

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

Nota

Quando si usa l'API REST, viene creato prima l'oggetto progetto . Per aggiungere ogni artefatto con parametri, definire i parametri in anticipo nel progetto iniziale.

In ogni URI dell'API REST sostituire le variabili seguenti con i propri valori:

{YourMG} - Sostituire con l'ID del gruppo di gestione.
{subscriptionId} - Sostituire con l'ID sottoscrizione.

Nota

È anche possibile creare progetti a livello di sottoscrizione. Per altre informazioni, vedere Creare un progetto nell'esempio di sottoscrizione.

Creare l'oggetto progetto iniziale. Include Request Body proprietà relative al progetto, a qualsiasi gruppo di risorse da creare e a tutti i parametri a livello di progetto. I parametri vengono impostati durante l'assegnazione e vengono usati dagli artefatti aggiunti in passaggi successivi.

URI DELL'API REST

PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint?api-version=2018-11-01-preview

Request Body

{
    "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",
                "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"
                }
            },
            "owners": {
                "type": "array",
                "metadata": {
                    "description": "List of AAD object IDs that is assigned Owner role at the resource group"
                }
            }
        },
        "resourceGroups": {
            "storageRG": {
                "description": "Contains the resource template deployment and a role assignment."
            }
        }
    }
}

Aggiungere un'assegnazione di ruolo nella sottoscrizione. Definisce Request Body il tipo di artefatto, le proprietà si allineano all'identificatore di definizione del ruolo e le identità dell'entità vengono passate come matrice di valori. Nell'esempio seguente le identità dell'entità concesse al ruolo specificato sono 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.
- URI DELL'API REST
```
PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint/artifacts/roleContributor?api-version=2018-11-01-preview
```
- Request Body
```
{
    "kind": "roleAssignment",
    "properties": {
        "roleDefinitionId": "/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c",
        "principalIds": "[parameters('contributors')]"
    }
}
```

Aggiungere un'assegnazione di criteri nella sottoscrizione. Definisce Request Body il tipo di artefatto, le proprietà si allineano a una definizione di criteri o di iniziativa e l'assegnazione dei criteri è configurata per usare i parametri del progetto definiti durante l'assegnazione del progetto. In questo esempio viene usato il Apply tag and its default value to resource groups criterio predefinito, con un GUID di 49c88fc8-6fd1-46fd-a676-f12d1d3a4c71.

URI DELL'API REST

PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint/artifacts/policyTags?api-version=2018-11-01-preview

Request Body

{
    "kind": "policyAssignment",
    "properties": {
        "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')]"
            }
        }
    }
}

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 viene usato storageAccountType per impostare un tag nel gruppo di risorse. Questo valore fornisce informazioni sull'account di archiviazione creato nel passaggio successivo. In questo esempio viene usato il Apply tag and its default value to resource groups criterio predefinito, con un GUID di 49c88fc8-6fd1-46fd-a676-f12d1d3a4c71.

URI DELL'API REST

PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint/artifacts/policyStorageTags?api-version=2018-11-01-preview

Request Body

{
    "kind": "policyAssignment",
    "properties": {
        "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')]"
            }
        }
    }
}

Aggiungere un modello nel gruppo di risorse. Per Request Body un modello di Resource Manager è incluso il normale componente JSON del modello e definisce il gruppo di risorse di destinazione con properties.resourceGroup. Il modello riutilizza anche i storageAccountTypeparametri , tagNamee tagValue del progetto passando ognuno al modello. I parametri del progetto sono disponibili per il modello definendo properties.parameterse 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 possono essere uguali, ma sono diversi qui per illustrare il modo in cui ogni progetto passa dal progetto all'artefatto del modello.

URI DELL'API REST

PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint/artifacts/templateStorage?api-version=2018-11-01-preview

Request Body

{
    "kind": "template",
    "properties": {
        "template": {
            "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
            "contentVersion": "1.0.0.0",
            "parameters": {
                "storageAccountTypeFromBP": {
                    "type": "string",
                    "defaultValue": "Standard_LRS",
                    "allowedValues": [
                        "Standard_LRS",
                        "Standard_GRS",
                        "Standard_ZRS",
                        "Premium_LRS"
                    ],
                    "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": "[resourceGroups('storageRG').location]",
                "sku": {
                    "name": "[parameters('storageAccountTypeFromBP')]"
                },
                "kind": "Storage",
                "properties": {}
            }],
            "outputs": {
                "storageAccountSku": {
                    "type": "string",
                    "value": "[variables('storageAccountName')]"
                }
            }
        },
        "resourceGroup": "storageRG",
        "parameters": {
            "storageAccountTypeFromBP": {
                "value": "[parameters('storageAccountType')]"
            },
            "tagNameFromBP": {
                "value": "[parameters('tagName')]"
            },
            "tagValueFromBP": {
                "value": "[parameters('tagValue')]"
            }
        }
    }
}

Aggiungere un'assegnazione di ruolo nel gruppo di risorse. Analogamente alla voce precedente dell'assegnazione di ruolo, 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.

URI DELL'API REST

PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint/artifacts/roleOwner?api-version=2018-11-01-preview

Request Body

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

Pubblicare un progetto

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

URI DELL'API REST

PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint/versions/{BlueprintVersion}?api-version=2018-11-01-preview

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

Assegnare un progetto

Dopo aver pubblicato un progetto usando l'API REST, è 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. Request Body Specifica il progetto da assegnare e fornisce il nome e la posizione a tutti i gruppi di risorse nella definizione del progetto. Request Body fornisce anche tutti i parametri definiti nel progetto e usati da uno o più artefatti associati.

In ogni URI dell'API REST sostituire le variabili seguenti con valori personalizzati:

{tenantId} - Sostituire con l'ID tenant.
{YourMG} - Sostituire con l'ID del gruppo di gestione.
{subscriptionId} - Sostituire con l'ID sottoscrizione.

Specificare l'entità servizio Azure Blueprints il Owner ruolo nella sottoscrizione di destinazione. AppId è statico (f71766dc-90d9-4b7d-bd9d-4499c4331c3f), ma l'ID dell'entità servizio varia in base al tenant. Usare l'API REST seguente per richiedere i dettagli per il tenant. Viene usata l'API Graph di Azure Active Directory, che ha autorizzazioni diverse.
- URI DELL'API REST
```
GET https://graph.windows.net/{tenantId}/servicePrincipals?api-version=1.6&$filter=appId eq 'f71766dc-90d9-4b7d-bd9d-4499c4331c3f'
```

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 Azure Active Directory API Graph per raccogliere l'oggetto objectIds da usare in Request Body per utenti, gruppi o entità servizio personali.

URI DELL'API REST

PUT https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Blueprint/blueprintAssignments/assignMyBlueprint?api-version=2018-11-01-preview

Request Body

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

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 corpo della richiesta viene modificata nel modo seguente. Sostituire {yourRG} e {userIdentity} rispettivamente con il nome del gruppo di risorse e il nome 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

Annullare l'assegnazione di un progetto

È 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 un'assegnazione del progetto, usare l'operazione API REST seguente:

URI DELL'API REST

DELETE https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Blueprint/blueprintAssignments/assignMyBlueprint?api-version=2018-11-01-preview

Eliminare un progetto

Per rimuovere il progetto stesso, usare l'operazione API REST seguente:

URI DELL'API REST

DELETE https://management.azure.com/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint?api-version=2018-11-01-preview

Passaggi successivi

In questa guida introduttiva è stato creato, assegnato e rimosso un progetto con l'API REST. 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

Avvio rapido: Definire e assegnare un progetto di Azure con l'API REST

Prerequisiti

Azure Cloud Shell

Introduzione ad API REST

API REST e PowerShell

Creare un progetto

Pubblicare un progetto

Assegnare un progetto

Pulire le risorse

Annullare l'assegnazione di un progetto

Eliminare un progetto

Passaggi successivi

Risorse aggiuntive

Risorse aggiuntive