Démarrage rapide : Définir et affecter un blueprint Azure avec l’API REST

Article
09/07/2023

Important

Le 11 juillet 2026, Blueprints (préversion) sera devenu obsolète. Migrez vos définitions et affectations Blueprint existantes vers les Spécifications de modèleet lesPiles de déploiement. Les artefacts de Blueprint doivent être convertis en modèles ARM JSON ou en fichiers Bicep utilisés pour définir des piles de déploiement. Pour savoir comment créer un artefact en tant que ressource ARM, consultez :

Dans ce tutoriel, vous allez découvrir comment utiliser Azure Blueprints pour effectuer des tâches courantes liées à la création, à la publication et à l’affectation d’un blueprint dans votre organisation. Cette compétence vous permet de définir des modèles courants pour développer des configurations réutilisables et déployables rapidement, en fonction des modèles, de la stratégie et de la sécurité d’Azure Resource Manager (ARM).

Prérequis

Si vous n’avez pas d’abonnement Azure, créez un compte gratuit avant de commencer.
Inscrivez le fournisseur de ressources Microsoft.Blueprint. Pour obtenir des instructions, consultez Types et fournisseurs de ressources.

Azure Cloud Shell

Azure héberge Azure Cloud Shell, un environnement d’interpréteur de commandes interactif que vous pouvez utiliser dans votre navigateur. Vous pouvez utiliser Bash ou PowerShell avec Cloud Shell pour utiliser les services Azure. Vous pouvez utiliser les commandes préinstallées Cloud Shell pour exécuter le code de cet article sans avoir à installer quoi que ce soit dans votre environnement local.

Pour démarrer Azure Cloud Shell :

Option	Exemple/Lien
Sélectionnez Essayer dans le coin supérieur droite d’un bloc de codes ou de commandes. La sélection de Essayer ne copie pas automatiquement le code ni la commande dans Cloud Shell.
Accédez à https://shell.azure.com ou sélectionnez le bouton Lancer Cloud Shell pour ouvrir Cloud Shell dans votre navigateur.
Sélectionnez le bouton Cloud Shell dans la barre de menus en haut à droite du portail Azure.

Pour utiliser Azure Cloud Shell :

Démarrez Cloud Shell.
Sélectionnez le bouton Copier sur un bloc de codes (ou un bloc de commandes) pour copier le code ou la commande.
Collez le code ou la commande dans la session Cloud Shell en sélectionnant Ctrl+Maj+V sur Windows et Linux ou en sélectionnant Cmd+Maj+V sur macOS.
Sélectionnez Entrée pour exécuter le code ou la commande.

Prise en main de l’API REST

Si vous n’êtes pas familiarisé avec l’API REST, commencez par examiner les Informations de référence sur l’API REST Azure, en particulier les sections sur l’URI de la requête et sur le corps de la requête. Ce guide de démarrage rapide utilise ces concepts pour fournir des instructions sur l’utilisation d’Azure Blueprints et suppose une connaissance pratique de ces derniers. Des outils comme ARMClient peuvent gérer les autorisations automatiquement et sont recommandés pour les débutants.

Pour les caractéristiques Azure Blueprints, consultez API REST Azure Blueprints.

API REST et PowerShell

Si vous n’avez pas encore d’outil pour effectuer des appels d’API REST, songez à utiliser PowerShell pour ces instructions. Voici un exemple d’en-tête pour l’authentification auprès d’Azure. Générez un en-tête d’authentification, parfois appelé jeton du porteur, puis spécifiez l’URI d’API REST auquel se connecter avec un paramètre ou un 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

Remplacez {subscriptionId} dans la variable $restUri précédente pour obtenir des informations sur votre abonnement. La variable $response contient le résultat de la cmdlet Invoke-RestMethod que vous pouvez analyser avec des cmdlets comme ConvertFrom-Json. Si le point de terminaison de service de l’API REST attend un Request Body, fournissez une variable au format JSON au paramètre -Body de Invoke-RestMethod.

Créer un blueprint

La première étape de la définition d’un modèle standard à des fins de conformité est de composer un blueprint à partir des ressources disponibles. Vous allez créer un blueprint nommé MyBlueprint pour configurer les attributions de rôles et de stratégies de l’abonnement. Ensuite, vous ajoutez un groupe de ressources, un modèle ARM et une attribution de rôle sur le groupe de ressources.

Notes

Quand vous utilisez l’API REST, l’objet blueprint est créé en premier. Pour chaque artefact à ajouter qui a des paramètres, vous définissez ces paramètres à l’avance sur le blueprint initial.

Dans chaque URI de l’API REST, remplacez les variables suivantes par vos propres valeurs :

{YourMG} - Remplacez par l’ID de votre groupe d’administration.
{subscriptionId} - Remplacez par votre ID d’abonnement.

Notes

Vous pouvez aussi créer des blueprints au niveau de l’abonnement. Pour plus d’informations, consultez Exemple de création de blueprint au niveau de l’abonnement.

Créez l’objet blueprint initial. Le Request Body inclut des propriétés du blueprint, les groupes de ressources à créer et tous les paramètres au niveau du blueprint. Vous définissez les paramètres lors de l’attribution, et ils sont utilisés par les artefacts que vous ajoutez dans les étapes ultérieures.

URI de l’API REST

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

Corps de la requête

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

Ajoutez une attribution de rôle à l’abonnement. Request Body définit le genre d’artefact, les propriétés varient en fonction de l’identificateur de définition de rôle et les identités de principal sont passées sous forme de tableau de valeurs. Dans l’exemple suivant, les identités de principal ayant reçu le rôle spécifié sont configurées avec un paramètre qui est défini durant l’affectation du blueprint. Cet exemple utilise le rôle intégré Contributor avec le GUID b24988ac-6180-42a0-ab88-20f7382dd24c.
- URI de l’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
```
- Corps de la requête
```
{
    "kind": "roleAssignment",
    "properties": {
        "roleDefinitionId": "/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c",
        "principalIds": "[parameters('contributors')]"
    }
}
```

Ajoutez une attribution de stratégie à l’abonnement. Request Body définit le genre d’artefact, les propriétés qui varient en fonction de la définition d’une stratégie ou d’une initiative, et configure l’affectation de stratégie pour utiliser les paramètres de blueprint définis (à configurer durant l’affectation du blueprint). Cet exemple utilise la stratégie intégrée Apply tag and its default value to resource groups avec le GUID 49c88fc8-6fd1-46fd-a676-f12d1d3a4c71.

URI de l’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

Corps de la requête

{
    "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')]"
            }
        }
    }
}

Ajoutez une autre affectation de stratégie pour l’étiquette de stockage (en réutilisant storageAccountType_ parameter) au niveau de l’abonnement. Cet artefact d’affectation de stratégie supplémentaire montre qu’un paramètre défini sur le blueprint peut être utilisé par plusieurs artefacts. Dans l’exemple, vous utilisez storageAccountType pour définir une étiquette sur le groupe de ressources. Cette valeur fournit des informations sur le compte de stockage que vous créez à l’étape suivante. Cet exemple utilise la stratégie intégrée Apply tag and its default value to resource groups avec le GUID 49c88fc8-6fd1-46fd-a676-f12d1d3a4c71.

URI de l’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

Corps de la requête

{
    "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')]"
            }
        }
    }
}

Ajoutez un modèle sous le groupe de ressources. Le Request Body pour un modèle ARM inclut le composant JSON normal du modèle et définit le groupe de ressources cible avec properties.resourceGroup. Le modèle réutilise également les paramètres de blueprint storageAccountType, tagName et tagValue en passant chacun au modèle. Les paramètres de blueprint sont accessibles au modèle en définissant properties.parameters, et dans le modèle JSON, cette paire clé/valeur est utilisée pour injecter la valeur. Les noms des paramètres du blueprint et du modèle peuvent être identiques, mais ils sont différents ici pour illustrer la façon dont chacun passe du blueprint à l’artefact du modèle.

URI de l’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

Corps de la requête

{
    "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')]"
            }
        }
    }
}

Ajoutez une attribution de rôle sous le groupe de ressources. Comme pour l’entrée d’attribution de rôle précédente, l’exemple suivant utilise l’identificateur de définition pour le rôle Owner et lui fournit un paramètre différent à partir du blueprint. Cet exemple utilise le rôle intégré Owner avec le GUID 8e3af657-a8ff-443c-a75c-2fe8c4bcb635.

URI de l’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

Corps de la requête

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

Publier un blueprint

Maintenant que vous avez ajouté les artefacts au blueprint, il est temps de le publier. Une fois publié, un blueprint peut être affecté à un abonnement.

URI de l’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

La valeur de {BlueprintVersion} est une chaîne de lettres, de chiffres et de traits d’union (sans espaces ni de caractères spéciaux). La longueur maximale est de 20 caractères. Utilisez un nom unique et significatif, comme v20180622-135541.

Affecter un blueprint

Une fois que vous avez publié un blueprint en utilisant l’API REST, il peut être affecté à un abonnement. Affectez le blueprint que vous avez créé à l’un des abonnements de votre hiérarchie de groupes d’administration. Si le blueprint est enregistré dans un abonnement, il ne peut être attribué qu’à cet abonnement. Le Request Body spécifie le blueprint à affecter, et fournit le nom et l’emplacement des groupes de ressources dans la définition du blueprint. Request Body fournit également tous les paramètres définis sur le blueprint et qui sont utilisés par un ou plusieurs artefacts attachés.

Dans chaque URI de l’API REST, remplacez les variables suivantes par vos propres valeurs :

{tenantId} - Remplacez par votre ID de locataire.
{YourMG} - Remplacez par l’ID de votre groupe d’administration.
{subscriptionId} - Remplacez par votre ID d’abonnement.

Fournissez au principal de service d’Azure Blueprints le rôle Owner sur l’abonnement cible. AppId est statique (f71766dc-90d9-4b7d-bd9d-4499c4331c3f), mais l’ID de principal de service varie en fonction du locataire. Utilisez l’API REST suivante pour demander les détails pour votre locataire. Elle utilise l’API Graph Azure Active Directory, qui a une autorisation différente.
- URI de l’API REST
```
GET https://graph.windows.net/{tenantId}/servicePrincipals?api-version=1.6&$filter=appId eq 'f71766dc-90d9-4b7d-bd9d-4499c4331c3f'
```

Exécutez le déploiement du blueprint en l’affectant à un abonnement. Comme les paramètres contributors et owners nécessitent l’octroi de l’attribution de rôle à un tableau de objectIds des principaux, utilisez l’API Graph d’Azure Active Directory pour collecter les objectIds à utiliser dans les Request Body pour vos propres utilisateurs, groupes ou principaux de service.

URI de l’API REST

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

Corps de la requête

{
    "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é managée affectée par l’utilisateur

Une affectation de blueprint peut également utiliser une identité managée affectée par l’utilisateur. Dans ce cas, la partie identity du corps de la requête change de la façon suivante. Remplacez {yourRG} et {userIdentity} par le nom de votre groupe de ressources et le nom de votre identité managée affectée par l’utilisateur, respectivement.
```
"identity": {
    "type": "userAssigned",
    "tenantId": "{tenantId}",
    "userAssignedIdentities": {
        "/subscriptions/{subscriptionId}/resourceGroups/{yourRG}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{userIdentity}": {}
    }
},
```
L’identité managée affectée par l’utilisateur peut être dans n’importe quel abonnement et groupe de ressources pour lesquels l’utilisateur qui affecte le blueprint a les autorisations nécessaires.

Important

Azure Blueprints ne gère pas l’identité managée affectée par l’utilisateur. Les utilisateurs doivent attribuer des rôles et autorisations suffisants. À défaut, l’affectation du blueprint échouera.

Nettoyer les ressources

Annuler l’affectation d’un blueprint

Vous pouvez supprimer un blueprint d’un abonnement. La suppression est souvent effectuée lorsque les ressources d’artefact ne sont plus nécessaires. Quand un blueprint est supprimé, les artefacts affectés dans le cadre de ce blueprint sont abandonnés. Pour supprimer une affectation de blueprint, utilisez l’opération d’API REST suivante :

URI de l’API REST

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

Supprimer un blueprint

Pour supprimer le blueprint, utilisez l’opération d’API REST suivante :

URI de l’API REST

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

Étapes suivantes

Dans ce guide de démarrage rapide, vous avez créé, affecté et supprimé un blueprint avec l’API REST. Pour plus d’informations sur Azure Blueprints, consultez l’article concernant le cycle de vie des blueprints.

En savoir plus sur le cycle de vie des blueprints

Partager via

Démarrage rapide : Définir et affecter un blueprint Azure avec l’API REST

Prérequis

Azure Cloud Shell

Prise en main de l’API REST

API REST et PowerShell

Créer un blueprint

Publier un blueprint

Affecter un blueprint

Nettoyer les ressources

Annuler l’affectation d’un blueprint

Supprimer un blueprint

Étapes suivantes

Commentaires

Ressources supplémentaires