Implementación de recursos con plantillas de Resource Manager y la API de REST de Azure Resource Manager

  • Artículo

En este artículo se explica cómo usar la API de REST de Azure Resource Manager con las plantillas de Azure Resource Manager (ARM) para implementar los recursos en Azure.

Puede incluir la plantilla en el cuerpo de solicitud o vincularla a un archivo. Al usar un archivo, este puede ser un archivo local o un archivo externo disponible a través de un identificador URI. Cuando la plantilla se encuentra en una cuenta de almacenamiento, puede restringir el acceso a ella y proporcionar un token de firma de acceso compartido (SAS) durante la implementación.

Permisos necesarios

Para implementar un archivo de Bicep o una plantilla de ARM, se necesita acceso de escritura en los recursos que implementa y acceso a todas las operaciones del tipo de recurso Microsoft.Resources/deployments. Por ejemplo, para implementar una máquina virtual, necesita los permisos Microsoft.Compute/virtualMachines/write y Microsoft.Resources/deployments/*. La operación what-if tiene los mismos requisitos de permisos.

Para obtener una lista de roles y permisos, consulte Roles integrados de Azure.

Ámbito de la implementación

La implementación puede tener como destino un grupo de recursos, una suscripción de Azure, un grupo de administración o un inquilino. Según el ámbito de la implementación, usará comandos diferentes.

Los ejemplos de este artículo usan las implementaciones del grupo de recursos.

Implementación con la API de REST

  1. Establezca los encabezados y parámetros comunes, incluidos los tokens de autenticación.

  2. Si va a realizar la implementación en un grupo de recursos que no existe, cree el grupo de recursos. Especifique el identificador de la suscripción, el nombre del nuevo grupo de recursos y la ubicación que necesita para la solución. Para obtener más información, consulte Crear un grupo de recursos.

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

    Con un cuerpo de la solicitud como:

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

  3. Antes de implementar la plantilla, puede obtener una vista previa de los cambios que la plantilla realizará en su entorno. Use la operación Y si para comprobar que la plantilla realiza los cambios esperados. La operación Y si también valida que la plantilla no tenga errores.

  4. Para implementar una plantilla, especifique el identificador de suscripción, el nombre del grupo de recursos y el nombre de la implementación en el URI de solicitud.

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

    En el cuerpo de solicitud, proporcione un vínculo al archivo de plantilla y parámetros. Para más información sobre el archivo de parámetro, consulte Creación de un archivo de parámetros de Resource Manager.

    Observe que el mode se establece en Incremental. Para ejecutar una implementación completa, establezca el mode en Completo. Tenga cuidado al usar este modo, ya que puede eliminar accidentalmente los recursos que no estén en la plantilla.

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

    Si desea registrar el contenido de la respuesta y el de la solicitud, o ambos, incluya debugSetting en la solicitud.

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

    Puede configurar la cuenta de almacenamiento para utilizar un token de firma de acceso compartido (SAS). Para obtener más información, consulte Delegar el acceso con una firma de acceso compartido.

    Si necesita proporcionar un valor confidencial para un parámetro (por ejemplo, una contraseña), agregue ese valor a un almacén de claves. Recupere el almacén de claves durante la implementación, como se muestra en el ejemplo anterior. Para más información, consulte Uso de Azure Key Vault para pasar el valor de parámetro seguro durante la implementación.

  5. En lugar de crear vínculos a archivos para la plantilla y los parámetros, puede incluirlos en el cuerpo de la solicitud. El ejemplo siguiente muestra el cuerpo de la solicitud con la plantilla y el parámetro en línea:

    {
   "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 obtener el estado de la implementación de la plantilla, use Deployments - Get.

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

Implementación con ARMClient

ARMClient es una sencilla herramienta de línea de comandos para invocar la API de Azure Resource Manager. Para instalar la herramienta, consulte ARMClient.

Para enumerar sus suscripciones:

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

Para enumerar sus grupos de recursos:

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

Reemplace <subscription-id> por su id. de suscripción de Azure.

Para crear un grupo de recursos en la región Centro de EE. UU.:

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

Como alternativa, puede colocar el cuerpo en un archivo 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 obtener más información, consulte ARMClient: a command line tool for the Azure API (ARMClient: una herramienta de línea de comandos para la API de Azure).

Nombre de implementación

Puede asignar un nombre a la implementación, como ExampleDeployment.

Cada vez que se ejecuta una implementación, se agrega una entrada al historial de implementación del grupo de recursos con el nombre de la implementación. Si ejecuta otra implementación y le asigna el mismo nombre, la entrada anterior se reemplazará por la implementación actual. Si desea que todas las entradas del historial de implementaciones sean diferentes, asigne un nombre único a cada implementación.

Para crear un nombre único, puede asignar un número aleatorio. También puede agregar un valor de fecha.

Si ejecuta implementaciones simultáneas en el mismo grupo de recursos utilizando el mismo nombre de implementación, solo se completará la última implementación. Aquellas implementaciones que tengan el mismo nombre y no hayan finalizado se sustituirán por la última implementación. Por ejemplo, si ejecuta una implementación llamada newStorage que implementa la cuenta de almacenamiento storage1 y, al mismo tiempo, ejecuta otra implementación llamada newStorage que implementa la cuenta de almacenamiento storage2, solo se implementará una única cuenta de almacenamiento. La cuenta de almacenamiento resultante será storage2.

Sin embargo, si ejecuta una implementación llamada newStorage que implementa la cuenta de almacenamiento storage1 e inmediatamente después ejecuta otra implementación llamada newStorage que implementa la cuenta de almacenamiento storage2, tendrá dos cuentas de almacenamiento. Una se llamará storage1 y la otra, storage2. Sin embargo, solo tendrá una entrada en el historial de implementaciones.

Si especifica un nombre único para cada implementación, podrá ejecutarlas simultáneamente sin conflictos. Si ejecuta una implementación llamada newStorage1 que implementa la cuenta de almacenamiento storage1 y, al mismo tiempo, ejecuta otra implementación llamada newStorage2 que implementa la cuenta de almacenamiento storage2, tendrá dos cuentas de almacenamiento y dos entradas en el historial de implementación.

Para evitar conflictos con las implementaciones simultáneas y garantizar que las entradas del historial de implementaciones sean únicas, asigne un nombre diferente a cada implementación.

Pasos siguientes