Управление назначениями с помощью PowerShell

  • Статья

Важно!

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

Назначением схемы можно управлять при помощи модуля Azure PowerShell Az.Blueprint. В этом модуле поддерживается получение, создание, обновление и удаление назначений. Этот модуль также может получать сведения о существующих определениях схем. В этой статье описывается установка модуля и начало его использования.

Добавление модуля Az.Blueprint

Чтобы позволить Azure PowerShell управлять назначениями схем, необходимо добавить модуль. Этот модуль можно использовать с локально установленной средой PowerShell, с Azure Cloud Shell либо с образом Docker Azure PowerShell.

Основные требования

Модуль Azure Blueprints требует следующее программное обеспечение:

  • Azure PowerShell 1.5.0 или более поздней версии. Если она еще не установлена, выполните эти инструкции.
  • Модуль PowerShellGet 2.0.1 или более поздней версии. Если он еще не установлен или не обновлен, выполните эти инструкции.

Установка модуля

Модуль Azure Blueprints для PowerShell — Az.Blueprint.

  1. Запустите следующие команды из командной строки PowerShell с правами администратора.

    # Install the Azure Blueprints module from PowerShell Gallery
Install-Module -Name Az.Blueprint

    Примечание

    Если учетные записи Az.Accounts уже установлены, для принудительной установки может потребоваться использование -AllowClobber.

  2. Убедитесь, что модуль импортирован и имеет требуемую версию (0.2.6):

    # Get a list of commands for the imported Az.Blueprint module
Get-Command -Module 'Az.Blueprint' -CommandType 'Cmdlet'

Получение определений схем

Первым шагом для работы с назначением является получение ссылки на определение схемы. Командлет Get-AzBlueprint получает одно или несколько определений схем. Данный командлет может получить определения схем из группы управления с помощью -ManagementGroupId {mgId} или подписки на -SubscriptionId {subId}. Параметр Name (Имя) получает определение схемы и должен использоваться совместно с параметрами ManagementGroupId или SubscriptionId. Параметр Version (Версия) можно использовать с параметром Name (Имя), чтобы точнее задать получаемое определение схемы. В отличие от параметра Version (Версия), переключатель -LatestPublished извлекает последнюю опубликованную версию.

В следующем примере Get-AzBlueprint используется для получения всех версий определения схемы с именем "101-blueprints-definition-subscription" из конкретной подписки, представленной в виде {subId}:

# Login first with Connect-AzAccount if not using Cloud Shell

# Get all versions of the blueprint definition in the specified subscription
$blueprints = Get-AzBlueprint -SubscriptionId '{subId}' -Name '101-blueprints-definition-subscription'

# Display the blueprint definition object
$blueprints

Пример выходных данных для определения схемы с несколькими версиями:

Name                 : 101-blueprints-definition-subscription
Id                   : /subscriptions/{subId}/providers/Microsoft.Blueprint/blueprints/101
                       -blueprints-definition-subscription
DefinitionLocationId : {subId}
Versions             : {1.0, 1.1}
TimeCreated          : 2019-02-25
TargetScope          : Subscription
Parameters           : {storageAccount_storageAccountType, storageAccount_location,
                       allowedlocations_listOfAllowedLocations, [Usergrouporapplicationname]:Reader_RoleAssignmentName}
ResourceGroups       : ResourceGroup

В определении схемы можно расширить список параметров схемы для предоставления дополнительных сведений.

$blueprints.Parameters

Key                                                    Value
---                                                    -----
storageAccount_storageAccountType                      Microsoft.Azure.Commands.Blueprint.Models.PSParameterDefinition
storageAccount_location                                Microsoft.Azure.Commands.Blueprint.Models.PSParameterDefinition
allowedlocations_listOfAllowedLocations                Microsoft.Azure.Commands.Blueprint.Models.PSParameterDefinition
[Usergrouporapplicationname]:Reader_RoleAssignmentName Microsoft.Azure.Commands.Blueprint.Models.PSParameterDefinition

Получение назначений схем

Если назначение схемы уже существует, на него можно получить ссылку при помощи командлета Get-AzBlueprintAssignment. Командлет воспринимает параметры SubscriptionId и Name как необязательные. Если параметр SubscriptionId не указан, используется текущий контекст подписки.

В следующем примере Get-AzBlueprintAssignment используется для получения одного назначения схемы с именем Assignment-lock-resource-groups из конкретной подписки, представленной в виде {subId}:

# Login first with Connect-AzAccount if not using Cloud Shell

# Get the blueprint assignment in the specified subscription
$blueprintAssignment = Get-AzBlueprintAssignment -SubscriptionId '{subId}' -Name 'Assignment-lock-resource-groups'

# Display the blueprint assignment object
$blueprintAssignment

Пример выходных данных для назначения схемы:

Name              : Assignment-lock-resource-groups
Id                : /subscriptions/{subId}/providers/Microsoft.Blueprint/blueprintAssignme
                    nts/Assignment-lock-resource-groups
Scope             : /subscriptions/{subId}
LastModified      : 2019-02-19
LockMode          : AllResourcesReadOnly
ProvisioningState : Succeeded
Parameters        :
ResourceGroups    : ResourceGroup

Создание назначений схем

Если назначение схемы еще не существует, его можно создать при помощи командлета New-AzBlueprintAssignment. Для этого командлета требуются следующие параметры:

  • Name [обязательный]:

    • Указывает имя назначения схемы
    • Имя должно быть уникальным и не существовать в SubscriptionId

  • Blueprint [обязательный]:

    • Указывает определение схемы для назначения
    • используйте Get-AzBlueprint для получения объекта ссылки.

  • Location [обязательный]

    • Указывает область управляемого удостоверения, назначаемого системой, и объекта развертывания подписки, в котором необходимо создать назначение

  • Subscription (необязательный)

    • Указывает подписку, в которой развернуто назначение
    • Если подписка не указана, по умолчанию используется текущий контекст подписки

  • Lock (необязательный)

    • Определяет блокировку ресурсов схемы для использования в развернутых ресурсах
    • Поддерживаемые параметры: None, AllResourcesReadOnly, AllResourcesDoNotDelete
    • Если не указаны, по умолчанию используются параметры None

  • SystemAssignedIdentity (необязательный)

    • Выберите, чтобы создать управляемое удостоверение, назначаемое системой для назначения и развертывания ресурсов
    • Значение по умолчанию для набора параметров Identity
    • Нельзя использовать с параметром UserAssignedIdentity

  • UserAssignedIdentity (необязательный)

    • Указывает назначаемое пользователем управляемое удостоверение, которое будет использоваться для назначения и развертывания ресурсов
    • Часть набора параметров Identity
    • Нельзя использовать с параметром SystemAssignedIdentity

  • Parameter (необязательный)

    • Хэш-таблица пар "ключ-значение" для настройки динамических параметров в назначении схемы

    • Значение по умолчанию динамического параметра — DefaultValue в определении

    • Если параметр не указан и не имеет значения defaultValue, он является необязательным

      Примечание

      Parameter не поддерживает secureStrings.

  • ResourceGroupParameter (необязательный)

    • Хэш-таблица артефактов группы ресурсов
    • Каждый заполнитель артефакта группы ресурсов имеет пары "ключ-значение" для динамических параметров Name и Location в этом артефакте группы ресурсов
    • Если параметр группы ресурсов не указан и не имеет значения defaultValue, он является необязательным

  • AssignmentFile (необязательный)

    • Путь к представлению JSON-файла для назначения схемы
    • Этот параметр является частью набора параметров PowerShell, в который входят только Name, Blueprint и SubscriptionId, а также общие параметры.

Пример 1. Указание параметров

В следующем примере рассматривается создание нового назначения версии 1.1 определения схемы my-blueprint, полученного при помощи Get-AzBlueprint; расположению управляемого удостоверения и объекта назначения присваивается значение westus2; блокируются ресурсы при помощи параметра AllResourcesReadOnly; задаются хэш-таблицы для параметров Parameter и ResourceGroupParameter по конкретной подписке, представленной в виде {subId}:

# Login first with Connect-AzAccount if not using Cloud Shell

# Get version '1.1' of the blueprint definition in the specified subscription
$bpDefinition = Get-AzBlueprint -SubscriptionId '{subId}' -Name 'my-blueprint' -Version '1.1'

# Create the hash table for Parameters
$bpParameters = @{storageAccount_storageAccountType='Standard_GRS'}

# Create the hash table for ResourceGroupParameters
# ResourceGroup is the resource group artifact placeholder name
$bpRGParameters = @{ResourceGroup=@{name='storage_rg';location='westus2'}}

# Create the new blueprint assignment
$bpAssignment = New-AzBlueprintAssignment -Name 'my-blueprint-assignment' -Blueprint $bpDefinition `
    -SubscriptionId '{subId}' -Location 'westus2' -Lock AllResourcesReadOnly `
    -Parameter $bpParameters -ResourceGroupParameter $bpRGParameters

Пример выходных данных, используемых для создания назначения схемы:

Name              : my-blueprint-assignment
Id                : /subscriptions/{subId}/providers/Microsoft.Blueprint/blueprintAssi
                    gnments/my-blueprint-assignment
Scope             : /subscriptions/{subId}
LastModified      : 2019-03-13
LockMode          : AllResourcesReadOnly
ProvisioningState : Creating
Parameters        : {storageAccount_storageAccountType}
ResourceGroups    : ResourceGroup

Пример 2. Использование файла определения назначения JSON

В следующем примере создается почти такое же назначение, как и в Примере 1. Вместо передачи параметров в командлет здесь показано использование файла определения назначения JSON и параметра AssignmentFile. Кроме того, свойство excludedPrincipals настраивается как часть блокировок. Отсутствует параметр PowerShell для свойства excludedPrincipals. Это свойство можно настроить только с помощью файла определения назначения JSON.

{
  "identity": {
    "type": "SystemAssigned"
  },
  "location": "westus2",
  "properties": {
    "description": "Assignment of the 101-blueprint-definition-subscription",
    "blueprintId": "/subscriptions/{subId}/providers/Microsoft.Blueprint/blueprints/101-blueprints-definition-subscription",
    "locks": {
      "mode": "AllResourcesReadOnly",
      "excludedPrincipals": [
          "7be2f100-3af5-4c15-bcb7-27ee43784a1f",
          "38833b56-194d-420b-90ce-cff578296714"
      ]
    },
    "parameters": {
      "storageAccount_storageAccountType": {
        "value": "Standard_GRS"
      }
    },
    "resourceGroups": {
      "ResourceGroup": {
        "name": "storage_rg",
        "location": "westus2"
      }
    }
  }
}

# Login first with Connect-AzAccount if not using Cloud Shell

# Create the new blueprint assignment
$bpAssignment = New-AzBlueprintAssignment -Name 'my-blueprint-assignment' -SubscriptionId '{subId}' `
    -AssignmentFile '.\assignment.json'

Пример файла определения назначения JSON для управляемого удостоверения, назначаемого пользователем, см. в тексте запроса в разделе Пример: назначение с управляемым удостоверением, назначаемым пользователем для REST API.

Обновление назначения схем

Иногда необходимо обновлять созданное назначение схемы. Командлет Set-AzBlueprintAssignment выполняет это действие. Для этого командлета нужна большая часть параметров, необходимых командлету New-AzBlueprintAssignment. Это позволяет обновить все, что было настроено в назначении. К исключениям относятся Name, Blueprint и SubscriptionId. Обновляются только указанные значения.

Сведения о том, что происходит при обновлении назначения схемы, см. в разделе Правила обновления назначений.

  • Name [обязательный]:

    • Указывает имя назначения схемы, которую нужно обновить
    • Используется для поиска назначения для обновления, а не изменения назначения

  • Blueprint [обязательный]:

    • Задает определение назначения схемы
    • используйте Get-AzBlueprint для получения объекта ссылки.
    • Используется для поиска назначения для обновления, а не изменения назначения

  • Location (необязательный)

    • Указывает область управляемого удостоверения, назначаемого системой, и объекта развертывания подписки, в котором необходимо создать назначение

  • Subscription (необязательный)

    • Указывает подписку, в которой развернуто назначение
    • Если подписка не указана, по умолчанию используется текущий контекст подписки
    • Используется для поиска назначения для обновления, а не изменения назначения

  • Lock (необязательный)

    • Определяет блокировку ресурсов схемы для использования в развернутых ресурсах
    • Поддерживаемые параметры: None, AllResourcesReadOnly, AllResourcesDoNotDelete

  • SystemAssignedIdentity (необязательный)

    • Выберите, чтобы создать управляемое удостоверение, назначаемое системой для назначения и развертывания ресурсов
    • Значение по умолчанию для набора параметров Identity
    • Нельзя использовать с параметром UserAssignedIdentity

  • UserAssignedIdentity (необязательный)

    • Указывает назначаемое пользователем управляемое удостоверение, которое будет использоваться для назначения и развертывания ресурсов
    • Часть набора параметров Identity
    • Нельзя использовать с параметром SystemAssignedIdentity

  • Parameter (необязательный)

    • Хэш-таблица пар "ключ-значение" для настройки динамических параметров в назначении схемы

    • Значение по умолчанию динамического параметра — DefaultValue в определении

    • Если параметр не указан и не имеет значения defaultValue, он является необязательным

      Примечание

      Parameter не поддерживает secureStrings.

  • ResourceGroupParameter (необязательный)

    • Хэш-таблица артефактов группы ресурсов
    • Каждый заполнитель артефакта группы ресурсов имеет пары "ключ-значение" для динамических параметров Name и Location в этом артефакте группы ресурсов
    • Если параметр группы ресурсов не указан и не имеет значения defaultValue, он является необязательным

В следующем примере представлено обновление назначения версии 1.1 определения схемы my-blueprint, полученного при помощи Get-AzBlueprint путем изменения режима блокировки:

# Login first with Connect-AzAccount if not using Cloud Shell

# Get version '1.1' of the blueprint definition in the specified subscription
$bpDefinition = Get-AzBlueprint -SubscriptionId '{subId}' -Name 'my-blueprint' -Version '1.1'

# Update the existing blueprint assignment
$bpAssignment = Set-AzBlueprintAssignment -Name 'my-blueprint-assignment' -Blueprint $bpDefinition `
    -SubscriptionId '{subId}' -Lock AllResourcesDoNotDelete

Пример выходных данных, используемых для создания назначения схемы:

Name              : my-blueprint-assignment
Id                : /subscriptions/{subId}/providers/Microsoft.Blueprint/blueprintAssi
                    gnments/my-blueprint-assignment
Scope             : /subscriptions/{subId}
LastModified      : 2019-03-13
LockMode          : AllResourcesDoNotDelete
ProvisioningState : Updating
Parameters        : {storageAccount_storageAccountType}
ResourceGroups    : ResourceGroup

Удаление назначений схем

Удаление назначения схемы выполняет командлет Remove-AzBlueprintAssignment. Этот командлет использует параметр Name или InputObject, определяющий, какое назначение схемы будет удалено. Параметр SubscriptionId является обязательным и должен быть указан в любом случае.

В следующем примере рассматривается получение существующего назначения схемы при помощи Get-AzBlueprintAssignment и его удаление из конкретной подписки, представленной {subId}.

# Login first with Connect-AzAccount if not using Cloud Shell

# Get the blueprint assignment in the specified subscription
$blueprintAssignment = Get-AzBlueprintAssignment -Name 'Assignment-lock-resource-groups'

# Remove the existing blueprint assignment
Remove-AzBlueprintAssignment -InputObject $blueprintAssignment -SubscriptionId '{subId}'

Пример кода

В следующем примере объединены все шаги: получение определения схемы, создание, обновление и удаление назначения схемы в конкретной подписке, представленной {subId}.

# Login first with Connect-AzAccount if not using Cloud Shell

#region GetBlueprint
# Get version '1.1' of the blueprint definition in the specified subscription
$bpDefinition = Get-AzBlueprint -SubscriptionId '{subId}' -Name 'my-blueprint' -Version '1.1'
#endregion

#region CreateAssignment
# Create the hash table for Parameters
$bpParameters = @{storageAccount_storageAccountType='Standard_GRS'}

# Create the hash table for ResourceGroupParameters
# ResourceGroup is the resource group artifact placeholder name
$bpRGParameters = @{ResourceGroup=@{name='storage_rg';location='westus2'}}

# Create the new blueprint assignment
$bpAssignment = New-AzBlueprintAssignment -Name 'my-blueprint-assignment' -Blueprint $bpDefinition `
    -SubscriptionId '{subId}' -Location 'westus2' -Lock AllResourcesReadOnly `
    -Parameter $bpParameters -ResourceGroupParameter $bpRGParameters
#endregion CreateAssignment

# Wait for the blueprint assignment to finish deployment prior to the next steps

#region UpdateAssignment
# Update the existing blueprint assignment
$bpAssignment = Set-AzBlueprintAssignment -Name 'my-blueprint-assignment' -Blueprint $bpDefinition `
    -SubscriptionId '{subId}' -Lock AllResourcesDoNotDelete
#endregion UpdateAssignment

# Wait for the blueprint assignment to finish deployment prior to the next steps

#region RemoveAssignment
# Remove the existing blueprint assignment
Remove-AzBlueprintAssignment -InputObject $bpAssignment -SubscriptionId '{subId}'
#endregion

Дальнейшие действия