Краткое руководство. Определение и назначение схемы Azure с помощью REST API

Статья
09/07/2023

Внимание

11 июля 2026 г. схемы (предварительная версия) будут устарели. Перенос существующих определений схемы и назначений в спецификации шаблонов и стеки развертывания. Артефакты схемы необходимо преобразовать в шаблоны JSON ARM или файлы Bicep, используемые для определения стеков развертывания. Сведения о создании артефакта в качестве ресурса ARM см. в статье:

Из этого руководства вы узнаете, как с помощью службы Azure Blueprints выполнять некоторые общие задачи, связанных с созданием, публикацией и назначением схемы в вашей организации. Этот навык помогает создавать стандартные шаблоны для разработки многоразовых и быстро развертываемых конфигураций на основе шаблонов, политик и правил безопасности Azure Resource Manager (ARM).

Необходимые компоненты

Если у вас нет подписки Azure, создайте бесплатную учетную запись, прежде чем приступить к работе.
Зарегистрируйте поставщик ресурсов Microsoft.Blueprint. См. инструкции в статье Поставщики и типы ресурсов Azure.

Azure Cloud Shell

В Azure есть Azure Cloud Shell, интерактивная оболочка среды, с которой можно работать в браузере. Для работы со службами Azure можно использовать Bash или PowerShell с Cloud Shell. Для запуска кода из этой статьи можно использовать предварительно установленные команды Cloud Shell. Ничего дополнительного в локальной среде устанавливать не нужно.

Начало работы с Azure Cloud Shell

Вариант	Пример и ссылка
Нажмите кнопку Попробовать в правом верхнем углу блока кода или команд. При нажатии кнопки Попробовать код или команда не копируется в Cloud Shell автоматически.
Чтобы открыть Cloud Shell в браузере, перейдите по адресу https://shell.azure.com или нажмите кнопку Запуск Cloud Shell.
Нажмите кнопку Cloud Shell в строке меню в правом верхнем углу окна портала Azure.

Чтобы использовать Azure Cloud Shell, выполните следующие действия:

Запустите Cloud Shell.
Нажмите кнопку Копировать в блоке кода (или блоке команд), чтобы скопировать код или команду.
Вставьте код или команду в окно сеанса Cloud Shell, нажав клавиши CTRL+SHIFT+V в Windows и Linux или CMD+SHIFT+V в macOS.
Нажмите клавишу ВВОД, чтобы запустить код или команду.

Начало работы с REST API

Если у вас нет опыта работы с интерфейсом REST API, сначала ознакомьтесь со справочником по REST API Azure, в частности с разделами о URI запроса и тексте запроса. В этом кратком руководстве эти понятия используются в указаниях по работе с Azure Blueprints, поэтому предполагается, что у вас есть соответствующие практические навыки. Начинающим рекомендуется применять такие средства, как ARMClient, обеспечивающие автоматическую авторизацию.

Спецификации по Azure Blueprints см. в статье о REST API для Azure Blueprints.

REST API и PowerShell

Если у вас еще нет средства для выполнения вызовов REST API, рекомендуем использовать среду PowerShell. Ниже приведен пример заголовка для проверки подлинности в Azure. Создайте заголовок проверки подлинности, иногда называемый маркером носителя, и укажите универсальный код ресурса (URI) REST API, к которому нужно подключиться, а также параметры или 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

Замените {subscriptionId} в предыдущей переменной $restUri, чтобы получить сведения о своей подписке. Переменная $response содержит результат выполнения командлета Invoke-RestMethod, который можно проанализировать с помощью таких командлетов, как ConvertFrom-Json. Если конечная точка службы REST API требует Request Body, укажите переменную в формате JSON в качестве параметра -Body для Invoke-RestMethod.

Создание схемы

Первым этапом при определении стандартной модели соответствия требованиям является формирование схемы на основе доступных ресурсов. Мы создадим схему с именем MyBlueprint для настройки назначения ролей и политик для подписки. Затем мы добавим группу ресурсов, шаблон ARM и назначение ролей группе ресурсов.

Примечание.

При использовании REST API сначала создается объект схемы. Для каждого добавляемого артефакта с параметрами нужно заранее определить параметры в исходной схеме.

В каждом URI REST API замените следующие переменные собственными значениями:

{YourMG}— замените это значение идентификатором своей группы управления.
{subscriptionId} — замените это значение идентификатором своей подписки.

Примечание.

Вы также можете создавать схемы на уровне подписки. Дополнительные сведения см. в разделе Пример создания схемы на уровне подписки.

Создайте исходный объект схемы. Request Body содержит свойства схемы, группы ресурсов, которые необходимо создать, и все параметры уровня схемы. Эти параметры задаются при назначении и используются артефактами, которые будут добавлены в дальнейшем.

Универсальный код ресурса (URI) REST API

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 определяется тип артефакта и свойства, соответствующие идентификатору определения роли, а удостоверения субъектов передаются в виде массива значений. В приведенном ниже примере удостоверения субъектов, которым предоставляется указанная роль, передаются в параметре, задаваемом во время назначения схемы. В этом примере используется встроенная роль Contributor с GUID b24988ac-6180-42a0-ab88-20f7382dd24c.
- Универсальный код ресурса (URI) REST API
```
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 определяется тип артефакта и свойства, соответствующие определению политики или инициативы, а также настраивается назначение политики для использования указанных параметров схемы во время назначения схемы. В этом примере используется встроенная политика Apply tag and its default value to resource groups с глобальным уникальным идентификатором 49c88fc8-6fd1-46fd-a676-f12d1d3a4c71.
- Универсальный код ресурса (URI) REST API
```
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 используется для настройки тега группы ресурсов. Это значение предоставляет сведения об учетной записи хранения, которая будет создана на следующем шаге. В этом примере используется встроенная политика Apply tag and its default value to resource groups с глобальным уникальным идентификатором 49c88fc8-6fd1-46fd-a676-f12d1d3a4c71.
- Универсальный код ресурса (URI) REST API
```
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')]"
            }
        }
    }
}
```

Добавьте шаблон в группу ресурсов: Request Body шаблона ARM содержит обычный компонент JSON шаблона и определяет целевую группу ресурсов с помощью properties.resourceGroup. Шаблон также повторно использует storageAccountTypetagNameпараметры схемы и tagValue схемы путем передачи каждого из них в шаблон. Чтобы параметры схемы были доступны шаблону, задается properties.parameters. В коде JSON шаблона эта пара "ключ — значение" используется для внедрения значения. Имена параметров схемы и шаблона могут совпадать, но здесь они различаются, чтобы можно было наглядно увидеть, как каждый из них передается из схемы в артефакт шаблона.

Универсальный код ресурса (URI) REST API

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, но из схемы для него передается другой параметр. В этом примере используется встроенная роль Owner с GUID 8e3af657-a8ff-443c-a75c-2fe8c4bcb635.
- Универсальный код ресурса (URI) REST API
```
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')]"
    }
}
```

Публикация схемы

Теперь, когда артефакты добавлены в схему, пора ее опубликовать. После публикации схему можно будет назначить подписке.

Универсальный код ресурса (URI) REST API

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 также предоставляет все параметры, определенные в схеме и используемые одним или несколькими присоединенными артефактами.

В каждом URI REST API замените следующие переменные собственными значениями:

{tenantId} — замените это значение своим идентификатором клиента.
{YourMG}— замените это значение идентификатором своей группы управления.
{subscriptionId} — замените это значение идентификатором своей подписки.

Предоставьте субъекту-службе Azure Blueprints роль Owner в целевой подписке. AppId является статическим (f71766dc-90d9-4b7d-bd9d-4499c4331c3f), но идентификаторы субъекта-службы у клиентов различны. Используйте следующие REST API для запроса сведений о клиенте. Он использует API Graph Azure Active Directory, схема авторизации которого отличается.
- Универсальный код ресурса (URI) REST API
```
GET https://graph.windows.net/{tenantId}/servicePrincipals?api-version=1.6&$filter=appId eq 'f71766dc-90d9-4b7d-bd9d-4499c4331c3f'
```
Запустите развертывание схемы, назначив ее подписке. Поскольку в параметрах contributors и owners должны быть переданы массивы идентификаторов objectIds субъектов, которым должно быть предоставлено назначение ролей, используйте API Graph Azure Active Directory для сбора идентификаторов objectIds, которые вы затем будете использовать в параметре Request Body для собственных пользователей, групп или субъектов-служб.
- Универсальный код ресурса (URI) REST API
```
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 Blueprints не администрирует управляемое удостоверение, назначаемое пользователем. Назначение соответствующих ролей и разрешений выполняют пользователи. В противном случае назначение схемы завершится ошибкой.

Очистка ресурсов

Отмена назначения схемы

Вы можете удалить схему из подписки. Удаление часто выполняется, когда ресурсы артефакта больше не требуются. При удалении схемы назначенные артефакты оставляются. Чтобы отменить назначение схемы, используйте следующую операцию REST API:

Универсальный код ресурса (URI) REST API

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

Удаление схемы

Чтобы удалить саму схему, используйте следующую операцию REST API:

Универсальный код ресурса (URI) REST API

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

Следующие шаги

В рамках этого краткого руководства вы создали, назначили и удалили схему с помощью REST API. Чтобы узнать больше о схемах Azure, перейдите к статье о жизненном цикле схемы.

Ознакомьтесь со сведениями о жизненном цикле схем

Краткое руководство. Определение и назначение схемы Azure с помощью REST API

Необходимые компоненты

Azure Cloud Shell

Начало работы с REST API

REST API и PowerShell

Создание схемы

Публикация схемы

Назначение схемы

Очистка ресурсов

Отмена назначения схемы

Удаление схемы

Следующие шаги

Дополнительные ресурсы