Implementar recursos com modelos arm e a API REST do Azure Resource Manager
Este artigo explica como utilizar a API REST do Azure Resource Manager com modelos de Resource Manager do Azure (modelos arm) para implementar os seus recursos no Azure.
Pode incluir o modelo no corpo do pedido ou ligar a um ficheiro. Ao utilizar um ficheiro, pode ser um ficheiro local ou um ficheiro externo que está disponível através de um URI. Quando o modelo está numa conta de armazenamento, pode restringir o acesso ao modelo e fornecer um token de assinatura de acesso partilhado (SAS) durante a implementação.
Permissões obrigatórias
Para implementar um ficheiro Bicep ou modelo do ARM, precisa de acesso de escrita nos recursos que está a implementar e acesso a todas as operações no tipo de recurso Microsoft.Resources/deployments. Por exemplo, para implementar uma máquina virtual, precisa de permissões e Microsoft.Resources/deployments/*
.Microsoft.Compute/virtualMachines/write
A operação what-if tem os mesmos requisitos de permissão.
Para obter uma lista de funções e permissões, veja Funções incorporadas do Azure.
Âmbito de implementação
Pode direcionar a sua implementação para um grupo de recursos, subscrição do Azure, grupo de gestão ou inquilino. Consoante o âmbito da implementação, utilize comandos diferentes.
Para implementar num grupo de recursos, utilize Implementações – Criar. O pedido é enviado para:
PUT https://management.azure.com/subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}/providers/Microsoft.Resources/deployments/{deploymentName}?api-version=2020-10-01
Para implementar numa subscrição, utilize Implementações – Criar no Âmbito da Subscrição. O pedido é enviado para:
PUT https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Resources/deployments/{deploymentName}?api-version=2020-10-01
Para obter mais informações sobre implementações ao nível da subscrição, veja Criar grupos de recursos e recursos ao nível da subscrição.
Para implementar num grupo de gestão, utilize Implementações – Criar no Âmbito do Grupo de Gestão. O pedido é enviado para:
PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/{groupId}/providers/Microsoft.Resources/deployments/{deploymentName}?api-version=2020-10-01
Para obter mais informações sobre implementações ao nível do grupo de gestão, veja Criar recursos ao nível do grupo de gestão.
Para implementar num inquilino, utilize Implementações – Criar ou Atualizar no Âmbito do Inquilino. O pedido é enviado para:
PUT https://management.azure.com/providers/Microsoft.Resources/deployments/{deploymentName}?api-version=2020-10-01
Para obter mais informações sobre implementações ao nível do inquilino, veja Criar recursos ao nível do inquilino.
Os exemplos neste artigo utilizam implementações de grupos de recursos.
Implementar com a API REST
Defina parâmetros e cabeçalhos comuns, incluindo tokens de autenticação.
Se estiver a implementar num grupo de recursos que não existe, crie o grupo de recursos. Indique o ID da subscrição, o nome do novo grupo de recursos e a localização de que precisa para a sua solução. Para obter mais informações, veja Criar um grupo de recursos.
PUT https://management.azure.com/subscriptions/<YourSubscriptionId>/resourcegroups/<YourResourceGroupName>?api-version=2020-06-01
Com um corpo de pedido como:
{ "location": "West US", "tags": { "tagname1": "tagvalue1" } }
Antes de implementar o modelo, pode pré-visualizar as alterações que o modelo irá fazer ao seu ambiente. Utilize a operação what-if para verificar se o modelo efetua as alterações esperadas. O what-if também valida o modelo para erros.
Para implementar um modelo, forneça o seu ID de subscrição, o nome do grupo de recursos, o nome da implementação no URI do pedido.
PUT https://management.azure.com/subscriptions/<YourSubscriptionId>/resourcegroups/<YourResourceGroupName>/providers/Microsoft.Resources/deployments/<YourDeploymentName>?api-version=2020-10-01
No corpo do pedido, forneça uma ligação para o seu modelo e ficheiro de parâmetros. Para obter mais informações sobre o ficheiro de parâmetros, veja Criar ficheiro de parâmetros do Resource Manager.
Repare que está
mode
definido como Incremental. Para executar uma implementação completa, definamode
como Concluída. Tenha cuidado ao utilizar o modo completo, pois pode eliminar inadvertidamente recursos que não estão no seu modelo.{ "properties": { "templateLink": { "uri": "http://mystorageaccount.blob.core.windows.net/templates/template.json", "contentVersion": "1.0.0.0" }, "parametersLink": { "uri": "http://mystorageaccount.blob.core.windows.net/templates/parameters.json", "contentVersion": "1.0.0.0" }, "mode": "Incremental" } }
Se quiser registar conteúdo de resposta, pedir conteúdo ou ambos, inclua
debugSetting
no pedido.{ "properties": { "templateLink": { "uri": "http://mystorageaccount.blob.core.windows.net/templates/template.json", "contentVersion": "1.0.0.0" }, "parametersLink": { "uri": "http://mystorageaccount.blob.core.windows.net/templates/parameters.json", "contentVersion": "1.0.0.0" }, "mode": "Incremental", "debugSetting": { "detailLevel": "requestContent, responseContent" } } }
Pode configurar a sua conta de armazenamento para utilizar um token de assinatura de acesso partilhado (SAS). Para obter mais informações, veja Delegar o acesso com uma assinatura de acesso partilhado.
Se precisar de fornecer um valor confidencial para um parâmetro (como uma palavra-passe), adicione esse valor a um cofre de chaves. Obtenha o cofre de chaves durante a implementação, conforme mostrado no exemplo anterior. Para obter mais informações, veja Utilizar o Azure Key Vault para transmitir o valor do parâmetro seguro durante a implementação.
Em vez de ligar a ficheiros para o modelo e parâmetros, pode incluí-los no corpo do pedido. O exemplo seguinte mostra o corpo do pedido com o modelo e o parâmetro inline:
{ "properties": { "mode": "Incremental", "template": { "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", "contentVersion": "1.0.0.0", "parameters": { "storageAccountType": { "type": "string", "defaultValue": "Standard_LRS", "allowedValues": [ "Standard_LRS", "Standard_GRS", "Standard_ZRS", "Premium_LRS" ], "metadata": { "description": "Storage Account type" } }, "location": { "type": "string", "defaultValue": "[resourceGroup().location]", "metadata": { "description": "Location for all resources." } } }, "variables": { "storageAccountName": "[format('{0}standardsa', uniquestring(resourceGroup().id))]" }, "resources": [ { "type": "Microsoft.Storage/storageAccounts", "apiVersion": "2022-09-01", "name": "[variables('storageAccountName')]", "location": "[parameters('location')]", "sku": { "name": "[parameters('storageAccountType')]" }, "kind": "StorageV2", "properties": {} } ], "outputs": { "storageAccountName": { "type": "string", "value": "[variables('storageAccountName')]" } } }, "parameters": { "location": { "value": "eastus2" } } } }
Para obter o estado da implementação do modelo, utilize Implementações – Obter.
GET https://management.azure.com/subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}/providers/Microsoft.Resources/deployments/{deploymentName}?api-version=2020-10-01
Implementar com o ARMClient
O ARMClient é uma ferramenta de linha de comandos simples para invocar a API de Resource Manager do Azure. Para instalar a ferramenta, veja ARMClient.
Para listar as suas subscrições:
armclient GET /subscriptions?api-version=2021-04-01
Para listar os grupos de recursos:
armclient GET /subscriptions/<subscription-id>/resourceGroups?api-version=2021-04-01
Substitua <subscription-id> pelo seu ID de subscrição do Azure.
Para criar um grupo de recursos na região E.U.A. Central :
armclient PUT /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>?api-version=2021-04-01 "{location: 'central us', properties: {}}"
Em alternativa, pode colocar o corpo num ficheiro JSON denominado CreateRg.json:
{
"location": "Central US",
"properties": { }
}
armclient PUT /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>?api-version=2021-04-01 '@CreateRg.json'
Para obter mais informações, veja ARMClient: uma ferramenta de linha de comandos para a API do Azure.
Nome da implementação
Pode atribuir um nome à sua implementação, como ExampleDeployment
.
Sempre que executa uma implementação, é adicionada uma entrada ao histórico de implementações do grupo de recursos com o nome da implementação. Se executar outra implementação e lhe der o mesmo nome, a entrada anterior será substituída pela implementação atual. Se quiser manter entradas exclusivas no histórico de implementações, atribua um nome exclusivo a cada implementação.
Para criar um nome exclusivo, pode atribuir um número aleatório. Em alternativa, adicione um valor de data.
Se executar implementações simultâneas no mesmo grupo de recursos com o mesmo nome de implementação, apenas a última implementação será concluída. Todas as implementações com o mesmo nome que ainda não tenham sido concluídas são substituídas pela última implementação. Por exemplo, se executar uma implementação com o nome newStorage
que implementa uma conta de armazenamento com o nome storage1
e, ao mesmo tempo, executar outra implementação com o nome newStorage
que implemente uma conta de armazenamento com o nome storage2
, implementa apenas uma conta de armazenamento. A conta de armazenamento resultante tem o nome storage2
.
No entanto, se executar uma implementação com o nome newStorage
que implementa uma conta de armazenamento com o nome storage1
e, imediatamente após a conclusão, executar outra implementação com o nome newStorage
que implemente uma conta de armazenamento com o nome storage2
, terá duas contas de armazenamento. Um tem o nome storage1
e o outro tem o nome storage2
. Mas só tem uma entrada no histórico de implementações.
Quando especificar um nome exclusivo para cada implementação, pode executá-los simultaneamente sem conflitos. Se executar uma implementação com o nome newStorage1
que implementa uma conta de armazenamento com o nome storage1
e, ao mesmo tempo, executar outra implementação com o nome newStorage2
que implementa uma conta de armazenamento com o nome storage2
, terá duas contas de armazenamento e duas entradas no histórico de implementações.
Para evitar conflitos com implementações simultâneas e para garantir entradas exclusivas no histórico de implementações, atribua um nome exclusivo a cada implementação.
Passos seguintes
- Para reverter para uma implementação com êxito quando receber um erro, veja Reverter o erro para uma implementação com êxito.
- Para especificar como processar recursos que existem no grupo de recursos, mas que não estão definidos no modelo, veja Modos de implementação do Azure Resource Manager.
- Para saber mais sobre como lidar com operações REST assíncronas, veja Controlar operações assíncronas do Azure.
- Para saber mais sobre modelos, veja Compreender a estrutura e a sintaxe dos modelos do ARM.