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

Статья
09/07/2023

Важно!

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.

Запустите следующие команды из командной строки PowerShell с правами администратора.
```
# Install the Azure Blueprints module from PowerShell Gallery
Install-Module -Name Az.Blueprint
```
Примечание

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

Убедитесь, что модуль импортирован и имеет требуемую версию (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

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

Ознакомьтесь со сведениями о жизненном цикле схем.
Узнайте, как использовать статические и динамические параметры.
Научитесь настраивать последовательность схемы.
Узнайте, как применять блокировку ресурсов схемы.
Устраняйте проблемы, возникающие во время назначения схемы, с помощью общих инструкций по устранению неполадок.

Поделиться через