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

  • Artigo

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

Você pode incluir seu modelo no corpo da solicitação ou vinculá-lo a um arquivo. Se optar pelo arquivo, ele poderá ser local ou um arquivo externo disponível por meio de um URI. Quando seu modelo estiver em uma conta de armazenamento, você poderá restringir o acesso a ele e fornecer um token de SAS (Assinatura de Acesso Compartilhado) durante a implantação.

Permissões necessárias

Para implantar um arquivo Bicep ou um modelo do ARM, você precisa de acesso de gravação nos recursos que está implantando e acesso a todas as operações no tipo de recurso Microsoft.Resources/implantações. Por exemplo, para implantar uma máquina virtual, você precisa Microsoft.Compute/virtualMachines/write e permissões Microsoft.Resources/deployments/*. A operação do teste de hipóteses tem os mesmos requisitos de permissão.

Para ver uma lista de funções e permissões, consulte Funções interna do Azure.

Escopo da implantação

É possível direcionar a sua implantação para um grupo de recursos, uma assinatura do Azure, um grupo de gerenciamento ou um locatário. Dependendo do escopo da implantação, você usará comandos diferentes.

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

Implantar com a API REST

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

  2. Se você estiver implantando em um grupo de recursos que ainda não existe, precisará criá-lo. Forneça sua ID de assinatura, o nome do novo grupo de recursos e 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 o modelo, você pode visualizar as alterações que ele fará no ambiente. Use o teste de hipóteses para conferir se o modelo faz as alterações que você espera. O teste de hipóteses também verifica se há erros no modelo.

  4. Para implantar um modelo, forneça a ID da assinatura, o nome do grupo de recursos e o nome da implantação na 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 o modelo e o arquivo de parâmetro. Para saber mais sobre o arquivo de parâmetro, confira Criar arquivo de parâmetro do Resource Manager.

    Observe que mode está definido como Incremental. Para executar uma implantação completa, defina mode como Complete. Tenha cuidado ao usar o modo completo, pois você pode excluir acidentalmente recursos que não estão em 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 SAS (Assinatura de Acesso Compartilhado). Para obter mais informações, confira 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 em um cofre de chaves. Recupere o cofre de chaves durante a implantação, conforme mostrado no exemplo anterior. Para saber mais, confira Usar o Azure Key Vault para passar um valor de parâmetro seguro durante a implantação.

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

    {
   "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 Implantações – Obter.

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

Implantação com o ARMClient

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

Para listar suas assinaturas:

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 <ID-da-assinatura> pela sua ID da 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, confira ARMClient: uma ferramenta de linha de comando para a API do Azure.

Nome da implantação

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

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

Para criar um nome exclusivo, você pode designar um número aleatório. Ou adicionar 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 nome idêntico que não tenham sido concluídas serão substituídas pela última implantação. Por exemplo, se você executar uma implantação chamada newStorage que implanta uma conta de armazenamento denominada storage1 e, ao mesmo tempo, executar outra implantação chamada newStorage que implanta uma conta de armazenamento denominada storage2, apenas uma conta de armazenamento será implantada. A conta de armazenamento resultante será denominada storage2.

No entanto, se você executar uma implantação chamada newStorage que implanta uma conta de armazenamento denominada storage1 e, logo após a conclusão, executar outra implantação chamada newStorage que implanta uma conta de armazenamento denominada storage2, serão geradas duas contas de armazenamento: uma chamada storage1 e outra denominada storage2. No entanto, apenas uma entrada será registrada no histórico de implantações.

Quando você especifica um nome exclusivo para cada implantação, pode executá-las simultaneamente sem conflitos. Se você executar uma implantação chamada newStorage1 que implanta uma conta de armazenamento denominada storage1 e, ao mesmo tempo, executar outra implantação chamada newStorage2 que implanta uma conta de armazenamento denominada storage2, serão geradas duas contas de armazenamento e serão registradas duas entradas no histórico de implantações.

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

Próximas etapas