你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

快速入门：使用 REST API 定义和分配 Azure 蓝图

项目
09/22/2023

重要

2026 年 7 月 11 日，蓝图（预览版）将弃用。将现有蓝图定义和分配迁移到模板规格和部署堆栈。蓝图项目将转换为 ARM JSON 模板或用于定义部署堆栈的 Bicep 文件。若要了解如何将项目创作为 ARM 资源，请参阅：

本教程介绍如何使用 Azure 蓝图来执行某些与在组织中创建、发布和分配蓝图相关的常见任务。此技能可帮助你定义常见的模式，以便基于 Azure 资源管理器 (ARM) 模板、策略和安全性开发可重用且可快速部署的配置。

先决条件

如果没有 Azure 订阅，请在开始之前创建一个免费帐户。
注册 Microsoft.Blueprint 资源提供程序。有关用法说明，请参阅资源提供程序和类型。

Azure Cloud Shell

Azure 托管 Azure Cloud Shell（一个可通过浏览器使用的交互式 shell 环境）。可以将 Bash 或 PowerShell 与 Cloud Shell 配合使用来使用 Azure 服务。可以使用 Cloud Shell 预安装的命令来运行本文中的代码，而不必在本地环境中安装任何内容。

若要启动 Azure Cloud Shell，请执行以下操作：

选项	示例/链接
选择代码或命令块右上角的“试用”。选择“试用”不会自动将代码或命令复制到 Cloud Shell。
转到 https://shell.azure.com 或选择启动 Cloud Shell 按钮可在浏览器中打开 Cloud Shell。
选择 Azure 门户右上角菜单栏上的 Cloud Shell 按钮。

若要使用 Azure Cloud Shell，请执行以下操作：

启动 Cloud Shell。
选择代码块（或命令块）上的“复制”按钮以复制代码或命令。
在 Windows 和 Linux 上选择 Ctrl+Shift+V，或在 macOS 上选择 Cmd+Shift+V 将代码或命令粘贴到 Cloud Shell 会话中。
选择“Enter”运行代码或命令。

Get started with REST API（REST API 入门）

如果不熟悉 REST API，请先查看 Azure REST API 参考，特别是有关请求 URI 和请求正文的部分。本快速入门使用这些概念来提供有关如何使用 Azure 蓝图的说明，并假定具有相关的实践经验。 ARMClient 等工具可自动处理授权，建议初学者使用。

有关 Azure 蓝图规范，请参阅 Azure 蓝图 REST API。

REST API 和 PowerShell

如果尚无用于进行 REST API 调用的工具，请考虑使用 PowerShell 获取说明。下面是使用 Azure 进行身份验证的示例标头。生成身份验证标头（有时称为持有者令牌），然后向要连接到的 REST API URI 提供任何参数或 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

替换前面 $restUri 变量中的 {subscriptionId}，以获取订阅的相关信息。 $response 变量可保留 Invoke-RestMethod cmdlet 的结果，后者可使用 ConvertFrom-Json 等 cmdlet 进行分析。如果 REST API 服务终结点需要 Request Body，请向 Invoke-RestMethod 的 -Body 参数提供 JSON 格式的变量。

创建蓝图

定义符合性的标准模式的第一步是根据可用资源构建蓝图。让我们创建一个名为 MyBlueprint 的蓝图，用于配置订阅的角色和策略分配。然后，在资源组上添加资源组、ARM 模板和角色分配。

注意

使用 REST API 时，首先创建 blueprint 对象。对于每个要添加的具有参数的项目，需要在初始蓝图上提前定义该参数。

在每个 REST API URI 中，将以下变量替换为自己的值：

{YourMG} - 替换为管理组的 ID。
{subscriptionId} - 替换为订阅 ID。

注意

也可以在订阅级别创建蓝图。有关详细信息，请参阅在订阅示例中创建蓝图。

创建初始 blueprint 对象。 Request Body 包括有关蓝图的属性、要创建的任何资源组，以及所有蓝图级别参数。在分配过程中设置参数，在后续步骤中添加的项目将使用这些参数。

REST API URI

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

请求正文

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

在订阅中添加角色分配。 Request Body 定义项目的种类、与角色定义标识符一致的属性以及以值的数组形式传递的主体标识。在下面的示例中，主体标识被授予指定的角色，配置为蓝图分配过程中所设置的参数。此示例使用 GUID 为 b24988ac-6180-42a0-ab88-20f7382dd24c 的 Contributor 内置角色。

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

请求正文

{
    "kind": "roleAssignment",
    "properties": {
        "roleDefinitionId": "/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c",
        "principalIds": "[parameters('contributors')]"
    }
}

在订阅中添加策略分配。 Request Body 定义项目的种类、与策略或计划定义一致的属性，以及策略分配被配置为在蓝图分配过程中使用已定义的蓝图参数。此示例使用 GUID 为 49c88fc8-6fd1-46fd-a676-f12d1d3a4c71 的 Apply tag and its default value to resource groups 内置策略。

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

请求正文

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

（通过重复使用 storageAccountType_ parameter）在订阅中为存储标记添加另一个策略分配。此附加的策略分配项目演示了蓝图上定义的参数可由多个项目使用。在示例中，使用 storageAccountType 在资源组上设置标记。此值提供有关下一步骤中创建的存储帐户的信息。此示例使用 GUID 为 49c88fc8-6fd1-46fd-a676-f12d1d3a4c71 的 Apply tag and its default value to resource groups 内置策略。

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

请求正文

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

在资源组下添加模板。 ARM 模板的 Request Body 包括模板的常规 JSON 组件，并使用 properties.resourceGroup 定义目标资源组。该模板还通过将 storageAccountType、tagName 和 tagValue 蓝图参数传递给模板来重用它们。通过定义 properties.parameters 并置于键/值对用于插入值的模板 JSON 内，蓝图参数可供模板使用。蓝图和模板参数名称可以相同，但对于如何分别从蓝图项目传入模板项目的说明有所区别。

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

请求正文

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

在资源组下添加角色分配。与上一角色分配项类似，以下示例对 Owner 角色使用定义标识符，并向其提供不同于蓝图参数的另一参数。此示例使用 GUID 为 8e3af657-a8ff-443c-a75c-2fe8c4bcb635 的 Owner 内置角色。

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

请求正文

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

发布蓝图

现在已将项目添加到蓝图中，可以将其发布了。发布后，即可将蓝图分配到订阅。

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

{BlueprintVersion} 的值是由字母、数字和连字符组成的字符串（不含空格或其他特殊字符）。最大长度为 20 个字符。使用唯一且具有参考性的内容，如 v20180622-135541。

分配蓝图

在使用 REST API 发布蓝图后，即可将其分配给订阅。将创建的蓝图分配到管理组层次结构下的一个订阅。如果蓝图保存到某个订阅，则只能将其分配给该订阅。 Request Body 指定要分配的蓝图，并为蓝图定义中的任何资源组提供名称和位置。 Request Body 还提供了在蓝图上定义并由一个或多个附加项目使用的所有参数。

在每个 REST API URI 中，将以下变量替换为自己的值：

{tenantId} - 替换为租户 ID。
{YourMG} - 替换为管理组的 ID。
{subscriptionId} - 替换为订阅 ID。

在目标订阅上，向 Azure 蓝图服务主体提供 Owner 角色。 AppId 是静态的 (f71766dc-90d9-4b7d-bd9d-4499c4331c3f)，但服务主体 ID 因租户而异。使用以下 REST API 请求租户的详细信息。它可使用具有不同授权的 Azure Active Directory Graph API。
- REST API URI
```
GET https://graph.windows.net/{tenantId}/servicePrincipals?api-version=1.6&$filter=appId eq 'f71766dc-90d9-4b7d-bd9d-4499c4331c3f'
```

通过将蓝图部署分配到订阅，运行它。由于 contributors 和 owners 参数要求主体的 objectIds 数组被授予角色分配，请使用 Azure Active Directory 图形 API 来收集 objectIds，以供自己的用户、组或服务主体在 Request Body 中使用。

REST API URI

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

请求正文

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

用户分配的托管标识

蓝图分配也可使用用户分配的托管标识。在此示例中，请求正文的 identity 部分的更改如下所示。将 {yourRG} 和 {userIdentity} 分别替换为资源组名称和用户分配托管标识的名称。
```
"identity": {
    "type": "userAssigned",
    "tenantId": "{tenantId}",
    "userAssignedIdentities": {
        "/subscriptions/{subscriptionId}/resourceGroups/{yourRG}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{userIdentity}": {}
    }
},
```
用户分配的托管标识可以位于分配蓝图的用户具有访问权限的任何订阅和资源组中。

重要

Azure 蓝图不管理用户分配的托管标识。用户负责分配足够的角色和权限，否则蓝图分配会失败。

清理资源

取消分配蓝图

可以从订阅中删除蓝图。通常会在不再需要项目资源时将其删除。删除蓝图时，作为该蓝图的一部分分配的项目将保留。若要删除蓝图分配，请使用以下 REST API 操作：

REST API URI

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

删除蓝图

若要删除蓝图本身，请使用以下 REST API 操作：

REST API URI

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

后续步骤

在本快速入门中，你使用 REST API 创建、分配并删除了蓝图。若要详细了解 Azure 蓝图，请继续学习蓝图生命周期文章。

了解蓝图生命周期

快速入门：使用 REST API 定义和分配 Azure 蓝图

先决条件

Azure Cloud Shell

Get started with REST API（REST API 入门）

REST API 和 PowerShell

创建蓝图

发布蓝图

分配蓝图

清理资源

取消分配蓝图

删除蓝图

后续步骤

其他资源