Rövid útmutató: Azure-terv definiálása és hozzárendelése a REST API-val

Cikk
03/08/2024

Fontos

2026. július 11-én a tervek (előzetes verzió) elavultak lesznek. Migrálja a meglévő tervdefiníciókat és -hozzárendeléseket a sablon specifikációiba és üzembehelyezési vermeibe. A tervösszetevőket ARM JSON-sablonokká vagy Az üzembehelyezési verem definiálásához használt Bicep-fájlokká kell konvertálni. Az összetevők ARM-erőforrásként való létrehozásához lásd:

Ebben az oktatóanyagban megismerkedhet az Azure Blueprints használatával a terv szervezeten belüli létrehozásával, közzétételével és hozzárendelésével kapcsolatos gyakori feladatok némelyikével. Ez a képesség segít meghatározni azokat a gyakori mintákat, amelyek az Azure Resource Manager- (ARM-) sablonok, szabályzatok és biztonság alapján újrahasználható és gyorsan üzembe helyezhető konfigurációkat fejlesztenek.

Előfeltételek

Ha még nincs Azure-előfizetése, kezdés előtt hozzon létre egy ingyenes fiókot.
Regisztrálja az erőforrás-szolgáltatót Microsoft.Blueprint . Az utasításokért lásd az erőforrás-szolgáltatókat és típusaikat.

Azure Cloud Shell

Az Azure által üzemeltetett Azure Cloud Shell egy interaktív felület, amelyet a böngészőből használhat. A Bash vagy a PowerShell segítségével is használhatja a Cloud Shellt az Azure-szolgáltatásokhoz. A Cloud Shell előre telepített parancsaival futtathatja a jelen cikkben szereplő kódot anélkül, hogy bármit telepítenie kellene a helyi környezetben.

Az Azure Cloud Shell indítása:

Lehetőség	Példa/hivatkozás
Válassza a Kipróbálás lehetőséget egy kód vagy parancsblokk jobb felső sarkában. A Kipróbálás lehetőség választása nem másolja automatikusan a kódot vagy a parancsot a Cloud Shellbe.
Látogasson el a https://shell.azure.com webhelyre, vagy kattintson a Cloud Shell indítása gombra a böngészőben.
Az Azure Portal jobb felső sarkában található menüben kattintson a Cloud Shell gombra.

Az Azure Cloud Shell használata:

Indítsa el a Cloud Shellt.
A kód vagy parancs másolásához kattintson a Másolás gombra egy kódblokkon (vagy parancsblokkon).
Illessze be a kódot vagy parancsot a Cloud Shell-munkamenetbe a Windows és Linux rendszeren a Ctrl Shift+V billentyűkombinációval+, vagy a Cmd+Shift+V macOS rendszeren való kiválasztásával.
A kód vagy parancs futtatásához válassza az Enter lehetőséget .

A REST API használatának első lépései

Ha nem ismeri a REST API-t, először tekintse át az Azure REST API-referenciát, különösen a kérelem URI-jával és a kérelem törzsével kapcsolatos szakaszokat. Ez a rövid útmutató ezeket a fogalmakat használja az Azure Blueprints használatához, és feltételezi, hogy ismeri őket. Az olyan eszközök, mint az ARMClient , automatikusan képesek kezelni az engedélyezést, és kezdőknek ajánlottak.

Az Azure Blueprints specifikációiért lásd az Azure Blueprints REST API-t.

A REST API és a PowerShell

Ha még nem választott eszközt a REST API-hívások kezeléséhez, ennek az útmutatónak a keretében érdemes a PowerShellt használnia. Az alábbi mintafejléc az Azure-ral való hitelesítéshez használható. Hozzon létre egy hitelesítési fejlécet, más néven tulajdonosi jogkivonatot, és adja meg a REST API URI-t, hogy bármilyen paraméterrel vagy egyRequest 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

Cserélje le {subscriptionId} az előző $restUri változót az előfizetéssel kapcsolatos információk lekéréséhez. A $response változó tartalmazza a Invoke-RestMethod parancsmag eredményét, amelyet elemezhet olyan parancsmagokkal, mint a ConvertFrom-Json. Ha a REST API szolgáltatásvégpont elvárja Request Body, adjon meg egy JSON-formátumú változót a -Body paraméternek Invoke-RestMethod.

Terv létrehozása

A megfelelőségi szabványminták definiálásának első lépése, hogy összeállítunk egy tervet az elérhető erőforrásokból. Hozzunk létre egy MyBlueprint nevű tervet az előfizetés szerepkör- és szabályzat-hozzárendeléseinek konfigurálásához. Ezután hozzáad egy erőforráscsoportot, egy ARM-sablont és egy szerepkör-hozzárendelést az erőforráscsoporthoz.

Feljegyzés

A REST API használatakor először a tervobjektum jön létre. Minden olyan összetevőhöz, amely paraméterekkel rendelkezik, előre meg kell határoznia a paramétereket a kezdeti tervben.

Minden REST API URI-ban cserélje le a következő változókat a saját értékeire:

{YourMG} - Cserélje le a felügyeleti csoport azonosítójára.
{subscriptionId} – Cserélje le az előfizetés azonosítóját.

Feljegyzés

Az előfizetés szintjén is létrehozhat terveket. További információ: terv létrehozása az előfizetési példában.

Hozza létre a kezdeti terv objektumot. Ez Request Body tartalmazza a terv tulajdonságait, a létrehozandó erőforráscsoportokat és a tervszintű paramétereket. A hozzárendelés során beállítja a paramétereket, és a későbbi lépésekben hozzáadott összetevők használják őket.

REST API URI

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

Kérelem törzse

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

Szerepkör-hozzárendelés hozzáadása az előfizetéshez. Ez Request Body határozza meg az összetevő fajtáját, a tulajdonságok a szerepkördefiníció azonosítójához igazodnak, az egyszerű identitások pedig értéktömbként lesznek átadva. Az alábbi példában a megadott szerepkört kapott egyszerű identitások egy olyan paraméterre vannak konfigurálva, amely a terv hozzárendelése során van beállítva. Ez a példa a Contributor beépített szerepkört használja, amelynek GUID azonosítója a b24988ac-6180-42a0-ab88-20f7382dd24ckövetkező: .
- 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
```
- Kérelem törzse
```
{
    "kind": "roleAssignment",
    "properties": {
        "roleDefinitionId": "/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c",
        "principalIds": "[parameters('contributors')]"
    }
}
```

Adjon hozzá egy szabályzat-hozzárendelést az előfizetéshez. Ez Request Body határozza meg az összetevő típusát, a tulajdonságok egy szabályzat- vagy kezdeményezésdefinícióhoz igazodnak, a szabályzat-hozzárendelés pedig úgy van konfigurálva, hogy a tervkiosztás során a megadott tervparamétereket használja. Ez a példa a Apply tag and its default value to resource groups beépített szabályzatot használja, amelynek GUID azonosítója a 49c88fc8-6fd1-46fd-a676-f12d1d3a4c71következő: .

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

Kérelem törzse

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

Adjon hozzá egy másik szabályzat-hozzárendelést a tárcímkéhez (újbóli használattal storageAccountType_ parameter) az előfizetésben. Ez az újabb szabályzat-hozzárendelési összetevő bemutatja, hogy a terveken definiált paramétereket több összetevő is használhatja. A példában a storageAccountType címkét az erőforráscsoporton kell beállítania. Ez az érték információt nyújt a következő lépésben létrehozott tárfiókról. Ez a példa a Apply tag and its default value to resource groups beépített szabályzatot használja, amelynek GUID azonosítója a 49c88fc8-6fd1-46fd-a676-f12d1d3a4c71következő: .

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

Kérelem törzse

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

Sablon hozzáadása az erőforráscsoporthoz. Az Request Body ARM-sablon tartalmazza a sablon normál JSON-összetevőjét, és meghatározza a célerőforrás-csoportot a következővel properties.resourceGroup: . A sablon a sablonnak való átadással újra felhasználja a storageAccountType, tagNameés tagValue a tervparamétereket. A tervparaméterek a sablon számára a JSON-sablon definiálásával properties.parametersérhetők el, és a JSON-sablonon belül azt a kulcs-érték párot használják az érték injektálásához. A terv- és sablonparaméterek nevei lehetnek azonosak, de itt különbözőek, hogy bemutassa, hogyan haladnak át az egyes elemek a tervből a sablonösszetevőbe.

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

Kérelem törzse

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

Adjon hozzá egy szerepkör-hozzárendelést az erőforráscsoporthoz. Az előző szerepkör-hozzárendelési bejegyzéshez hasonlóan az alábbi példa a szerepkör definícióazonosítóját Owner használja, és a tervtől eltérő paramétert ad neki. Ez a példa a Owner beépített szerepkört használja, amelynek GUID azonosítója a 8e3af657-a8ff-443c-a75c-2fe8c4bcb635következő: .

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

Kérelem törzse

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

Terv közzététele

Most, hogy hozzáadta az összetevőket a tervhez, ideje közzétenni. A közzététel elérhetővé teszi a tervet egy előfizetéshez való hozzárendeléshez.

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

A függvény {BlueprintVersion} értéke betűk, számok és kötőjelek sztringje (szóközök és egyéb speciális karakterek nélkül). A maximális hossz 20 karakter. Használjon egyedi és tájékoztató jellegűt, például v20180622-135541.

Terv hozzárendelése

Miután közzétett egy tervet a REST API használatával, az hozzárendelhető egy előfizetéshez. Rendelje hozzá a létrehozott tervet a felügyeleti csoport hierarchiájának egyik előfizetéséhez. Ha a terv egy előfizetésbe van mentve, csak az adott előfizetéshez rendelhető hozzá. Ez Request Body adja meg a hozzárendelni kívánt tervet, és megadja a tervet definiáló erőforráscsoportok nevét és helyét. Request Body A terven definiált és egy vagy több csatolt összetevő által használt összes paramétert is biztosítja.

Minden REST API URI-ban cserélje le a következő változókat a saját értékeire:

{tenantId} - Cserélje le a bérlőazonosítót.
{YourMG} - Cserélje le a felügyeleti csoport azonosítójára.
{subscriptionId} – Cserélje le az előfizetés azonosítóját.

Adja meg az Azure Blueprints szolgáltatásnévnek a Owner célelőfizetéshez tartozó szerepkört. Ez AppId statikus (f71766dc-90d9-4b7d-bd9d-4499c4331c3f), de a szolgáltatásnév azonosítója bérlőnként eltérő. A bérlő adatainak lekéréséhez használja az alábbi REST API-t. Az Azure Active Directory Graph API-t használja, amely eltérő engedéllyel rendelkezik.
- REST API URI
```
GET https://graph.windows.net/{tenantId}/servicePrincipals?api-version=1.6&$filter=appId eq 'f71766dc-90d9-4b7d-bd9d-4499c4331c3f'
```

A tervpéldányt a futtatásához rendelje hozzá egy előfizetéshez. Mivel a és a contributors owners paraméterek megkövetelik, hogy a tagok egy tömbje objectIds megkapja a szerepkör-hozzárendelést, használja az Azure Active Directory Graph API-t a objectIds Request Body saját felhasználók, csoportok vagy szolgáltatásnevek számára való használatra.

REST API URI

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

Kérelem törzse

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

Felhasználó által hozzárendelt felügyelt identitás

A tervhozzárendelések felhasználó által hozzárendelt felügyelt identitást is használhatnak. Ebben az esetben a identity kérelem törzsének része az alábbiak szerint változik. Cserélje le {yourRG} az {userIdentity} erőforráscsoport nevét és a felhasználó által hozzárendelt felügyelt identitás nevét.
```
"identity": {
    "type": "userAssigned",
    "tenantId": "{tenantId}",
    "userAssignedIdentities": {
        "/subscriptions/{subscriptionId}/resourceGroups/{yourRG}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{userIdentity}": {}
    }
},
```
A felhasználó által hozzárendelt felügyelt identitás bármely előfizetésben és erőforráscsoportban lehet, amelyhez a tervet hozzárendelő felhasználó rendelkezik engedélyekkel.

Fontos

Az Azure Blueprints nem kezeli a felhasználó által hozzárendelt felügyelt identitást. A felhasználók felelősek a megfelelő szerepkörök és engedélyek hozzárendeléséért, vagy a terv hozzárendelése meghiúsul.

Az erőforrások eltávolítása

Terv hozzárendelésének megszüntetése

Eltávolíthatja a terveket az előfizetésekből. Az eltávolítás gyakori művelet az összetevők már szükségtelen erőforrásai esetén. Az egyes tervek eltávolításakor az adott tervek keretében hozzárendelt összetevők megmaradnak. A tervhozzárendelések törléséhez használja a következő REST API-műveletet:

REST API URI

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

Terv törlése

Maguknak a terveknek a törléséhez használja a következő REST API-műveletet:

REST API URI

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

Következő lépések

Ebben a rövid útmutatóban létrehozott, hozzárendelt és eltávolított egy tervet a REST API-val. Ha többet szeretne megtudni az Azure Blueprintsről, folytassa a terv életciklusával foglalkozó cikkben.

Tudnivalók a terv életciklusáról

Megosztás a következőn keresztül:

Rövid útmutató: Azure-terv definiálása és hozzárendelése a REST API-val

Előfeltételek

Azure Cloud Shell

A REST API használatának első lépései

A REST API és a PowerShell

Terv létrehozása

Terv közzététele

Terv hozzárendelése

Az erőforrások eltávolítása

Terv hozzárendelésének megszüntetése

Terv törlése

Következő lépések

Visszajelzés

További források