Como gerenciar atribuições com o PowerShell

  • Artigo

Importante

Em 11 de julho de 2026, o Blueprints (versão prévia) será preterido. Migre suas definições e atribuições de blueprint existentes para Especificações de Modelo e Pilhas de Implantação. Os artefatos de blueprint devem ser convertidos em modelos JSON do ARM ou arquivos Bicep usados para definir pilhas de implantação. Para saber como criar um artefato como um recurso do ARM, confira:

Uma atribuição de blueprint pode ser gerenciada usando o módulo Az.Blueprint do Azure PowerShell. O módulo dá suporte à busca, criação, atualização e remoção de atribuições. O módulo também pode buscar detalhes sobre as definições de blueprints existentes. Este artigo aborda como instalar o módulo e começar a usá-lo.

Adicionar o módulo Az.Blueprint

Para habilitar o Azure PowerShell para gerenciar as atribuições de blueprint, o módulo precisa ser adicionado. Esse módulo pode ser usado com o PowerShell instalado localmente, com o Azure Cloud Shell ou com a imagem do Docker do Azure PowerShell.

Requisitos base

O módulo do Azure Blueprints requer o seguinte software:

  • Azure PowerShell 1.5.0 ou superior. Se ainda não estiver instalado, siga estas instruções.
  • PowerShellGet 2.0.1 ou superior. Se ele não estiver instalado ou atualizado, siga estas instruções.

Instalar o módulo

O módulo do Azure Blueprints para PowerShell é Az.Blueprint.

  1. De um prompt administrativo do PowerShell, execute o comando a seguir:

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

    Observação

    Se o Az.Accounts já estiver instalado, pode ser necessário usar -AllowClobber para forçar a instalação.

  2. Confirme se o módulo foi importado e é da versão correta (0.2.6):

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

Obter definições de blueprint

A primeira etapa para trabalhar com uma atribuição é geralmente obter uma referência a uma definição de blueprint. O cmdlet Get-AzBlueprint obtém uma ou mais definições de blueprint. O cmdlet pode obter definições de blueprint de um grupo de gerenciamento com -ManagementGroupId {mgId} ou uma assinatura com -SubscriptionId {subId}. O parâmetro Nome obtém uma definição de blueprint, mas deve ser usado com ManagementGroupId ou SubscriptionId. A Versão pode ser usada com o Nome para explicitar qual definição de blueprint é retornada. Em vez de Versão, a opção -LatestPublished captura a versão publicada mais recentemente.

O exemplo a seguir usa Get-AzBlueprint para obter todas as versões de uma definição de blueprint denominada '101-Blueprints-Definition-Subscription ' de uma assinatura específica representada como {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

A saída de exemplo para uma definição de blueprint com várias versões é semelhante a esta:

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

Os parâmetros de blueprint na definição de blueprint podem ser expandidos para fornecer mais informações.

$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

Obter atribuições de blueprint

Se a atribuição de blueprint já existir, você poderá obter uma referência a ela com o cmdlet Get-AzBlueprintAssignment. O cmdlet usa SubscriptionId e Nome como parâmetros opcionais. Se SubscriptionId não for especificado, o contexto de assinatura atual será usado.

O exemplo a seguir usa Get-AzBlueprintAssignment para obter uma única atribuição de blueprint chamada 'Assignment-Lock-Resource-Groups' de uma assinatura específica representada como {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

A saída de exemplo de uma atribuição de blueprint tem esta aparência:

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

Criar atribuições de blueprint

Se a atribuição de blueprint ainda não existir, você poderá criá-la com o cmdlet New-AzBlueprintAssignment. Esse cmdlet usa os seguintes parâmetros:

  • Nome [obrigatório]

    • Especifica o nome da atribuição de blueprint
    • Deve ser exclusivo e ainda não existir no SubscriptionId

  • Blueprint [obrigatório]

    • Especifica a definição de blueprint a ser atribuída
    • Use Get-AzBlueprint para obter o objeto de referência

  • Local [obrigatório]

    • Especifique uma região na qual criar a identidade gerenciada atribuída pelo sistema e o objeto de implantação de assinatura

  • Assinatura (opcional)

    • Especifica a assinatura na qual a atribuição é implantada
    • Se não for fornecido, o padrão será o contexto da assinatura atual

  • Bloqueio (opcional)

    • Define o bloqueio de recursos do blueprint a ser usado para recursos implantados
    • Opções com suporte: Nenhum, AllResourcesReadOnly, AllResourcesDoNotDelete
    • Se não for fornecido, o padrão será Nenhum

  • SystemAssignedIdentity (opcional)

    • Selecione para criar uma identidade gerenciada atribuída pelo sistema para a atribuição e para implantar os recursos
    • Padrão para o conjunto de parâmetros "Identity"
    • Não pode ser usado com UserAssignedIdentity

  • UserAssignedIdentity (opcional)

    • Especifica a identidade gerenciada atribuída pelo usuário a ser usada para a atribuição e para implantar os recursos
    • Parte do conjunto de parâmetros "Identity"
    • Não pode ser usado com SystemAssignedIdentity

  • Parâmetro (opcional)

    • Uma tabela de hash de pares chave/valor para definir parâmetros dinâmicos na atribuição de blueprint

    • O padrão para um parâmetro dinâmico é o defaultValue na definição

    • Se um parâmetro não for fornecido e não tiver defaultValue, o parâmetro não será opcional

      Observação

      O parâmetro não dá suporte a secureStrings.

  • ResourceGroupParameter (optional)

    • Uma tabela de hash de artefatos do grupo de recursos
    • Cada espaço reservado do artefato do grupo de recursos tem pares de chave/valor para configurar dinamicamente o Nome e o Local nesse artefato do grupo de recursos
    • Se um parâmetro do grupo de recursos não for fornecido e não tiver defaultValue, o parâmetro de grupo de recursos não será opcional

  • AssignmentFile (opcional)

    • O caminho para uma representação de arquivo JSON de uma atribuição de blueprint
    • Esse parâmetro faz parte de um conjunto de parâmetros do PowerShell que inclui apenas Nome, Blueprinte SubscriptionId, além dos parâmetros comuns.

Exemplo 1: Fornecer parâmetros

O exemplo a seguir cria uma nova atribuição da versão '1.1' da definição de blueprint 'my-blueprint' buscada com Get-AzBlueprint, define a identidade gerenciada e o local do objeto de atribuição como 'westus2', bloqueia os recursos com AllResourcesReadOnlye define as tabelas de hash para Parâmetro e ResourceGroupParameter na assinatura específica representada como {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

A saída de exemplo parar criar uma atribuição de blueprint tem esta aparência:

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

Exemplo 2: Usar um arquivo de definição de atribuição JSON

O exemplo a seguir cria quase a mesma atribuição que o Exemplo 1. Em vez de passar parâmetros para o cmdlet, o exemplo mostra o uso de um arquivo de definição de atribuição JSON e o parâmetro AssignmentFile. Além disso, a propriedade excludedPrincipals é configurada como parte dos bloqueios. Não há um parâmetro do PowerShell para excludedPrincipals e a propriedade só pode ser definida pela configuração por meio do arquivo de definição de atribuição 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'

Para obter um exemplo do arquivo de definição de atribuição JSON para uma identidade gerenciada atribuída pelo usuário, consulte o corpo da solicitação em Exemplo: Atribuição com identidade gerenciada atribuída pelo usuário para a API REST.

Atualizar atribuições de blueprint

Às vezes, é necessário atualizar uma atribuição de blueprint que já foi criada. O cmdlet Set-AzBlueprintAssignment lida com essa ação. O cmdlet usa a maioria dos mesmos parâmetros que o cmdlet New-AzBlueprintAssignment, permitindo que qualquer coisa que tenha sido definida na atribuição seja atualizada. As exceções são o Nome, o Blueprinte a SubscriptionId. Somente os valores fornecidos são atualizados.

Para entender o que acontece ao atualizar uma atribuição de blueprint, consulte regras para atualizar atribuições.

  • Nome [obrigatório]

    • Especifica o nome da atribuição de blueprint para atualizar
    • Usado para localizar a atribuição a ser atualizada, não para alterar a atribuição

  • Blueprint [obrigatório]

    • Especifica a definição de blueprint da atribuição de blueprint
    • Use Get-AzBlueprint para obter o objeto de referência
    • Usado para localizar a atribuição a ser atualizada, não para alterar a atribuição

  • Local(opcional)

    • Especifique uma região na qual criar a identidade gerenciada atribuída pelo sistema e o objeto de implantação de assinatura

  • Assinatura (opcional)

    • Especifica a assinatura na qual a atribuição é implantada
    • Se não for fornecido, o padrão será o contexto da assinatura atual
    • Usado para localizar a atribuição a ser atualizada, não para alterar a atribuição

  • Bloqueio (opcional)

  • SystemAssignedIdentity (opcional)

    • Selecione para criar uma identidade gerenciada atribuída pelo sistema para a atribuição e para implantar os recursos
    • Padrão para o conjunto de parâmetros "Identity"
    • Não pode ser usado com UserAssignedIdentity

  • UserAssignedIdentity (opcional)

    • Especifica a identidade gerenciada atribuída pelo usuário a ser usada para a atribuição e para implantar os recursos
    • Parte do conjunto de parâmetros "Identity"
    • Não pode ser usado com SystemAssignedIdentity

  • Parâmetro (opcional)

    • Uma tabela de hash de pares chave/valor para definir parâmetros dinâmicos na atribuição de blueprint

    • O padrão para um parâmetro dinâmico é o defaultValue na definição

    • Se um parâmetro não for fornecido e não tiver defaultValue, o parâmetro não será opcional

      Observação

      O parâmetro não dá suporte a secureStrings.

  • ResourceGroupParameter (optional)

    • Uma tabela de hash de artefatos do grupo de recursos
    • Cada espaço reservado do artefato do grupo de recursos tem pares de chave/valor para configurar dinamicamente o Nome e o Local nesse artefato do grupo de recursos
    • Se um parâmetro do grupo de recursos não for fornecido e não tiver defaultValue, o parâmetro de grupo de recursos não será opcional

O exemplo a seguir atualiza a atribuição da versão '1.1' da definição de blueprint 'my-blueprint ' buscada com Get-AzBlueprint alterando o modo de bloqueio:

# 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

A saída de exemplo parar criar uma atribuição de blueprint tem esta aparência:

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

Remover atribuições de blueprint

Quando é o momento de uma atribuição de blueprint ser removida, o cmdlet Remove-AzBlueprintAssignment lida com essa ação. O cmdlet usa Nome ou InputObject para especificar qual atribuição de blueprint deve ser removida. SubscriptionId é necessário e deve ser fornecido em todos os casos.

O exemplo a seguir busca uma atribuição de blueprint existente com Get-AzBlueprintAssignment e, em seguida, a remove da assinatura específica representada como {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}'

Exemplo de código

Reunindo todas as etapas, o exemplo a seguir obtém a definição de blueprint, depois cria, atualiza e remove uma atribuição de blueprint na assinatura específica representada como {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

Próximas etapas