Início rápido: Definir e atribuir um blueprint do Azure com a API REST

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.
Registre o provedor de recursos Microsoft.Blueprint. Para obter instruções, confira Provedores e tipos de recursos.

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.

Introdução à API REST

Se não estiver familiarizado com a API REST, comece revisando a Referência da API REST do Azure, especificamente as seções sobre o URI da solicitação e o corpo da solicitação. Este guia de início rápido usa esses conceitos para fornecer instruções de uso do Azure Blueprints e pressupõe um conhecimento prático deles. Ferramentas como o ARMClient podem lidar com a autorização automaticamente e são recomendadas para iniciantes.

Para ver as especificações do Azure Blueprints, confira a API REST do Azure Blueprints.

API REST e PowerShell

Se você ainda não tiver uma ferramenta para fazer chamadas à API REST, considere usar o PowerShell para essas instruções. Veja a seguir um exemplo de cabeçalho para autenticação no Azure. Gere um cabeçalho de autenticação, às vezes chamado de token de portador, e forneça o URI da API REST para se conectar a qualquer parâmetro ou a um Request Body:

# Log in first with Connect-AzAccount if not using Cloud Shell

$azContext = Get-AzContext
$azProfile = [Microsoft.Azure.Commands.Common.Authentication.Abstractions.AzureRmProfileProvider]::Instance.Profile
$profileClient = New-Object -TypeName Microsoft.Azure.Commands.ResourceManager.Common.RMProfileClient -ArgumentList ($azProfile)
$token = $profileClient.AcquireAccessToken($azContext.Subscription.TenantId)
$authHeader = @{
    'Content-Type'='application/json'
    'Authorization'='Bearer ' + $token.AccessToken
}

# Invoke the REST API
$restUri = 'https://management.azure.com/subscriptions/{subscriptionId}?api-version=2020-01-01'
$response = Invoke-RestMethod -Uri $restUri -Method Get -Headers $authHeader

Substitua {subscriptionId} na variável $restUri anterior para obter informações sobre sua assinatura. A variável $response armazena o resultado do cmdlet Invoke-RestMethod, que pode ser analisado com cmdlets como ConvertFrom-Json. Se o endpoint do serviço da API REST exigir um Request Body, forneça uma variável no formato JSON para o parâmetro -Body de Invoke-RestMethod.

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 API REST, o objeto blueprint é criado primeiro. Para cada artefato com parâmetros a ser adicionado, defina os parâmetros com antecedência no blueprint inicial.

Em cada URI da API REST, substitua as seguintes variáveis por valores próprios:

{YourMG} – Substitua-o pela ID do grupo de gerenciamento.
{subscriptionId} – Substitua-o pela ID da assinatura.

Observação

Você também pode criar modelos no nível da assinatura. Para obter mais informações, confira Exemplo de criação de blueprint na assinatura.

Crie o objeto blueprint original. O Request Body inclui propriedades sobre o blueprint, os grupos de recursos a serem criados e todos os parâmetros no blueprint. Defina os parâmetros durante a atribuição e eles serão usados pelos artefatos que você adicionar em etapas posteriores.

URI da API REST

PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint?api-version=2018-11-01-preview

Corpo da solicitação

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

Adicione uma atribuição de função na assinatura. O Request Body define o tipo de artefato, as propriedades correspondem ao identificador da definição de função e as identidades principais são passadas como um array de valores. 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.
- URI da API REST
```
PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint/artifacts/roleContributor?api-version=2018-11-01-preview
```
- Corpo da solicitação
```
{
    "kind": "roleAssignment",
    "properties": {
        "roleDefinitionId": "/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c",
        "principalIds": "[parameters('contributors')]"
    }
}
```

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

URI da API REST

PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint/artifacts/policyTags?api-version=2018-11-01-preview

Corpo da solicitação

{
    "kind": "policyAssignment",
    "properties": {
        "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')]"
            }
        }
    }
}

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.

URI da API REST

PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint/artifacts/policyStorageTags?api-version=2018-11-01-preview

Corpo da solicitação

{
    "kind": "policyAssignment",
    "properties": {
        "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')]"
            }
        }
    }
}

Adicione um modelo no grupo de recursos. O Request Body de um modelo do ARM inclui o componente normal JSON do modelo e define o grupo de recursos de destino com properties.resourceGroup. 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 ficam disponíveis para o modelo ao definir properties.parameters, e, dentro do JSON do modelo, esse par chave-valor é usado para injetar o valor. Os nomes dos parâmetros do blueprint e do template podem ser os mesmos, mas aqui são diferentes para ilustrar como cada parâmetro é passado do blueprint para o artefato do template.

URI da API REST

PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint/artifacts/templateStorage?api-version=2018-11-01-preview

Corpo da solicitação

{
    "kind": "template",
    "properties": {
        "template": {
            "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
            "contentVersion": "1.0.0.0",
            "parameters": {
                "storageAccountTypeFromBP": {
                    "type": "string",
                    "defaultValue": "Standard_LRS",
                    "allowedValues": [
                        "Standard_LRS",
                        "Standard_GRS",
                        "Standard_ZRS",
                        "Premium_LRS"
                    ],
                    "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": "[resourceGroups('storageRG').location]",
                "sku": {
                    "name": "[parameters('storageAccountTypeFromBP')]"
                },
                "kind": "Storage",
                "properties": {}
            }],
            "outputs": {
                "storageAccountSku": {
                    "type": "string",
                    "value": "[variables('storageAccountName')]"
                }
            }
        },
        "resourceGroup": "storageRG",
        "parameters": {
            "storageAccountTypeFromBP": {
                "value": "[parameters('storageAccountType')]"
            },
            "tagNameFromBP": {
                "value": "[parameters('tagName')]"
            },
            "tagValueFromBP": {
                "value": "[parameters('tagValue')]"
            }
        }
    }
}

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.

URI da API REST

PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint/artifacts/roleOwner?api-version=2018-11-01-preview

Corpo da solicitação

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

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.

URI da API REST

PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint/versions/{BlueprintVersion}?api-version=2018-11-01-preview

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 v20180622-135541.

Atribuir um modelo

Depois que um blueprint é publicado por meio da API REST, 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 Request Body especifica o blueprint a ser atribuído e fornece o nome e a localização dos grupos de recursos na definição de blueprint. Request Body também fornece todos os parâmetros definidos no blueprint e usados por um ou mais artefatos anexados.

Em cada URI da API REST, substitua as seguintes variáveis por valores próprios:

{tenantId} – Substitua-o pela ID de locatário.
{YourMG} – Substitua-o pela ID do grupo de gerenciamento.
{subscriptionId} – Substitua-o pela ID da assinatura.

Forneça à entidade de serviço do Azure Blueprints a função Owner na assinatura de destino. A AppId é estática (f71766dc-90d9-4b7d-bd9d-4499c4331c3f), mas a ID da entidade de serviço varia de acordo com o locatário. Use a API REST a seguir para solicitar detalhes do seu locatário. Ela usa a API do Graph do Azure Active Directory que tem uma autorização diferente.
- URI da API REST
```
GET https://graph.windows.net/{tenantId}/servicePrincipals?api-version=1.6&$filter=appId eq 'f71766dc-90d9-4b7d-bd9d-4499c4331c3f'
```

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 Request Body de usuários, de entidades de serviço ou de grupos próprios.

URI da API REST

PUT https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Blueprint/blueprintAssignments/assignMyBlueprint?api-version=2018-11-01-preview

Corpo da solicitação

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

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, a parte identity do corpo da solicitação é alterada conforme mostrado a seguir. Substitua {yourRG} e {userIdentity} pelo nome do grupo de recursos e pelo nome da identidade gerenciada atribuída por 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 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

Cancelar a atribuição de um blueprint

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 a seguinte operação de API REST:

URI da API REST

DELETE https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Blueprint/blueprintAssignments/assignMyBlueprint?api-version=2018-11-01-preview

Excluir um blueprint

Para remover um blueprint em si, use a seguinte operação de API REST:

URI da API REST

DELETE https://management.azure.com/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint?api-version=2018-11-01-preview

Próximas etapas

Neste guia de início rápido, você criou, atribuiu e removeu um modelo usando a API REST. 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

Início rápido: Definir e atribuir um blueprint do Azure com a API REST

Pré-requisitos

Azure Cloud Shell

Introdução à API REST

API REST e PowerShell

Criar um plano gráfico

Publicar um modelo

Atribuir um modelo

Limpar os recursos

Cancelar a atribuição de um blueprint

Excluir um blueprint

Próximas etapas

Comentários

Recursos adicionais