Início Rápido: Definir e atribuir um plano gráfico do Azure com a CLI do Azure

Importante

Azure Blueprints (versão prévia) será desativada em 31 de janeiro de 2027, com uma aposentadoria em fases a partir de 31 de julho de 2026. Migre suas definições e atribuições de blueprints existentes para Deployment Stacks (recomendado) e Template Specs. Artefatos de blueprint são convertidos em modelos ARM JSON ou arquivos Bicep usados para definir pilhas de implantação. Para obter o cronograma completo das fases, o impacto e as perguntas frequentes, consulte desativação do Azure Blueprints ou https://aka.ms/AzureBlueprintsRetirement. Para saber como criar um artefato como um recurso do ARM, confira:

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 blueprint dentro de sua organização. Essa habilidade ajuda você a definir padrões comuns para desenvolver configurações reutilizáveis e implantáveis rapidamente, com base em modelos do ARM (Azure Resource Manager), política e segurança.

Pré-requisitos

Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.
Se você ainda não usou o Azure Blueprints, registre o provedor de recursos por meio da CLI do Azure com az provider register --namespace Microsoft.Blueprint.

Azure Cloud Shell

O Azure hospeda o Azure Cloud Shell, um ambiente de shell interativo que pode ser usado por meio do navegador. É possível usar o bash ou o PowerShell com o Cloud Shell para trabalhar com os serviços do Azure. É possível usar os comandos pré-instalados do Cloud Shell para executar o código neste artigo, sem precisar instalar nada no seu ambiente local.

Para iniciar o Azure Cloud Shell:

Opção	Exemplo/Link
Selecione Experimentar no canto superior direito de um bloco de código ou de comando. Selecionar Experimentar não copia automaticamente o código nem o comando para o Cloud Shell.
Acesse https://shell.azure.com ou selecione o botão Iniciar o Cloud Shell para abri-lo no navegador.
Selecione o botão Cloud Shell na barra de menus no canto superior direito 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 o comando.
Cole o código ou comando na sessão do Cloud Shell selecionando Ctrl+Shift+V no Windows e no Linux, ou selecionando Cmd+Shift+V no macOS.
Selecione Enter para executar o código ou o comando.

Adicionar a extensão de plano

Para permitir que a CLI do Azure gerencie definições e atribuições de blueprint, você precisa adicionar a extensão. Essa extensão funcionará sempre que você poderá usar a CLI do Azure. Isso inclui o Bash no Windows 10, o Cloud Shell (a versão autônoma e a do portal), a imagem do Docker na CLI do Azure ou uma extensão instalada localmente.

Verifique se a CLI do Azure mais recente está instalada (pelo menos a versão 2.0.76). Se ainda não estiver instalado, siga estas instruções.

No seu ambiente da CLI do Azure preferido, importe a extensão com o seguinte comando:

# Add the Blueprint extension to the Azure CLI environment
az extension add --name blueprint

Verifique se a extensão foi instalada e se é a versão esperada (0.1.0 ou posterior):

# Check the extension list (note that you might have other extensions installed)
az extension list

# Run help for extension options
az blueprint -h

Criar um plano gráfico

A primeira etapa na definição de um modelo padrão para conformidade é compor um blueprint a partir dos recursos disponíveis. Vamos criar um blueprint chamado MyBlueprint para configurar as atribuições de funções e políticas para a assinatura. Em seguida, você adicionará um grupo de recursos, um modelo do ARM e uma atribuição de função no grupo de recursos.

Observação

Quando você usa a CLI do Azure, o objeto blueprint é criado primeiro. Para cada artefato com parâmetros a ser adicionado, defina os parâmetros com antecedência no blueprint inicial.

Crie o objeto blueprint original. O parâmetro parameters usa um arquivo JSON que inclui todos os parâmetros do blueprint. Defina os parâmetros durante a atribuição e eles serão usados pelos artefatos que você adicionar em etapas posteriores.

Arquivo JSON – blueprintparms.json

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

Comando da CLI do Azure
```
# Login first with az login if not using Cloud Shell

# Create the blueprint object
az blueprint create \
   --name 'MyBlueprint' \
   --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.' \
   --parameters blueprintparms.json
```
Observação

Use o nome de arquivo blueprint.json ao importar as definições de blueprint. Esse nome de arquivo é usado quando você chama az blueprint import.

Por padrão, o objeto blueprint é criado na assinatura padrão. Para especificar o grupo de gerenciamento, use o parâmetro managementgroup. Para especificar a assinatura, use o parâmetro subscription.

Adicione o grupo de recursos dos artefatos de armazenamento à definição.

az blueprint resource-group add \
   --blueprint-name 'MyBlueprint' \
   --artifact-name 'storageRG' \
   --description 'Contains the resource template deployment and a role assignment.'

Adicione uma atribuição de função na assinatura. No exemplo a seguir, as identidades às quais foi atribuída a função especificada são configuradas em um parâmetro definido durante a atribuição do blueprint. Este exemplo usa a função interna Contributor com o GUID b24988ac-6180-42a0-ab88-20f7382dd24c.
```
az blueprint artifact role create \
   --blueprint-name 'MyBlueprint' \
   --artifact-name 'roleContributor' \
   --role-definition-id '/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c' \
   --principal-ids "[parameters('contributors')]"
```

Adicione uma atribuição de política na assinatura. Este exemplo usa a política interna Apply tag and its default value to resource groups com o GUID 49c88fc8-6fd1-46fd-a676-f12d1d3a4c71.

Arquivo JSON – artifacts\policyTags.json

{
   "tagName": {
      "value": "[parameters('tagName')]"
   },
   "tagValue": {
      "value": "[parameters('tagValue')]"
   }
}

Comando da CLI do Azure

az blueprint artifact policy create \
   --blueprint-name 'MyBlueprint' \
   --artifact-name 'policyTags' \
   --policy-definition-id '/providers/Microsoft.Authorization/policyDefinitions/49c88fc8-6fd1-46fd-a676-f12d1d3a4c71' \
   --display-name 'Apply tag and its default value to resource groups' \
   --description 'Apply tag and its default value to resource groups' \
   --parameters artifacts\policyTags.json

Observação

Ao usar az blueprint em um Mac, substitua \ por / nos valores de parâmetro que incluem o caminho. Nesse caso, o valor de parameters passa a ser artifacts/policyTags.json.

Adicione outra atribuição de política para a tag de armazenamento (reutilizando storageAccountType_ parameter) na assinatura. Este artefato de atribuição de política adicional demonstra que um parâmetro definido no blueprint pode ser usado por mais de um artefato. No exemplo, você usará o storageAccountType para definir uma marca no grupo de recursos. Esse valor fornece informações sobre a conta de armazenamento que será criada na próxima etapa. Este exemplo usa a política interna Apply tag and its default value to resource groups com o GUID 49c88fc8-6fd1-46fd-a676-f12d1d3a4c71.
- Arquivo JSON – artifacts\policyStorageTags.json
```
{
   "tagName": {
      "value": "StorageType"
   },
   "tagValue": {
      "value": "[parameters('storageAccountType')]"
   }
}
```
- Comando da CLI do Azure
```
az blueprint artifact policy create \
   --blueprint-name 'MyBlueprint' \
   --artifact-name 'policyStorageTags' \
   --policy-definition-id '/providers/Microsoft.Authorization/policyDefinitions/49c88fc8-6fd1-46fd-a676-f12d1d3a4c71' \
   --display-name 'Apply storage tag to resource group' \
   --description 'Apply storage tag and the parameter also used by the template to resource groups' \
   --parameters artifacts\policyStorageTags.json
```
  Observação
  
  Ao usar az blueprint em um Mac, substitua \ por / nos valores de parâmetro que incluem o caminho. Nesse caso, o valor de parameters passa a ser artifacts/policyStorageTags.json.

Adicione um modelo no grupo de recursos. O parâmetro template de um modelo do ARM inclui os componentes normais JSON do modelo. O modelo também reutiliza os parâmetros storageAccountType, tagName e tagValue do blueprint transmitindo cada um para o modelo. Os parâmetros do blueprint são disponibilizados ao modelo usando o parâmetro parameters e, dentro do JSON do modelo, o par chave-valor é usado para injetar o valor. Os nomes dos parâmetros de blueprint e de modelo podem ser iguais.

Arquivo de modelo do ARM JSON – 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âmetros do modelo ARM JSON - artifacts\templateStorageParams.json

{
   "storageAccountTypeFromBP": {
      "value": "[parameters('storageAccountType')]"
   },
   "tagNameFromBP": {
      "value": "[parameters('tagName')]"
   },
   "tagValueFromBP": {
      "value": "[parameters('tagValue')]"
   }
}

Comando da CLI do Azure
```
az blueprint artifact template create \
   --blueprint-name 'MyBlueprint' \
   --artifact-name 'templateStorage' \
   --template artifacts\templateStorage.json \
   --parameters artifacts\templateStorageParams.json \
   --resource-group-art 'storageRG'
```
Observação

Ao usar az blueprint em um Mac, substitua \ por / nos valores de parâmetro que incluem o caminho. Nesse caso, o valor de template passa a ser artifacts/templateStorage.json, e parameters passa a ser artifacts/templateStorageParams.json.

Adicione uma atribuição de função no grupo de recursos. De modo semelhante à entrada de atribuição de função anterior, o exemplo a seguir usa o identificador de definição da função Owner e fornece a ela um parâmetro diferente do blueprint. Este exemplo usa a função interna Owner com o GUID 8e3af657-a8ff-443c-a75c-2fe8c4bcb635.
```
az blueprint artifact role create \
   --blueprint-name 'MyBlueprint' \
   --artifact-name 'roleOwner' \
   --role-definition-id '/providers/Microsoft.Authorization/roleDefinitions/8e3af657-a8ff-443c-a75c-2fe8c4bcb635' \
   --principal-ids "[parameters('owners')]" \
   --resource-group-art 'storageRG'
```

Publicar um modelo

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

az blueprint publish --blueprint-name 'MyBlueprint' --version '{BlueprintVersion}'

O valor de {BlueprintVersion} é uma cadeia de caracteres de letras, números e hifens (sem espaços nem outros caracteres especiais). O tamanho máximo é de 20 caracteres. Use algo exclusivo e informativo, como v20200605-135541.

Atribuir um modelo

Depois que um blueprint é publicado por meio da CLI do Azure, ele pode ser atribuído a uma assinatura. Atribua o blueprint que você criou a uma das assinaturas em sua hierarquia do grupo de gerenciamento. Se o blueprint for salvo em uma assinatura, ele só poderá ser atribuído a essa assinatura. O parâmetro blueprint-name especifica o blueprint a ser atribuído. Para fornecer parâmetros name, location, identity, lock e blueprint, use os parâmetros correspondentes da CLI do Azure no comando az blueprint assignment create ou forneça-os no arquivo JSON parameters.

Execute a implantação do blueprint atribuindo-o uma assinatura. Como os parâmetros contributors e owners exigem que uma matriz de objectIds das entidades de segurança seja concedida à atribuição de função, use a API do Graph do Azure Active Directory para coletar as objectIds a serem usadas nos parameters de usuários, de entidades de serviço ou de grupos próprios.
- Arquivo JSON – blueprintAssignment.json
```
{
   "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"
       ]
   }
}
```
- Comando da CLI do Azure
```
az blueprint assignment create \
   --name 'assignMyBlueprint' \
   --location 'westus' \
   --resource-group-value artifact_name=storageRG name=StorageAccount location=eastus \
   --parameters blueprintAssignment.json
```
- Identidade gerenciada atribuída pelo usuário
  
  Uma atribuição de Blueprint também pode usar uma identidade gerenciada atribuída pelo usuário. Nesse caso, o parâmetro identity-type é definido como UserAssigned, e o parâmetro user-assigned-identities especifica a identidade. Substitua {userIdentity} pelo nome da identidade gerenciada atribuída ao usuário.
```
az blueprint assignment create \
   --name 'assignMyBlueprint' \
   --location 'westus' \
   --identity-type UserAssigned \
   --user-assigned-identities {userIdentity} \
   --resource-group-value artifact_name=storageRG name=StorageAccount location=eastus \
   --parameters blueprintAssignment.json
```
  A identidade gerenciada atribuída pelo usuário pode estar em qualquer assinatura e grupo de recursos nos quais o usuário que atribui o blueprint tem permissões.
  
  Importante
  
  O Azure Blueprints não gerencia a identidade gerenciada atribuída por usuário. Os usuários são responsáveis por atribuir as funções e permissões necessárias, ou a atribuição do blueprint falhará.

Limpar os recursos

Você pode remover um blueprint de uma assinatura. A remoção geralmente é feita quando os recursos de artefato não são mais necessários. Quando um modelo é removido, os artefatos atribuídos a esse modelo permanecem. Para remover uma atribuição de blueprint, use o comando az blueprint assignment delete:

az blueprint assignment delete --name 'assignMyBlueprint'

Próximas etapas

Neste guia de início rápido, você criou, atribuiu e removeu um blueprint com a CLI do Azure. Para saber mais sobre Azure Blueprints, continue no artigo sobre o ciclo de vida dos blueprints.

Saiba mais sobre o ciclo de vida do blueprint

Comentários

Esta página foi útil?

Last updated on 2026-06-24