Quickstart: Een Azure-blauwdruk definiëren en toewijzen met REST API

Artikel
03/10/2024

Belangrijk

Op 11 juli 2026 worden blauwdrukken (preview) afgeschaft. Migreer uw bestaande blauwdrukdefinities en -toewijzingen naar sjabloonspecificaties en implementatiestacks. Blauwdrukartefacten moeten worden geconverteerd naar ARM JSON-sjablonen of Bicep-bestanden die worden gebruikt om implementatiestacks te definiëren. Zie voor meer informatie over het ontwerpen van een artefact als een ARM-resource:

In deze zelfstudie leert u hoe u Azure Blueprints gebruikt om algemene taken uit te voeren met betrekking tot het maken, publiceren en toewijzen van een blauwdruk binnen uw organisatie. Deze vaardigheid helpt u bij het definiëren van algemene patronen voor het ontwikkelen van herbruikbare en snel implementeerbare configuraties, op basis van ARM-sjablonen (Azure Resource Manager), beleid en beveiliging.

Vereisten

Als u geen Azure-abonnement hebt, maakt u een gratis account voordat u begint.
Registreer de Microsoft.Blueprint-resourceprovider. Zie Resourceproviders en -typen voor aanwijzingen.

Azure Cloud Shell

Azure host Azure Cloud Shell, een interactieve shell-omgeving die u via uw browser kunt gebruiken. U kunt Bash of PowerShell gebruiken met Cloud Shell om met Azure-services te werken. U kunt de vooraf geïnstalleerde Cloud Shell-opdrachten gebruiken om de code in dit artikel uit te voeren zonder dat u iets hoeft te installeren in uw lokale omgeving.

Om Azure Cloud Shell op te starten:

Optie	Voorbeeld/koppeling
Selecteer Uitproberen in de rechterbovenhoek van een code- of opdrachtblok. Als u Try It selecteert, wordt de code of opdracht niet automatisch gekopieerd naar Cloud Shell.
Ga naar https://shell.azure.com, of selecteer de knop Cloud Shell starten om Cloud Shell in uw browser te openen.
Klik op de knop Cloud Shell in het menu in de balk rechtsboven in de Azure-portal.

Azure Cloud Shell gebruiken:

Start Cloud Shell.
Selecteer de knop Kopiëren op een codeblok (of opdrachtblok) om de code of opdracht te kopiëren.
Plak de code of opdracht in de Cloud Shell-sessie door Ctrl+Shift+V in Windows en Linux te selecteren of door Cmd+Shift+V te selecteren in macOS.
Selecteer Enter om de code of opdracht uit te voeren.

Aan de slag met REST API

Als u niet bekend bent met REST API, bekijkt u eerst de Naslaginformatie over de Azure REST API, met name de secties over de aanvraag-URI en de aanvraagbody. In deze quickstart worden deze concepten gebruikt om instructies te bieden voor het werken met Azure Blueprints en wordt ervan uitgegaan dat ze werken. Hulpprogramma's zoals ARMClient kunnen autorisatie automatisch verwerken en worden aanbevolen voor beginners.

Zie Azure Blueprints REST API voor de specificaties van Azure Blueprints.

REST API en PowerShell

Als u nog geen hulpprogramma hebt om REST API-aanroepen te doen, kunt u overwegen PowerShell te gebruiken voor deze instructies. Hier volgt een voorbeeldheader voor verificatie met Azure. Genereer een verificatieheader, ook wel een Bearer-token genoemd, en geef de REST API-URI op om verbinding te maken met parameters of een 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

Vervang {subscriptionId} in de voorgaande $restUri variabele om informatie over uw abonnement op te halen. De $response variabele bevat het resultaat van de Invoke-RestMethod cmdlet, die u kunt parseren met cmdlets zoals ConvertFrom-Json. Als het REST API-service-eindpunt een Request Bodyvariabele in JSON-indeling verwacht, geeft u de -Body parameter van Invoke-RestMethod.

Een blauwdruk maken

De eerste stap bij het definiëren van een standaardpatroon voor naleving is om een blauwdruk samen te stellen uit de beschikbare resources. We gaan een blauwdruk maken met de naam MyBlueprint om rol- en beleidstoewijzingen voor het abonnement te configureren. Vervolgens voegt u een resourcegroep, een ARM-sjabloon en een roltoewijzing toe aan de resourcegroep.

Notitie

Wanneer u de REST API gebruikt, wordt het blauwdrukobject eerst gemaakt. Voor elk artefact dat moet worden toegevoegd met parameters, definieert u de parameters vooraf op de eerste blauwdruk.

Vervang in elke REST API-URI de volgende variabelen door uw eigen waarden:

{YourMG} - Vervang door de id van uw beheergroep.
{subscriptionId} - Vervang door uw abonnements-id.

Notitie

U kunt ook blauwdrukken maken op abonnementsniveau. Zie een blauwdruk maken in het abonnementsvoorbeeld voor meer informatie.

Maak het eerste blauwdrukobject. De Request Body bevat eigenschappen over de blauwdruk, resourcegroepen die moeten worden gemaakt en alle parameters op blauwdrukniveau. U stelt de parameters in tijdens de toewijzing en ze worden gebruikt door de artefacten die u in latere stappen toevoegt.

REST API-URI

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

Aanvraagbody

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

Voeg een roltoewijzing toe aan het abonnement. Hiermee Request Body definieert u het soort artefact, worden de eigenschappen uitgelijnd met de roldefinitie-id en worden de principal-identiteiten doorgegeven als een matrix met waarden. In het volgende voorbeeld worden de principal-identiteiten aan de opgegeven rol geconfigureerd voor een parameter die is ingesteld tijdens de blauwdruktoewijzing. In dit voorbeeld wordt de Contributor ingebouwde rol gebruikt, met een GUID van b24988ac-6180-42a0-ab88-20f7382dd24c.
- REST API-URI
```
PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint/artifacts/roleContributor?api-version=2018-11-01-preview
```
- Aanvraagbody
```
{
    "kind": "roleAssignment",
    "properties": {
        "roleDefinitionId": "/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c",
        "principalIds": "[parameters('contributors')]"
    }
}
```

Voeg een beleidstoewijzing toe aan het abonnement. Hiermee Request Body definieert u het soort artefact, worden de eigenschappen afgestemd op een beleids- of initiatiefdefinitie en wordt de beleidstoewijzing geconfigureerd voor het gebruik van de gedefinieerde blauwdrukparameters tijdens de toewijzing van de blauwdruk. In dit voorbeeld wordt het Apply tag and its default value to resource groups ingebouwde beleid gebruikt, met een GUID van 49c88fc8-6fd1-46fd-a676-f12d1d3a4c71.

REST API-URI

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

Aanvraagbody

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

Voeg nog een beleidstoewijzing toe voor de opslagtag (door opnieuw te gebruiken storageAccountType_ parameter) in het abonnement. Deze aanvullende beleidstoewijzingsartefact laat zien dat een in de blauwdruk gedefinieerde parameter door meer dan één artefact kan worden gebruikt. In het voorbeeld gebruikt u de storageAccountType opdracht om een tag in te stellen voor de resourcegroep. Deze waarde bevat informatie over het opslagaccount dat u in de volgende stap maakt. In dit voorbeeld wordt het Apply tag and its default value to resource groups ingebouwde beleid gebruikt, met een GUID van 49c88fc8-6fd1-46fd-a676-f12d1d3a4c71.

REST API-URI

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

Aanvraagbody

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

Voeg een sjabloon toe onder de resourcegroep. Het Request Body voor een ARM-sjabloon bevat het normale JSON-onderdeel van de sjabloon en definieert de doelresourcegroep met properties.resourceGroup. De sjabloon hergebruikt ook de storageAccountTypeparameters en tagNametagValue blauwdrukparameters door elk door te geven aan de sjabloon. De blauwdrukparameters zijn beschikbaar voor de sjabloon door het definiëren properties.parametersen in de sjabloon-JSON die sleutel-waardepaar wordt gebruikt om de waarde in te voeren. De namen van de blauwdruk- en sjabloonparameter kunnen hetzelfde zijn, maar zijn hier anders om te laten zien hoe elke blauwdruk wordt doorgegeven aan het sjabloonartefact.

REST API-URI

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

Aanvraagbody

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

Voeg een roltoewijzing toe onder de resourcegroep. Net als bij de vorige roltoewijzingsvermelding gebruikt het volgende voorbeeld de definitie-id voor de Owner rol en biedt het een andere parameter dan de blauwdruk. In dit voorbeeld wordt de Owner ingebouwde rol gebruikt, met een GUID van 8e3af657-a8ff-443c-a75c-2fe8c4bcb635.

REST API-URI

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

Aanvraagbody

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

Een blauwdruk publiceren

Nu u de artefacten aan de blauwdruk hebt toegevoegd, is het tijd om deze te publiceren. Publiceren maakt de blauwdruk beschikbaar om toe te wijzen aan een abonnement.

REST API-URI

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

De waarde voor {BlueprintVersion} is een tekenreeks met letters, cijfers en afbreekstreepjes (zonder spaties of andere speciale tekens). De maximumlengte is 20 tekens. Gebruik iets unieks en informatief, zoals v20180622-135541.

Een blauwdruk toewijzen

Nadat u een blauwdruk hebt gepubliceerd met behulp van REST API, kan deze worden toegewezen aan een abonnement. Wijs de blauwdruk die u hebt gemaakt toe aan een van de abonnementen in uw beheergroephiërarchie. Als de blauwdruk is opgeslagen in een abonnement, kan deze alleen aan dat abonnement worden toegewezen. Hiermee Request Body geeft u de blauwdruk op die u wilt toewijzen en geeft u de naam en locatie op voor resourcegroepen in de blauwdrukdefinitie. Request Body biedt ook alle parameters die zijn gedefinieerd op de blauwdruk en die worden gebruikt door een of meer gekoppelde artefacten.

Vervang in elke REST API-URI de volgende variabelen door uw eigen waarden:

{tenantId} - Vervang deze door uw tenant-id.
{YourMG} - Vervang door de id van uw beheergroep.
{subscriptionId} - Vervang door uw abonnements-id.

Geef de Azure Blueprints-service-principal de Owner rol op voor het doelabonnement. Het AppId is statisch (f71766dc-90d9-4b7d-bd9d-4499c4331c3f), maar de id van de service-principal verschilt per tenant. Gebruik de volgende REST API om details voor uw tenant aan te vragen. Deze gebruikt Azure Active Directory Graph API, die een andere autorisatie heeft.
- REST API-URI
```
GET https://graph.windows.net/{tenantId}/servicePrincipals?api-version=1.6&$filter=appId eq 'f71766dc-90d9-4b7d-bd9d-4499c4331c3f'
```

Voer de blauwdrukimplementatie uit door deze toe te wijzen aan een abonnement. Omdat aan de contributors en owners parameters een matrix van objectIds de principals is vereist om de roltoewijzing te krijgen, gebruikt u Azure Active Directory Graph API om het objectIds te verzamelen voor gebruik in de Request Body voor uw eigen gebruikers, groepen of service-principals.

REST API-URI

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

Aanvraagbody

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

Door de gebruiker toegewezen beheerde identiteit

Een blauwdruktoewijzing kan ook gebruikmaken van een door een gebruiker toegewezen beheerde identiteit. In dit geval verandert het identity gedeelte van de hoofdtekst van de aanvraag als volgt. Vervang de naam van de resourcegroep en de naam van de door een gebruiker toegewezen beheerde identiteit door respectievelijk {yourRG} en {userIdentity}.
```
"identity": {
    "type": "userAssigned",
    "tenantId": "{tenantId}",
    "userAssignedIdentities": {
        "/subscriptions/{subscriptionId}/resourceGroups/{yourRG}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{userIdentity}": {}
    }
},
```
De door de gebruiker toegewezen beheerde identiteit kan zich in elk abonnement en elke resourcegroep bevinden waaraan de gebruiker die de blauwdruk toewijst, machtigingen heeft.

Belangrijk

De door een gebruiker toegewezen beheerde identiteit wordt niet beheerd door Azure Blueprints. Gebruikers zijn verantwoordelijk voor het toewijzen van voldoende rollen en machtigingen, of de blauwdruktoewijzing mislukt.

Resources opschonen

De toewijzing van een blauwdruk ongedaan maken

U kunt een blauwdruk uit een abonnement verwijderen. Het verwijderen wordt vaak uitgevoerd als de artefactresources niet langer nodig zijn. Wanneer een blauwdruk wordt verwijderd, blijven de artefacten die als onderdeel van die blauwdruk zijn toegewezen, achter. Als u de toewijzing van een blauwdruk ongedaan wilt maken, gebruikt u de volgende REST API-bewerking:

REST API-URI

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

Een blauwdruk verwijderen

Als u de blauwdruk zelf wilt verwijderen, gebruikt u de volgende REST API-bewerking:

REST API-URI

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

Volgende stappen

In deze quickstart hebt u een blauwdruk gemaakt, toegewezen en verwijderd met REST API. Ga verder met het artikel over de levenscyclus van blauwdrukken voor meer informatie over Azure Blueprints.

Meer informatie over de levenscyclus van een blauwdruk

Quickstart: Een Azure-blauwdruk definiëren en toewijzen met REST API

Vereisten

Azure Cloud Shell

Aan de slag met REST API

REST API en PowerShell

Een blauwdruk maken

Een blauwdruk publiceren

Een blauwdruk toewijzen

Resources opschonen

De toewijzing van een blauwdruk ongedaan maken

Een blauwdruk verwijderen

Volgende stappen

Aanvullende resources