빠른 시작: REST API로 Azure 청사진 정의 및 할당

아티클
09/07/2023

Important

2026년 7월 11일에 청사진(미리 보기)이 사용 중단됩니다. 기존 청사진 정의와 할당을 템플릿 사양과 배포 스택으로 마이그레이션하세요. 청사진 아티팩트는 배포 스택을 정의하는 데 사용되는 ARM JSON 템플릿 또는 Bicep 파일로 변환됩니다. 아티팩트를 ARM 리소스로 작성하는 방법을 알아보려면 다음을 참조하세요.

이 자습서에서는 Azure Blueprints를 사용하여 조직 내에서 청사진을 작성, 게시 및 할당하는 것과 관련된 일반적인 작업을 수행하는 방법을 알아봅니다. 이 기술은 ARM(Azure Resource Manager) 템플릿, 정책 및 보안을 기반으로 재사용 가능하고 신속하게 배포할 수 있는 구성을 개발하기 위한 공통 패턴을 정의하는 데 유용합니다.

필수 조건

Azure 구독이 없는 경우 시작하기 전에 체험 계정을 만듭니다.
Microsoft.Blueprint 리소스 공급자를 등록합니다. 지침은 리소스 공급자 및 형식을 참조하세요.

Azure Cloud Shell

Azure는 브라우저를 통해 사용할 수 있는 대화형 셸 환경인 Azure Cloud Shell을 호스트합니다. Cloud Shell에서 Bash 또는 PowerShell을 사용하여 Azure 서비스 작업을 수행할 수 있습니다. 로컬 환경에 아무 것도 설치할 필요 없이 Azure Cloud Shell의 미리 설치된 명령을 사용하여 이 문서의 코드를 실행할 수 있습니다.

Azure Cloud Shell을 시작하려면 다음을 수행합니다.

옵션	예제/링크
코드 또는 명령 블록의 오른쪽 상단에서 시도를 선택합니다. 시도를 선택해도 코드 또는 명령이 Cloud Shell에 자동으로 복사되지 않습니다.
https://shell.azure.com으로 이동하거나 Cloud Shell 시작 단추를 선택하여 브라우저에서 Cloud Shell을 엽니다.
Azure Portal의 오른쪽 위에 있는 메뉴 모음에서 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 Blueprints를 사용하는 작업에 대한 지침을 제공하며 이에 대한 실무 지식이 있다고 가정합니다. ARMClient 등과 같은 도구는 인증을 자동으로 처리할 수 있으며 초보자가 사용하면 좋습니다.

Azure Blueprints 사양은 Azure Blueprints REST API를 참조하세요.

REST API 및 PowerShell

REST API 호출을 만드는 도구가 없는 경우 지침에 대해 PowerShell을 사용하는 것이 좋습니다. 다음은 Azure로 인증을 수행하기 위한 샘플 헤더입니다. 인증 헤더(다른 이름: 전달자 토큰)를 생성하고 모든 매개 변수 또는 Request Body에 연결할 REST API URI를 제공합니다.

# 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 변수는 ConvertFrom-Json과 같은 cmdlet으로 구문 분석할 수 있는 Invoke-RestMethod cmdlet의 결과를 보관합니다. REST API 서비스 엔드포인트에 Request Body이 필요하면 JSON 형식의 변수를 Invoke-RestMethod의 -Body 매개 변수에 제공합니다.

청사진 만들기

규정 준수를 위한 표준 패턴을 정의하는 첫 단계는 사용 가능한 리소스로 청사진을 작성하는 것입니다. 구독에 대한 역할 및 정책 할당을 구성하는 MyBlueprint라는 청사진을 만들어 보겠습니다. 그런 다음, 리소스 그룹, ARM 템플릿 및 리소스 그룹에 대한 역할 할당을 추가합니다.

참고 항목

REST API를 사용하는 경우 청사진 개체가 먼저 생성됩니다. 매개 변수가 있는 추가할 아티팩트마다 초기 청사진에 매개 변수를 미리 정의해야 합니다.

각 REST API URI에서 다음 변수를 사용자 고유의 값으로 바꿉니다.

{YourMG} - 사용자의 관리 그룹 ID로 바꿉니다.
{subscriptionId} - 사용자의 구독 ID로 바꿉니다.

참고 항목

구독 수준에서 청사진을 만들 수도 있습니다. 자세한 내용은 구독 수준에서 청사진 만들기 예제를 참조하세요.

초기 청사진 개체를 만듭니다. 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은 아티팩트의 종류를 정의하고 속성은 역할 정의 식별자에 정렬되며 주체 ID는 값 배열의 형태로 전달됩니다. 다음 예에서 지정된 역할에 부여된 주체 ID는 청사진 할당 중에 설정되는 매개 변수로 구성됩니다. 이 예제에서는 b24988ac-6180-42a0-ab88-20f7382dd24c의 GUID와 함께 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은 아티팩트의 종류, 정책 또는 이니셔티브 정의에 부합하는 속성을 정의하고, 청사진 할당 중에 정의된 청사진 매개 변수를 사용하도록 정책 할당을 구성합니다. 이 예제에서는 49c88fc8-6fd1-46fd-a676-f12d1d3a4c71의 GUID와 함께 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을 사용합니다. 이 값은 다음 단계에서 만드는 스토리지 계정에 대한 정보를 제공합니다. 이 예제에서는 49c88fc8-6fd1-46fd-a676-f12d1d3a4c71의 GUID와 함께 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 역할에 대한 정의 식별자를 사용하고 청사진과 다른 매개 변수를 제공합니다. 이 예제에서는 8e3af657-a8ff-443c-a75c-2fe8c4bcb635의 GUID와 함께 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 Blueprints 서비스 주체에게 대상 구독에서 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 Graph API를 사용하여 사용자, 그룹 또는 서비스 주체의 Request Body에서 사용할 objectIds를 수집합니다.

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

사용자 할당 관리 ID

청사진 할당은 사용자가 할당한 관리형 ID로 사용할 수 있습니다. 이러한 경우 요청 본문의 identity 부분이 다음과 같이 변경됩니다. {yourRG}와 {userIdentity}를 각각 리소스 그룹 이름과 사용자가 할당한 관리형 ID의 이름으로 바꿉니다.
```
"identity": {
    "type": "userAssigned",
    "tenantId": "{tenantId}",
    "userAssignedIdentities": {
        "/subscriptions/{subscriptionId}/resourceGroups/{yourRG}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{userIdentity}": {}
    }
},
```
사용자가 할당한 관리 ID는 청사진을 할당하는 사용자에게 권한이 있는 모든 구독 및 리소스 그룹에 있을 수 있습니다.

Important

Azure Blueprints는 사용자 할당 관리 ID를 관리하지 않습니다. 사용자가 충분한 역할과 권한을 할당해야 합니다. 그렇지 않으면 청사진 할당이 실패합니다.

리소스 정리

청사진 할당 취소

구독에서 청사진을 제거할 수 있습니다. 아티팩트 리소스가 더 이상 필요 없는 경우에 청사진을 제거하는 경우가 많습니다. 청사진을 제거해도 해당 청사진의 일부분으로 할당된 아티팩트는 남아 있습니다. 청사진 할당을 제거하려면 다음 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 Blueprints에 대해 자세히 알아보려면 청사진 수명 주기 문서를 참조하세요.

청사진 수명 주기에 대해 알아보기

빠른 시작: REST API로 Azure 청사진 정의 및 할당

필수 조건

Azure Cloud Shell

REST API 시작

REST API 및 PowerShell

청사진 만들기

청사진 게시

청사진 할당

리소스 정리

청사진 할당 취소

청사진 삭제

다음 단계

추가 리소스