Guia de início rápido: definir e atribuir um plano do Azure com a API REST

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

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.

Introdução à API REST

Se você não estiver familiarizado com a API REST, comece examinando 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 para trabalhar com o Azure Blueprints e pressupõe um conhecimento prático deles. Ferramentas como ARMClient podem lidar com a autorização automaticamente e são recomendadas para iniciantes.

Para obter as especificações do Azure Blueprints, consulte Azure Blueprints REST API.

API REST e PowerShell

Se ainda não tem uma ferramenta para fazer chamadas à API REST, considere utilizar o PowerShell para estas instruções. A seguir está um cabeçalho de exemplo para autenticação com o 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 quaisquer parâmetros 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 anterior $restUri para obter informações sobre sua assinatura. A $response variável contém o Invoke-RestMethod resultado do cmdlet, que você pode analisar com cmdlets como ConvertFrom-Json. Se o ponto de extremidade do serviço da API REST espera um Request Body, forneça uma variável formatada em JSON para o -Body parâmetro de Invoke-RestMethod.

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 a API REST, 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.

Em cada URI DA API REST, substitua as seguintes variáveis pelos seus próprios valores:

{YourMG} - Substitua pelo ID do seu grupo de gestão.
{subscriptionId} - Substitua pelo seu ID de subscrição.

Nota

Você também pode criar esquemas no nível da assinatura. Para obter mais informações, consulte criar blueprint no exemplo de assinatura.

Crie o objeto esquema inicial. O Request Body 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.

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 do Pedido

{
    "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 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.
- 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 do Pedido
```
{
    "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 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.

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 do Pedido

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

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 do Pedido

{
    "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 para um modelo ARM inclui o componente JSON normal do modelo e define o grupo de recursos de destino com properties.resourceGroup. 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 definindo properties.parameters, e dentro do modelo JSON esse par chave-valor é usado para injetar o valor. Os nomes dos parâmetros do blueprint e do modelo podem ser os mesmos, mas são diferentes aqui para ilustrar como cada um passa do blueprint para o artefato do 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 do Pedido

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

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 do Pedido

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

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.

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 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 a API REST, 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 Request Body especifica o plano a ser atribuído e fornece o nome e o local para todos os grupos de recursos na definição do 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 pelos seus próprios valores:

{tenantId} - Substitua pelo seu ID de inquilino.
{YourMG} - Substitua pelo ID do seu grupo de gestão.
{subscriptionId} - Substitua pelo seu ID de subscrição.

Forneça à entidade de serviço do Azure Blueprints a Owner função na assinatura de destino. O AppId é estático (f71766dc-90d9-4b7d-bd9d-4499c4331c3f), mas o ID da entidade de serviço varia de acordo com o locatário. Use a seguinte API REST para solicitar detalhes para seu locatário. Ele usa a API do Azure Ative Directory Graph, que tem 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 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 Request Body para seus próprios usuários, grupos ou entidades de objectIds serviço.

URI da API REST

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

Corpo do Pedido

{
    "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 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 corpo da solicitação muda da seguinte maneira. Substitua {yourRG} e {userIdentity} pelo nome do grupo de recursos e pelo 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)

Anular a atribuição de um esquema

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 esquema, utilize a seguinte operação da API REST:

URI da API REST

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

Eliminar um esquema

Para remover o próprio esquema, utilize a seguinte operação da 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óximos passos

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

Partilhar via

Guia de início rápido: definir e atribuir um plano do Azure com a API REST

Pré-requisitos

Azure Cloud Shell

Introdução à API REST

API REST e PowerShell

Criar um esquema

Publicar um esquema

Atribuir um esquema

Clean up resources (Limpar recursos)

Anular a atribuição de um esquema

Eliminar um esquema

Próximos passos

Comentários

Recursos adicionais