快速入門：使用 REST API 定義和指派 Azure 藍圖

文章
06/14/2024

重要

在 2026 年 7 月 11 日，藍圖 (預覽) 將會淘汰。將現有的藍圖定義和指派移轉至範本規格和部署堆疊。藍圖成品會轉換成用來定義部署堆疊的 ARM JSON 範本或 Bicep 檔案。若要了解如何將成品撰寫為 ARM 資源，請參閱：

在本教學課程中，您將了解如何使用 Azure 藍圖在您的組織中處理藍圖的建立、發佈和指派等常見工作。此技能可協助您根據 Azure Resource Manager (ARM) 範本、原則和安全性定義常用模式，開發可重複使用並可快速部署的設定。

必要條件

如果您沒有 Azure 訂用帳戶，請在開始前建立免費帳戶。
註冊 Microsoft.Blueprint 資源提供者。如需指示，請參閱資源提供者和類型。

Azure Cloud Shell

Azure Cloud Shell 是裝載於 Azure 中的互動式殼層環境，可在瀏覽器中使用。您可以使用 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 鍵執行程式碼或命令。

開始使用 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，請提供一個 JSON 格式的變數給 -Body 的 Invoke-RestMethod 參數。

建立藍圖

定義合規性標準模式的第一個步驟，即是以可用的資源規劃藍圖。讓我們建立名為 MyBlueprint 的藍圖，設定訂用帳戶的角色和原則指派。接著，您新增資源群組、ARM 範本，以及資源群組的角色指派。

注意

使用 REST API 時，會先建立藍圖物件。對於要新增的具有參數的每個成品，您會在初始藍圖上預先定義參數。

在每個 REST API URI 中，以您自己的值取代下列變數：

{YourMG} - 取代為您的管理群組識別碼。
{subscriptionId} - 取代為您的訂用帳戶識別碼。

注意

您也可以在訂用帳戶層級建立藍圖。如需詳細資訊，請參閱在訂用帳戶建立藍圖範例。

建立初始藍圖物件。 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} - 取代為您的租用戶識別碼。
{YourMG} - 取代為您的管理群組識別碼。
{subscriptionId} - 取代為您的訂用帳戶識別碼。

在目標訂用帳戶上提供 Azure 藍圖服務主題 Owner 角色。 AppId 是靜態的 (f71766dc-90d9-4b7d-bd9d-4499c4331c3f)，但服務主體識別碼則依租用戶而各有不同。使用下列 REST API 來要求租用戶的詳細資料。它使用具有不同授權的 Azure Active Directory 圖形 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 Graph 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

開始使用 REST API

REST API 和 PowerShell

建立藍圖

發佈藍圖

指派藍圖

清除資源

取消指派藍圖

刪除藍圖

下一步

意見反映

更多資源