Inicio rápido: Definición y asignación de un plano técnico de Azure con la API de REST

Artículo
09/22/2023

Importante

El 11 de julio de 2026, Blueprints (versión preliminar) quedará en desuso. Migre las definiciones y asignaciones de planos técnicos existentes a Especificaciones de plantilla y Pilas de implementación. Los artefactos de plano técnico se convertirán en plantillas JSON de ARM o archivos de Bicep que se usan para definir pilas de implementación. Para obtener información sobre cómo crear un artefacto como un recurso de ARM, consulte:

En este tutorial, aprenderá a usar planos técnicos de Azure Blueprints para realizar algunas de las tareas más comunes relacionadas con la creación, publicación y asignación de planos técnicos en toda la organización. Esta aptitud ayuda a definir patrones comunes para desarrollar configuraciones reutilizables y que se pueden implementar rápidamente, basadas en plantillas, directivas y seguridad de Azure Resource Manager (ARM).

Requisitos previos

Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.
Registre el proveedor de recursos Microsoft.Blueprint. Para instrucciones, consulte Tipos y proveedores de recursos.

Azure Cloud Shell

En Azure se hospeda Azure Cloud Shell, un entorno de shell interactivo que puede utilizar mediante el explorador. Puede usar Bash o PowerShell con Cloud Shell para trabajar con los servicios de Azure. Puede usar los comandos preinstalados de Cloud Shell para ejecutar el código de este artículo sin tener que instalar nada en su entorno local.

Para iniciar Azure Cloud Shell:

Opción	Ejemplo o vínculo
Seleccione Pruébelo en la esquina superior derecha de un bloque de código o de comandos. Solo con seleccionar Pruébelo no se copia automáticamente el código o comando en Cloud Shell.
Vaya a https://shell.azure.com o seleccione el botón Iniciar Cloud Shell para abrir Cloud Shell en el explorador.
Seleccione el botón Cloud Shell en la barra de menús de la esquina superior derecha de Azure Portal.

Para usar Azure Cloud Shell:

Inicie Cloud Shell.
Seleccione el botón Copiar en un bloque de código (o bloque de comandos) para copiar el código o comando.
Pegue el código o comando en la sesión de Cloud Shell. Para ello, seleccione Ctrl+Mayús+V en Windows y Linux, o bien seleccione Cmd+Mayús+V en macOS.
Seleccione Intro para ejecutar el código o comando.

Introducción a la API de REST

Si no está familiarizado con la API REST, empiece por revisar la referencia de la API REST de Azure, en concreto las secciones sobre el URI de solicitud y el cuerpo de la solicitud. En este inicio rápido se usan estos conceptos para proporcionar instrucciones para trabajar con Azure Blueprints y se supone que tiene conocimientos prácticos de ellos. Herramientas como ARMClient pueden controlar la autorización automáticamente y se recomiendan para principiantes.

Para información sobre las especificaciones de Azure Blueprints, consulte API REST de Azure Blueprints.

API REST y PowerShell

Si aún no tiene una herramienta para realizar llamadas de API REST, considere el uso de PowerShell para estas instrucciones. A continuación, se muestra un encabezado de ejemplo para la autenticación con Azure. Genere un encabezado de autenticación, a veces denominado token de portador, y proporcione el URI de la API REST para conectarse con cualquier parámetro o 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

Reemplace {subscriptionId} en la variable $restUri anterior para obtener información sobre su suscripción. La variable $response contiene el resultado del cmdlet Invoke-RestMethod, que puede analizar con cmdlets como ConvertFrom-Json. Si el punto de conexión de servicio de la API REST espera un elemento Request Body, proporcione una variable con formato JSON al parámetro -Body de Invoke-RestMethod.

Creación de un plano técnico

El primer paso para definir un patrón estándar de cumplimiento es elaborar un plano técnico a partir de los recursos disponibles. Vamos a crear un plano técnico llamado MyBlueprint para configurar las asignaciones de roles y directivas de la suscripción. A continuación, agregará un grupo de recursos, una plantilla de Resource Manager y una asignación de roles en el grupo de recursos.

Nota:

Cuando se usa la API REST, el objeto plano técnico se crea primero. Para cada artefacto que se agregue que tenga parámetros, defina los parámetros de antemano en el plano técnico inicial.

En cada URI de API REST, reemplace las siguientes variables por sus propios valores:

{YourMG}: reemplácelo por el identificador del grupo de administración.
{subscriptionId}: reemplácelo por el identificador de la suscripción.

Nota:

También puede crear planos técnico a nivel de suscripción. Para más información, consulte Ejemplo de creación de un plano técnico en la suscripción.

Cree el objeto blueprint inicial. El elemento Request Body incluye propiedades sobre el plano técnico, los grupos de recursos que se crearán y todos los parámetros de nivel de plano técnico. Los parámetros se establecen durante la asignación y los usan los artefactos que agregue en pasos posteriores.

URI DE LA API REST

PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint?api-version=2018-11-01-preview

Cuerpo de la solicitud

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

Agregue una asignación de roles a la suscripción. El elemento Request Body define el tipo de artefacto, las propiedades se alinean con el identificador de definición de rol y las identidades principales se pasan como una matriz de valores. En el siguiente ejemplo, las identidades de la entidad de servicio a las que se ha asignado el rol especificado se configuran con un parámetro que se establece durante la asignación de planos técnicos. En este ejemplo se usa el rol integrado Contributor con el GUID de b24988ac-6180-42a0-ab88-20f7382dd24c.
- URI DE LA 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
```
- Cuerpo de la solicitud
```
{
    "kind": "roleAssignment",
    "properties": {
        "roleDefinitionId": "/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c",
        "principalIds": "[parameters('contributors')]"
    }
}
```

Agregue una asignación de directiva a la suscripción. El elemento Request Body define el tipo de artefacto, las propiedades se alinean con una definición de directiva o iniciativa, y la asignación de directivas se configura para usar los parámetros del plano técnico definidos durante la asignación del plano técnico. En este ejemplo se usa la directiva integrada Apply tag and its default value to resource groups con el GUID de 49c88fc8-6fd1-46fd-a676-f12d1d3a4c71.

URI DE LA 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

Cuerpo de la solicitud

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

Agregue otra asignación de directiva para la etiqueta de almacenamiento (mediante la reutilización de storageAccountType_ parameter) en la suscripción. Este artefacto de asignación de directivas adicional muestra que un parámetro definido en el plano técnico lo puede utilizar más de un artefacto. En el ejemplo, se usa storageAccountType para establecer una etiqueta en el grupo de recursos. Este valor proporciona información acerca de la cuenta de almacenamiento que crea en el paso siguiente. En este ejemplo se usa la directiva integrada Apply tag and its default value to resource groups con el GUID de 49c88fc8-6fd1-46fd-a676-f12d1d3a4c71.

URI DE LA 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

Cuerpo de la solicitud

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

Agregue una plantilla en el grupo de recursos. El elemento Request Body de una plantilla de ARM incluye el componente JSON normal de la plantilla, y define el grupo de recursos de destino con properties.resourceGroup. La plantilla también reutiliza los parámetros de plano técnico storageAccountType, tagName y tagValue pasando cada uno a la plantilla. Los parámetros de plano técnico están disponibles para la plantilla mediante la definición de properties.parameters y, dentro de la plantilla JSON, se usa el par clave-valor para insertar el valor. Los nombres de los parámetros de plano técnico y plantilla pueden ser los mismos, pero aquí son diferentes para ilustrar cómo pasa cada uno del plano técnico al artefacto de plantilla.

URI DE LA 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

Cuerpo de la solicitud

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

Agregue una asignación de roles en el grupo de recursos. Igual que con la entrada anterior de asignación de roles, en el ejemplo siguiente se usa el identificador de definición para el rol Owner y se proporciona un parámetro diferente del plano técnico. En este ejemplo se usa el rol integrado Owner con el GUID de 8e3af657-a8ff-443c-a75c-2fe8c4bcb635.

URI DE LA 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

Cuerpo de la solicitud

{
    "kind": "roleAssignment",
    "properties": {
        "resourceGroup": "storageRG",
        "roleDefinitionId": "/providers/Microsoft.Authorization/roleDefinitions/8e3af657-a8ff-443c-a75c-2fe8c4bcb635",
        "principalIds": "[parameters('owners')]"
    }
}

Publicación de un plano técnico

Ahora que ha agregado los artefactos al plano técnico, es hora de publicarlo. La publicación hace que el plano técnico esté disponible para asignarse a una suscripción.

URI DE LA 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

El valor de {BlueprintVersion} es una cadena de letras, números y guiones (sin espacios ni otros caracteres especiales). La longitud máxima es de 20 caracteres. Utilice un nombre único e informativo, como v20180622-135541.

Asignación de un plano técnico

Después de publicar un plano técnico mediante la API REST, se puede asignar a una suscripción. Asigne el plano técnico que ha creado a una de las suscripciones de la jerarquía de su grupo de administración. Si el proyecto se guarda en una suscripción, solo se puede asignar a dicha suscripción. El elemento Request Body especifica el plano técnico que se asignará y proporciona el nombre y la ubicación a los grupos de recursos de la definición del plano técnico. Request Body también proporciona todos los parámetros definidos en el plano técnico y usados por uno o varios artefactos adjuntos.

En cada URI de API REST, reemplace las siguientes variables por sus propios valores:

{tenantId}: reemplácelo por su identificador de inquilino.
{YourMG}: reemplácelo por el identificador del grupo de administración.
{subscriptionId}: reemplácelo por el identificador de la suscripción.

Proporcione a la entidad de servicio de Azure Blueprints el rol Owner en la suscripción de destino. El elemento AppId es estático (f71766dc-90d9-4b7d-bd9d-4499c4331c3f), pero el identificador de la entidad de servicio varía según el inquilino. Use la siguiente API REST para solicitar detalles del inquilino. Utiliza Graph API de Azure Active Directory, que tiene una autorización diferente.
- URI DE LA API REST
```
GET https://graph.windows.net/{tenantId}/servicePrincipals?api-version=1.6&$filter=appId eq 'f71766dc-90d9-4b7d-bd9d-4499c4331c3f'
```

Ejecute la implementación del plano técnico asignándolo a una suscripción. Dado que los parámetros contributors y owners requieren una matriz de objectIds de las entidades de servicio para que se les conceda la asignación de roles, utilice Graph API de Azure Active Directory para recopilar los elementos objectIds que se utilizarán en el elemento Request Body para sus propios usuarios, grupos o entidades de servicio.

URI DE LA API REST

PUT https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Blueprint/blueprintAssignments/assignMyBlueprint?api-version=2018-11-01-preview

Cuerpo de la solicitud

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

Identidad administrada asignada por el usuario

Una asignación de plano técnico también puede usar una identidad administrada asignada por el usuario. En este caso, la parte identity del cuerpo de la solicitud cambia de la manera siguiente. Reemplace {yourRG} y {userIdentity} por el nombre del grupo de recursos y el nombre de su identidad administrada asignada por el usuario, respectivamente.
```
"identity": {
    "type": "userAssigned",
    "tenantId": "{tenantId}",
    "userAssignedIdentities": {
        "/subscriptions/{subscriptionId}/resourceGroups/{yourRG}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{userIdentity}": {}
    }
},
```
La identidad administrada asignada por el usuario puede estar en cualquier suscripción y grupo de recursos para los que tenga permiso el usuario que asigna el plano técnico.

Importante

Azure Blueprints no administra la identidad administrada asignada por el usuario. Los usuarios son responsables de asignar los roles y permisos necesarios o la asignación del plano técnico producirá un error.

Limpieza de recursos

Cancelación de la asignación de un plano técnico

Puede eliminar un plano de una suscripción. A menudo, la eliminación se realiza cuando ya no son necesarios los recursos de artefacto. Cuando se quita un plano técnico, se omiten los artefactos que se asignaron como parte de ese plano técnico. Para quitar una asignación del plano técnico, use la siguiente operación de la API REST:

URI DE LA API REST

DELETE https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Blueprint/blueprintAssignments/assignMyBlueprint?api-version=2018-11-01-preview

Eliminación de un plano técnico

Para quitar el mismo plano técnico, utilice la siguiente operación de la API REST:

URI DE LA API REST

DELETE https://management.azure.com/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint?api-version=2018-11-01-preview

Pasos siguientes

En este inicio rápido, ha creado, asignado y quitado un plano técnico con la API REST. Para más información sobre Azure Blueprints, vaya el artículo sobre el ciclo de vida de los planos técnicos.

Más información acerca del ciclo de vida del plano técnico

Inicio rápido: Definición y asignación de un plano técnico de Azure con la API de REST

Requisitos previos

Azure Cloud Shell

Introducción a la API de REST

API REST y PowerShell

Creación de un plano técnico

Publicación de un plano técnico

Asignación de un plano técnico

Limpieza de recursos

Cancelación de la asignación de un plano técnico

Eliminación de un plano técnico

Pasos siguientes

Recursos adicionales