Guia de início rápido: definir e atribuir um plano do Azure com o PowerShell

Artigo
03/10/2024

Importante

Em 11 de julho de 2026, os Blueprints (Preview) serão preteridos. Migre suas definições e atribuições de blueprint existentes para Especificações de modelo e Pilhas de implantação. Os artefatos do Blueprint devem ser convertidos em modelos JSON ARM ou arquivos Bicep usados para definir pilhas de implantação. Para saber como criar um artefato como um recurso ARM, consulte:

Neste tutorial, você aprenderá a usar o Azure Blueprints para executar algumas das tarefas comuns relacionadas à criação, publicação e atribuição de um plano em sua organização. Essa habilidade ajuda você a definir padrões comuns para desenvolver configurações reutilizáveis e rapidamente implantáveis, com base em modelos, políticas e segurança do Azure Resource Manager (ARM).

Pré-requisitos

Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.
Se ainda não estiver instalado, siga as instruções em Adicionar o módulo Az.Blueprint para instalar e validar o módulo Az.Blueprint da Galeria do PowerShell.
Se você não tiver usado o Azure Blueprints antes, registre o provedor de recursos por meio do Azure PowerShell com Register-AzResourceProvider -ProviderNamespace Microsoft.Blueprint.

Azure Cloud Shell

O Azure aloja o Azure Cloud Shell, um ambiente de shell interativo que pode utilizar através do seu browser. Pode utilizar o Bash ou o PowerShell com o Cloud Shell para trabalhar com os serviços do Azure. Você pode usar os comandos pré-instalados do Cloud Shell para executar o código neste artigo, sem precisar instalar nada em seu ambiente local.

Para iniciar o Azure Cloud Shell:

Opção	Exemplo/Ligação
Selecione Experimentar no canto superior direito de um código ou bloco de comandos. Selecionar Experimentar não copia automaticamente o código ou comando para o Cloud Shell.
Aceda a https://shell.azure.com ou selecione o botão Iniciar Cloud Shell para abrir o Cloud Shell no browser.
Selecione o botão Cloud Shell na barra de menus, na parte direita do portal do Azure.

Para usar o Azure Cloud Shell:

Inicie o Cloud Shell.
Selecione o botão Copiar em um bloco de código (ou bloco de comando) para copiar o código ou comando.
Cole o código ou comando na sessão do Cloud Shell selecionando Ctrl+Shift+V no Windows e Linux ou selecionando Cmd+Shift+V no macOS.
Selecione Enter para executar o código ou comando.

Criar um esquema

O primeiro passo na definição de um padrão de conformidade é compor um esquema a partir dos recursos disponíveis. Vamos criar um plano chamado MyBlueprint para configurar atribuições de função e política para a assinatura. Em seguida, você adiciona um grupo de recursos, um modelo ARM e uma atribuição de função no grupo de recursos.

Nota

Quando você estiver usando o PowerShell, o objeto blueprint é criado primeiro. Para cada artefato a ser adicionado que tenha parâmetros, você define os parâmetros com antecedência no esquema inicial.

Crie o objeto esquema inicial. O BlueprintFile parâmetro usa um arquivo JSON que inclui propriedades sobre o blueprint, quaisquer grupos de recursos a serem criados e todos os parâmetros de nível de blueprint. Você define os parâmetros durante a atribuição e eles são usados pelos artefatos adicionados em etapas posteriores.

Arquivo JSON - blueprint.json

{
    "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",
                "defaultValue": "Standard_LRS",
                "allowedValues": [
                    "Standard_LRS",
                    "Standard_GRS",
                    "Standard_ZRS",
                    "Premium_LRS"
                ],
                "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",
                    "strongType": "PrincipalId"
                }
            },
            "owners": {
                "type": "array",
                "metadata": {
                    "description": "List of AAD object IDs that is assigned Owner role at the resource group",
                    "strongType": "PrincipalId"
                }
            }
        },
        "resourceGroups": {
            "storageRG": {
                "description": "Contains the resource template deployment and a role assignment."
            }
        }
    }
}

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

# Get a reference to the new blueprint object, we'll use it in subsequent steps
$blueprint = New-AzBlueprint -Name 'MyBlueprint' -BlueprintFile .\blueprint.json
```
Nota

Use o nome do arquivo blueprint.json ao criar suas definições de blueprint programaticamente. Esse nome de arquivo é usado quando você chama Import-AzBlueprintWithArtifacto .

O objeto blueprint é criado na assinatura padrão por padrão. Para especificar o grupo de gerenciamento, use o parâmetro ManagementGroupId. Para especificar a assinatura, use o parâmetro SubscriptionId.

Adicione uma atribuição de função na assinatura. O ArtifactFile define o tipo de artefato, as propriedades se alinham ao identificador de definição de função e as identidades principais são passadas como uma matriz de valores. No exemplo a seguir, as identidades principais concedidas à função especificada são configuradas para um parâmetro que é definido durante a atribuição do blueprint. Este exemplo usa a Contributor função interna, com um GUID de b24988ac-6180-42a0-ab88-20f7382dd24c.
- Arquivo JSON - \artifacts\roleContributor.json
```
{
    "kind": "roleAssignment",
    "properties": {
        "roleDefinitionId": "/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c",
        "principalIds": "[parameters('contributors')]"
    }
}
```
- Comando PowerShell
```
# Use the reference to the new blueprint object from the previous steps
New-AzBlueprintArtifact -Blueprint $blueprint -Name 'roleContributor' -ArtifactFile .\artifacts\roleContributor.json
```

Adicione uma atribuição de política na assinatura. O ArtifactFile define o tipo de artefato, as propriedades se alinham a uma definição de política ou iniciativa e a atribuição de política é configurada para usar os parâmetros de blueprint definidos durante a atribuição de blueprint. Este exemplo usa a Apply tag and its default value to resource groups política interna, com um GUID de 49c88fc8-6fd1-46fd-a676-f12d1d3a4c71.

Arquivo JSON - \artifacts\policyTags.json

{
    "kind": "policyAssignment",
    "properties": {
        "displayName": "Apply tag and its default value to resource groups",
        "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')]"
            }
        }
    }
}

Comando PowerShell

# Use the reference to the new blueprint object from the previous steps
New-AzBlueprintArtifact -Blueprint $blueprint -Name 'policyTags' -ArtifactFile .\artifacts\policyTags.json

Adicione outra atribuição de política para a marca de armazenamento (reutilizando storageAccountType_ parameter) na assinatura. Este artefacto de atribuição de política adicional demonstra que um parâmetro definido no esquema é utilizável por mais do que um artefacto. No exemplo, você usa o storageAccountType para definir uma marca no grupo de recursos. Esse valor fornece informações sobre a conta de armazenamento que você cria na próxima etapa. Este exemplo usa a Apply tag and its default value to resource groups política interna, com um GUID de 49c88fc8-6fd1-46fd-a676-f12d1d3a4c71.

Arquivo JSON - \artifacts\policyStorageTags.json

{
    "kind": "policyAssignment",
    "properties": {
        "displayName": "Apply storage tag to resource group",
        "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')]"
            }
        }
    }
}

Comando PowerShell

# Use the reference to the new blueprint object from the previous steps
New-AzBlueprintArtifact -Blueprint $blueprint -Name 'policyStorageTags' -ArtifactFile .\artifacts\policyStorageTags.json

Adicione um modelo no grupo de recursos. O TemplateFile para um modelo ARM inclui o componente JSON normal do modelo. O modelo também reutiliza os storageAccountTypeparâmetros , tagNamee tagValue blueprint passando cada um para o modelo. Os parâmetros do blueprint estão disponíveis para o modelo usando o parâmetro TemplateParameterFile, e dentro do modelo JSON esse par chave-valor é usado para injetar o valor. Os nomes dos parâmetros blueprint e template podem ser os mesmos.

Arquivo de modelo JSON ARM - \artifacts\templateStorage.json

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "storageAccountTypeFromBP": {
            "type": "string",
            "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": "[resourceGroup().location]",
        "sku": {
            "name": "[parameters('storageAccountTypeFromBP')]"
        },
        "kind": "Storage",
        "properties": {}
    }],
    "outputs": {
        "storageAccountSku": {
            "type": "string",
            "value": "[variables('storageAccountName')]"
        }
    }
}

Arquivo de parâmetro de modelo JSON ARM - \artifacts\templateStorageParams.json

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "storageAccountTypeFromBP": {
            "value": "[parameters('storageAccountType')]"
        },
        "tagNameFromBP": {
            "value": "[parameters('tagName')]"
        },
        "tagValueFromBP": {
            "value": "[parameters('tagValue')]"
        }
    }
}

Comando PowerShell

# Use the reference to the new blueprint object from the previous steps
New-AzBlueprintArtifact -Blueprint $blueprint -Type TemplateArtifact -Name 'templateStorage' -TemplateFile .\artifacts\templateStorage.json -TemplateParameterFile .\artifacts\templateStorageParams.json -ResourceGroupName storageRG

Adicione uma atribuição de função no grupo de recursos. Semelhante à entrada de atribuição de função anterior, o exemplo a seguir usa o identificador de definição para a Owner função e fornece um parâmetro diferente do blueprint. Este exemplo usa a Owner função interna, com um GUID de 8e3af657-a8ff-443c-a75c-2fe8c4bcb635.

Arquivo JSON - \artifacts\roleOwner.json

{
    "kind": "roleAssignment",
    "properties": {
        "resourceGroup": "storageRG",
        "roleDefinitionId": "/providers/Microsoft.Authorization/roleDefinitions/8e3af657-a8ff-443c-a75c-2fe8c4bcb635",
        "principalIds": "[parameters('owners')]"
    }
}

Comando PowerShell

# Use the reference to the new blueprint object from the previous steps
New-AzBlueprintArtifact -Blueprint $blueprint -Name 'roleOwner' -ArtifactFile .\artifacts\roleOwner.json

Publicar um esquema

Agora que você adicionou os artefatos ao projeto, é hora de publicá-lo. A publicação disponibiliza o esquema para atribuição a uma assinatura.

# Use the reference to the new blueprint object from the previous steps
Publish-AzBlueprint -Blueprint $blueprint -Version '{BlueprintVersion}'

O valor para {BlueprintVersion} é uma sequência de letras, números e hífenes (sem espaços ou outros caracteres especiais). O comprimento máximo é de 20 carateres. Use algo único e informativo, como v20180622-135541.

Atribuir um esquema

Depois de publicar um esquema usando o PowerShell, ele pode ser atribuído a uma assinatura. Atribua o esquema que você criou a uma das assinaturas na hierarquia do grupo de gerenciamento. Se o esquema for salvo em uma assinatura, ele só poderá ser atribuído a essa assinatura. O Blueprint parâmetro especifica o esquema a ser atribuído. Para fornecer os nameparâmetros , location, identity, lock, e , use blueprint os parâmetros correspondentes do New-AzBlueprintAssignment PowerShell no cmdlet ou forneça-os no arquivo JSON de AssignmentFile parâmetro.

Execute a implementação do esquema, atribuindo-o a uma subscrição. Como os contributors parâmetros e owners exigem que uma matriz dos principais receba a atribuição de função, use a API do Azure Ative Directory Graph para coletar o objectIds para uso no AssignmentFile para seus próprios usuários, grupos ou entidades de objectIds serviço.

Arquivo JSON - blueprintAssignment.json

{
    "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"
}

Comando PowerShell

# Use the reference to the new blueprint object from the previous steps
New-AzBlueprintAssignment -Blueprint $blueprint -Name 'assignMyBlueprint' -AssignmentFile .\blueprintAssignment.json

Identidade gerida atribuída pelo utilizador

Uma atribuição de blueprint também pode usar uma identidade gerenciada atribuída pelo usuário. Nesse caso, a identity parte do arquivo de atribuição JSON é alterada da seguinte maneira. Substitua {tenantId}, {subscriptionId}, {yourRG}e {userIdentity} pelo ID do locatário, ID da assinatura, nome do grupo de recursos e nome da identidade gerenciada atribuída pelo usuário, respectivamente.
```
"identity": {
    "type": "userAssigned",
    "tenantId": "{tenantId}",
    "userAssignedIdentities": {
        "/subscriptions/{subscriptionId}/resourceGroups/{yourRG}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{userIdentity}": {}
    }
},
```
A identidade gerenciada atribuída pelo usuário pode estar em qualquer assinatura e grupo de recursos ao qual o usuário que atribui o blueprint tenha permissões.

Importante

O Azure Blueprints não gerencia a identidade gerenciada atribuída pelo usuário. Os usuários são responsáveis por atribuir funções e permissões suficientes, ou a atribuição do blueprint falhará.

Clean up resources (Limpar recursos)

Pode remover um esquema de uma subscrição. A remoção é, muitas vezes, feita quando os recursos de artefacto já não são precisos. Quando um esquema é removido, os artefactos atribuídos como parte desse esquema são deixados para trás. Para remover uma atribuição de blueprint, use o Remove-AzBlueprintAssignment cmdlet:

atribuirMyBlueprint

Remove-AzBlueprintAssignment -Name 'assignMyBlueprint'

Próximos passos

Neste início rápido, você criou, atribuiu e removeu um esquema com o PowerShell. Para saber mais sobre os Blueprints do Azure, continue para o artigo do ciclo de vida do blueprint.

Saiba mais sobre o ciclo de vida do blueprint

Guia de início rápido: definir e atribuir um plano do Azure com o PowerShell

Pré-requisitos

Azure Cloud Shell

Criar um esquema

Publicar um esquema

Atribuir um esquema

Clean up resources (Limpar recursos)

Próximos passos

Recursos adicionais