Implantar recursos com modelos ARM e a API REST do Azure Resource Manager

  • Artigo

Este artigo explica como usar a API REST do Azure Resource Manager com modelos do Azure Resource Manager (modelos ARM) para implantar seus recursos no Azure.

Você pode incluir seu modelo no corpo da solicitação ou vincular a um arquivo. Ao usar um arquivo, ele pode ser um arquivo local ou um arquivo externo que está disponível por meio de um URI. Quando o modelo está em uma conta de armazenamento, você pode restringir o acesso ao modelo e fornecer um token de assinatura de acesso compartilhado (SAS) durante a implantaçã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 implantar uma máquina virtual, você precisa de Microsoft.Compute/virtualMachines/write permissões Microsoft.Resources/deployments/* . A operação hipotética tem os mesmos requisitos de permissão.

Para obter uma lista de funções e permissões, veja Funções incorporadas do Azure.

Âmbito da implementação

Você pode direcionar sua implantação para um grupo de recursos, assinatura do Azure, grupo de gerenciamento ou locatário. Dependendo do escopo da implantação, você usa comandos diferentes.

  • Para implantar em um grupo de recursos, use Implantaçõ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 implantar em uma assinatura, use Implantações - Criar no escopo da assinatura. 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 implantações no nível de assinatura, consulte Criar grupos de recursos e recursos no nível de assinatura.

  • Para implantar em um grupo de gerenciamento, use Implantações - Criar no escopo do grupo de gerenciamento. 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 implantações no nível do grupo de gerenciamento, consulte Criar recursos no nível do grupo de gerenciamento.

  • Para implantar em um locatário, use Implantações - Criar ou atualizar no escopo do locatário. 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 implantações no nível do locatário, consulte Criar recursos no nível do locatário.

Os exemplos neste artigo usam implantações de grupo de recursos.

Implementar com a API REST

  1. Defina parâmetros e cabeçalhos comuns, incluindo tokens de autenticação.

  2. Se você estiver implantando em um grupo de recursos que não existe, crie o grupo de recursos. Forneça sua ID de assinatura, o nome do novo grupo de recursos e o local que você precisa para sua solução. Para obter mais informações, consulte Criar um grupo de recursos.

    PUT https://management.azure.com/subscriptions/<YourSubscriptionId>/resourcegroups/<YourResourceGroupName>?api-version=2020-06-01

    Com um corpo de solicitação como:

    {
 "location": "West US",
 "tags": {
   "tagname1": "tagvalue1"
 }
}

  3. Antes de implantar seu modelo, você pode visualizar as alterações que o modelo fará em seu ambiente. Use a operação hipotética para verificar se o modelo faz as alterações esperadas. O What-if também valida o modelo em busca de erros.

  4. Para implantar um modelo, forneça sua ID de assinatura, o nome do grupo de recursos, o nome da implantação no URI de solicitação.

    PUT https://management.azure.com/subscriptions/<YourSubscriptionId>/resourcegroups/<YourResourceGroupName>/providers/Microsoft.Resources/deployments/<YourDeploymentName>?api-version=2020-10-01

    No corpo da solicitação, forneça um link para seu modelo e arquivo de parâmetro. Para obter mais informações sobre o ficheiro de parâmetros, veja Criar ficheiro de parâmetros do Resource Manager.

    Observe que o mode está definido como Incremental. Para executar uma implantação completa, defina mode como Concluir. Tenha cuidado ao usar o modo completo, pois você pode excluir 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 você quiser registrar o conteúdo da resposta, o conteúdo da solicitação ou ambos, inclua debugSetting na solicitação.

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

    Você pode configurar sua conta de armazenamento para usar um token de assinatura de acesso compartilhado (SAS). Para obter mais informações, consulte Delegar acesso com uma assinatura de acesso compartilhado.

    Se você precisar fornecer um valor confidencial para um parâmetro (como uma senha), adicione esse valor a um cofre de chaves. Recupere o cofre de chaves durante a implantação, conforme mostrado no exemplo anterior. Para obter mais informações, consulte Usar o Azure Key Vault para passar o valor do parâmetro seguro durante a implantação.

  5. Em vez de vincular a arquivos para o modelo e parâmetros, você pode incluí-los no corpo da solicitação. O exemplo a seguir mostra o corpo da solicitação com o modelo e o parâmetro embutidos:

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

  6. Para obter o status da implantação do modelo, use Deployments - Get.

    GET https://management.azure.com/subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}/providers/Microsoft.Resources/deployments/{deploymentName}?api-version=2020-10-01

Implante com o ARMClient

ARMClient é uma ferramenta de linha de comando simples para invocar a API do Azure Resource Manager. Para instalar a ferramenta, consulte ARMClient.

Para listar as suas subscrições:

armclient GET /subscriptions?api-version=2021-04-01

Para listar seus grupos de recursos:

armclient GET /subscriptions/<subscription-id>/resourceGroups?api-version=2021-04-01

Substitua <subscription-id> pela sua ID de assinatura do Azure.

Para criar um grupo de recursos na região EUA Central:

armclient PUT /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>?api-version=2021-04-01  "{location: 'central us', properties: {}}"

Como alternativa, você pode colocar o corpo em um arquivo JSON chamado 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, consulte ARMClient: uma ferramenta de linha de comando para a API do Azure.

Nome da implementação

Você pode dar à sua implantação um nome como ExampleDeployment.

Sempre que você executa uma implantação, uma entrada é adicionada ao histórico de implantação do grupo de recursos com o nome da implantação. Se você executar outra implantação e lhe der o mesmo nome, a entrada anterior será substituída pela implantação atual. Se você quiser manter entradas exclusivas no histórico de implantação, dê a cada implantação um nome exclusivo.

Para criar um nome exclusivo, você pode atribuir um número aleatório. Ou adicione um valor de data.

Se você executar implantações simultâneas no mesmo grupo de recursos com o mesmo nome de implantação, somente a última implantação será concluída. Todas as implantações com o mesmo nome que não foram concluídas são substituídas pela última implantação. Por exemplo, se você executar uma implantação nomeada newStorage que implanta uma conta de armazenamento chamada storage1, e ao mesmo tempo executar outra implantação nomeada newStorage que implanta uma conta de armazenamento chamada storage2, você implantará apenas uma conta de armazenamento. A conta de armazenamento resultante é denominada storage2.

No entanto, se você executar uma implantação nomeada newStorage que implanta uma conta de armazenamento chamada storage1, e imediatamente após sua conclusão executar outra implantação nomeada newStorage que implanta uma conta de armazenamento chamada storage2, então você terá duas contas de armazenamento. Um é chamado storage1, e o outro é chamado storage2. Mas, você só tem uma entrada no histórico de implantação.

Ao especificar um nome exclusivo para cada implantação, você pode executá-los simultaneamente sem conflito. Se você executar uma implantação nomeada newStorage1 que implanta uma conta de armazenamento chamada storage1e, ao mesmo tempo, executar outra implantação nomeada newStorage2 que implanta uma conta de armazenamento chamada storage2, terá duas contas de armazenamento e duas entradas no histórico de implantação.

Para evitar conflitos com implantações simultâneas e garantir entradas exclusivas no histórico de implantação, dê a cada implantação um nome exclusivo.

Próximos passos