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

Artigo
09/07/2023

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:

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 ponto de extremidade de serviço da API REST espera um Request Body, forneça uma variável formatada em 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ção e política 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 blueprints na 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 se alinham com o identificador da definição de função e as identidades de entidade de segurança são passadas como uma matriz de valores. No exemplo a seguir, as identidades de entidade de segurança concedidas à função especificada são configuradas para um parâmetro que é 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 marca 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 de blueprint são disponibilizados para o modelo com a definição de properties.parameters e dentro do modelo JSON em que o par chave-valor é usado para injetar o valor. Os nomes de parâmetros de blueprint e de modelo podem ser os mesmos, mas são diferentes aqui para ilustrar como cada um é transmitido do blueprint para o artefato de modelo.

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 por 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 funções e permissões suficientes, ou a atribuição de 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 blueprint é removido, os artefatos atribuídos como parte desse blueprint são deixados para trás. 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 blueprint com a API REST. Para saber mais sobre o Azure Blueprints, prossiga para o artigo de ciclo de vida do blueprint.

Saiba mais sobre o ciclo de vida do blueprint

Compartilhar via

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