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

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.
• Registe o fornecedor de recursos Microsoft.Blueprint. 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:

1. Inicie o Cloud Shell.

2. Selecione o botão Copiar em um bloco de código (ou bloco de comando) para copiar o código ou comando.

3. Cole o código ou comando na sessão do Cloud Shell premindo Ctrl+Shift+V no Windows e no Linux, ou premindo Cmd+Shift+V no macOS.

4. 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, por vezes chamado de token bearer, e forneça o URI da API REST para estabelecer ligação com quaisquer parâmetros ou com 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 variável $response armazena o resultado do cmdlet Invoke-RestMethod, que pode processar com cmdlets como ConvertFrom-Json. Se o endpoint do serviço da API REST esperar um Request Body, forneça uma variável formatada em JSON ao parâmetro -Body 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.

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.

1. Crie o objeto esquema inicial. O Request Body inclui propriedades relativas ao modelo, quaisquer grupos de recursos a criar e todos os parâmetros ao nível do modelo. 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."
                 }
             }
         }
     }
     

2. 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')]"
         }
     }
     

3. Adicione uma atribuição de política na assinatura. Request Body define o tipo de artefacto, as propriedades correspondem a uma definição de política ou de iniciativa, e a atribuição da política é configurada para utilizar os parâmetros definidos do blueprint durante a atribuição do blueprint. Este exemplo usa a política incorporada 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 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')]"
                 }
             }
         }
     }
     

4. Adicione outra atribuição de política para a tag de armazenamento (reutilizando storageAccountType_ parameter) ao nível da subscrição. 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, utiliza o storageAccountType para definir uma etiqueta 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 política incorporada 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 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')]"
                 }
             }
         }
     }
     

5. 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 parâmetros do esquema storageAccountType, tagName e tagValue, passando cada um deles 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 template podem ser os mesmos, mas aqui são diferentes para ilustrar como cada um é transmitido do blueprint para o artefacto 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 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')]"
                 }
             }
         }
     }
     

6. 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 plano que criou a uma das subscrições sob a sua hierarquia de grupos de gestão. 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.

1. Atribua ao principal de serviço do Azure Blueprints a função Owner na subscrição 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'
     

2. Execute a implementação do blueprint, atribuindo-o a uma subscrição. Uma vez que os parâmetros contributors e owners exigem uma matriz de objectIds das identidades às quais será atribuída a função, utilize a Azure Active Directory Graph API para obter o objectIds para utilizar no Request Body dos seus próprios utilizadores, grupos ou principais de 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 utilizar uma identidade gerida atribuída pelo utilizador. 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 utilizadores são responsáveis por atribuir funções e permissões suficientes; caso contrário, a atribuição do blueprint falhará.

Limpar recursos

Anular a atribuição de um esquema

Pode remover um esquema de uma subscrição. A eliminação é frequentemente efetuada quando os recursos do artefacto deixam de ser necessários. 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 Esquemas do Azure, consulte o artigo sobre o ciclo de vida dos esquemas.