Share via

Como gerir atribuições com o PowerShell

  • Artigo

Importante

A 11 de julho de 2026, o Blueprints (Pré-visualização) será preterido. Migre as definições e atribuições de esquemas existentes para Especificações de Modelo e Pilhas de Implementação. Os artefactos de esquema devem ser convertidos em modelos JSON do ARM ou ficheiros Bicep utilizados para definir pilhas de implementação. Para saber como criar um artefacto como um recurso do ARM, veja:

Uma atribuição de esquema pode ser gerida com o módulo Az.Blueprint Azure PowerShell. O módulo suporta a obtenção, criação, atualização e remoção de atribuições. O módulo também pode obter detalhes sobre as definições de esquema existentes. Este artigo aborda como instalar o módulo e começar a utilizá-lo.

Adicionar o módulo Az.Blueprint

Para permitir que Azure PowerShell faça a gestão de atribuições de esquemas, o módulo tem de ser adicionado. Este módulo pode ser utilizado com o PowerShell instalado localmente, com o Azure Cloud Shell ou com a imagem Azure PowerShell Docker.

Requisitos de base

O módulo Azure Blueprints requer o seguinte software:

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

Instalar o módulo

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

  1. A partir de uma linha de comandos administrativa do PowerShell, execute o seguinte comando:

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

    Nota

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

  2. Confirme que o módulo foi importado e se é a 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 esquema

O primeiro passo para trabalhar com uma atribuição é, muitas vezes, obter uma referência a uma definição de esquema. O Get-AzBlueprint cmdlet obtém uma ou mais definições de esquema. O cmdlet pode obter definições de esquema de um grupo de gestão com -ManagementGroupId {mgId} ou uma subscrição com -SubscriptionId {subId}. O parâmetro Name obtém uma definição de esquema, mas tem de ser utilizado com ManagementGroupId ou SubscriptionId. A versão pode ser utilizada com o Nome para ser mais explícita sobre que definição de esquema é devolvida. Em vez de Versão, o comutador -LatestPublished agarra a versão publicada mais recentemente.

O exemplo seguinte utiliza Get-AzBlueprint para obter todas as versões de uma definição de esquema com o nome "101-blueprints-definition-subscription" de uma subscrição 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

O resultado de exemplo de uma definição de esquema com várias versões tem o seguinte aspeto:

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 esquema na definição do esquema 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 esquema

Se a atribuição do esquema já existir, pode obter uma referência para a mesma com o Get-AzBlueprintAssignment cmdlet . O cmdlet assume SubscriptionId e Name como parâmetros opcionais. Se SubscriptionId não for especificado, é utilizado o contexto de subscrição atual.

O exemplo seguinte utiliza Get-AzBlueprintAssignment para obter uma única atribuição de esquema denominada "Assignment-lock-resource-groups" a partir de uma subscrição 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

O resultado de exemplo de uma atribuição de esquema tem o seguinte aspeto:

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 esquema

Se a atribuição do esquema ainda não existir, pode criá-la com o New-AzBlueprintAssignment cmdlet . Este cmdlet utiliza os seguintes parâmetros:

  • Nome [obrigatório]

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

  • Esquema [obrigatório]

    • Especifica a definição de esquema a atribuir
    • Utilizar Get-AzBlueprint para obter o objeto de referência

  • Localização [necessária]

    • Especifica a região para o objeto de implementação de subscrição e identidade gerida atribuída pelo sistema a ser criado no

  • Subscrição (opcional)

    • Especifica a subscrição na que a atribuição está implementada
    • Se não for fornecido, a predefinição é o contexto de subscrição atual

  • Bloquear (opcional)

    • Define o bloqueio de recursos de esquema a utilizar para recursos implementados
    • Opções suportadas: None, AllResourcesReadOnly, AllResourcesDoNotDelete
    • Se não for fornecido, a predefinição é Nenhuma

  • SystemAssignedIdentity (opcional)

    • Selecione para criar uma identidade gerida atribuída pelo sistema para a atribuição e para implementar os recursos
    • Predefinição para o conjunto de parâmetros "identity"
    • Não é possível utilizar com UserAssignedIdentity

  • UserAssignedIdentity (opcional)

    • Especifica a identidade gerida atribuída pelo utilizador a utilizar para a atribuição e para implementar os recursos
    • Parte do conjunto de parâmetros "identity"
    • Não é possível utilizar com SystemAssignedIdentity

  • Parâmetro (opcional)

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

    • A predefinição para um parâmetro dinâmico é defaultValue na definição

    • Se não for fornecido um parâmetro e não tiver valor predefinido, o parâmetro não é opcional

      Nota

      O parâmetro não suporta secureStrings.

  • ResourceGroupParameter (opcional)

    • Uma tabela hash de artefactos do grupo de recursos
    • Cada marcador de posição do artefacto do grupo de recursos tem pares chave/valor para definir dinamicamente o Nome e a Localização nesse artefacto do grupo de recursos
    • Se não for fornecido um parâmetro de grupo de recursos e não tiver valor predefinido, o parâmetro do grupo de recursos não é opcional

  • AssignmentFile (opcional)

    • O caminho para uma representação de ficheiro JSON de uma atribuição de esquema
    • Este parâmetro faz parte de um conjunto de parâmetros do PowerShell que inclui apenas Nome, Esquema e SubscriptionId, além dos parâmetros comuns.

Exemplo 1: fornecer parâmetros

O exemplo seguinte cria uma nova atribuição da versão “1.1” da definição de esquema “o-meu-esquema” obtida com Get-AzBlueprint, define a identidade gerida e a localização do objeto de atribuição como “westus2”, bloqueia os recursos com AllResourcesReadOnly e define as tabelas hash para o Parâmetro e o ResourceGroupParameter na subscrição 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

O resultado de exemplo para criar uma atribuição de esquema tem o seguinte aspeto:

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: Utilizar um ficheiro de definição de atribuição JSON

O exemplo seguinte cria quase a mesma atribuição que o Exemplo 1. Em vez de transmitir parâmetros para o cmdlet, o exemplo mostra a utilização de um ficheiro de definição de atribuição JSON e o parâmetro AssignmentFile . Além disso, a propriedade excludedPrincipals está configurada como parte de bloqueios. Não existe um parâmetro do PowerShell para excludedPrincipals e a propriedade só pode ser configurada ao defini-lo através do ficheiro 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 ficheiro de definição de atribuição JSON para uma identidade gerida atribuída pelo utilizador, veja o corpo do pedido em Exemplo: Atribuição com a identidade gerida atribuída pelo utilizador para a API REST.

Atualizar atribuições de esquema

Por vezes, é necessário atualizar uma atribuição de esquema que já tenha sido criada. O Set-AzBlueprintAssignment cmdlet processa esta ação. O cmdlet utiliza a maioria dos mesmos parâmetros que o New-AzBlueprintAssignment cmdlet, permitindo que tudo o que foi definido na atribuição seja atualizado. As exceções são o Nome, o Esquema e o SubscriptionId. Apenas os valores fornecidos são atualizados.

Para compreender o que acontece ao atualizar uma atribuição de esquema, veja regras para atualizar atribuições.

  • Nome [obrigatório]

    • Especifica o nome da atribuição do esquema a atualizar
    • Utilizado para localizar a atribuição a atualizar e não para alterar a atribuição

  • Esquema [obrigatório]

    • Especifica a definição de esquema da atribuição do esquema
    • Utilizar Get-AzBlueprint para obter o objeto de referência
    • Utilizado para localizar a atribuição a atualizar e não para alterar a atribuição

  • Localização (opcional)

    • Especifica a região para o objeto de implementação de subscrição e identidade gerida atribuída pelo sistema a ser criado no

  • Subscrição (opcional)

    • Especifica a subscrição em que a atribuição está implementada
    • Se não for fornecido, a predefinição é o contexto da subscrição atual
    • Utilizado para localizar a atribuição a atualizar e não para alterar a atribuição

  • Bloquear (opcional)

  • SystemAssignedIdentity (opcional)

    • Selecione para criar uma identidade gerida atribuída pelo sistema para a atribuição e para implementar os recursos
    • Predefinição do conjunto de parâmetros "identity"
    • Não é possível utilizar com UserAssignedIdentity

  • UserAssignedIdentity (opcional)

    • Especifica a identidade gerida atribuída pelo utilizador a utilizar para a atribuição e para implementar os recursos
    • Parte do conjunto de parâmetros "identity"
    • Não é possível utilizar com SystemAssignedIdentity

  • Parâmetro (opcional)

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

    • A predefinição para um parâmetro dinâmico é o valor predefinido na definição

    • Se não for fornecido um parâmetro e não tiver valor predefinido, o parâmetro não é opcional

      Nota

      O parâmetro não suporta secureStrings.

  • ResourceGroupParameter (opcional)

    • Uma tabela hash de artefactos do grupo de recursos
    • Cada marcador de posição do artefacto do grupo de recursos tem pares chave/valor para definir dinamicamente Nome e Localização nesse artefacto do grupo de recursos
    • Se não for fornecido um parâmetro de grupo de recursos e não tiver valor predefinido, o parâmetro do grupo de recursos não é opcional

O exemplo seguinte atualiza a atribuição da versão "1.1" da definição do esquema "my-blueprint" obtida 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

O resultado de exemplo para criar uma atribuição de esquema tem o seguinte aspeto:

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 esquemas

Quando for altura de remover uma atribuição de esquema, o Remove-AzBlueprintAssignment cmdlet processa esta ação. O cmdlet utiliza Name ou InputObject para especificar que atribuição de esquema remover. O SubscriptionId é necessário e tem de ser fornecido em todos os casos.

O exemplo seguinte obtém uma atribuição de esquema existente com Get-AzBlueprintAssignment e, em seguida, remove-a da subscrição 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

Ao reunir todos os passos, o exemplo seguinte obtém a definição do esquema, cria, atualiza e remove uma atribuição de esquema na subscrição 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

Passos seguintes