Tutorial: Creación de formularios de Azure Portal para una especificación de plantilla
Puede crear un formulario que aparezca en Azure Portal para ayudar a los usuarios a implementar una especificación de plantilla. El formulario permite a los usuarios especificar valores que se pasan como parámetros a la especificación de plantilla.
Al crear la especificación de plantilla, se empaquetan el formulario y la plantilla de Azure Resource Manager conjuntamente. La implementación de la especificación de plantilla a través del portal inicia el formulario automáticamente.
En la captura de pantalla siguiente se muestra un formulario abierto en Azure Portal.
Requisitos previos
Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
En Azure PowerShell, use la versión 6.0.0, o cualquier versión posterior. En la CLI de Azure, use la versión 2.24.0, o cualquier versión posterior.
Creación de una plantilla
Para mostrar los diferentes elementos del portal que están disponibles en un formulario, usará una plantilla de Resource Manager con varios parámetros. La siguiente plantilla crea un almacén de claves, configura los permisos para el almacén de claves para un usuario y agrega un secreto.
Copie este archivo y guárdelo localmente. En este tutorial se supone que le ha asignado el nombre keyvault.json, pero puede darle cualquier otro.
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"keyVaultName": {
"type": "string",
"metadata": {
"description": "Specifies the name of the key vault."
}
},
"location": {
"type": "string",
"defaultValue": "[resourceGroup().location]",
"metadata": {
"description": "Specifies the Azure location where the key vault should be created."
}
},
"enabledForDeployment": {
"type": "bool",
"defaultValue": false,
"allowedValues": [
true,
false
],
"metadata": {
"description": "Specifies whether Azure Virtual Machines are permitted to retrieve certificates stored as secrets from the key vault."
}
},
"enabledForDiskEncryption": {
"type": "bool",
"defaultValue": false,
"allowedValues": [
true,
false
],
"metadata": {
"description": "Specifies whether Azure Disk Encryption is permitted to retrieve secrets from the vault and unwrap keys."
}
},
"enabledForTemplateDeployment": {
"type": "bool",
"defaultValue": false,
"allowedValues": [
true,
false
],
"metadata": {
"description": "Specifies whether Azure Resource Manager is permitted to retrieve secrets from the key vault."
}
},
"tenantId": {
"type": "string",
"defaultValue": "[subscription().tenantId]",
"metadata": {
"description": "Specifies the Azure Active Directory tenant ID that should be used for authenticating requests to the key vault. Get it by using Get-AzSubscription cmdlet."
}
},
"objectId": {
"type": "string",
"metadata": {
"description": "Specifies the object ID of a user, service principal or security group in the Azure Active Directory tenant for the vault. The object ID must be unique for the list of access policies. Get it by using Get-AzADUser or Get-AzADServicePrincipal cmdlets."
}
},
"keysPermissions": {
"type": "array",
"defaultValue": [
"list"
],
"metadata": {
"description": "Specifies the permissions to keys in the vault. Valid values are: all, encrypt, decrypt, wrapKey, unwrapKey, sign, verify, get, list, create, update, import, delete, backup, restore, recover, and purge."
}
},
"secretsPermissions": {
"type": "array",
"defaultValue": [
"list"
],
"metadata": {
"description": "Specifies the permissions to secrets in the vault. Valid values are: all, get, list, set, delete, backup, restore, recover, and purge."
}
},
"skuName": {
"type": "string",
"defaultValue": "standard",
"allowedValues": [
"standard",
"premium"
],
"metadata": {
"description": "Specifies whether the key vault is a standard vault or a premium vault."
}
},
"secretName": {
"type": "string",
"metadata": {
"description": "Specifies the name of the secret that you want to create."
}
},
"secretValue": {
"type": "secureString",
"metadata": {
"description": "Specifies the value of the secret that you want to create."
}
}
},
"resources": [
{
"type": "Microsoft.KeyVault/vaults",
"apiVersion": "2022-07-01",
"name": "[parameters('keyVaultName')]",
"location": "[parameters('location')]",
"properties": {
"enabledForDeployment": "[parameters('enabledForDeployment')]",
"enabledForDiskEncryption": "[parameters('enabledForDiskEncryption')]",
"enabledForTemplateDeployment": "[parameters('enabledForTemplateDeployment')]",
"tenantId": "[parameters('tenantId')]",
"accessPolicies": [
{
"objectId": "[parameters('objectId')]",
"tenantId": "[parameters('tenantId')]",
"permissions": {
"keys": "[parameters('keysPermissions')]",
"secrets": "[parameters('secretsPermissions')]"
}
}
],
"sku": {
"name": "[parameters('skuName')]",
"family": "A"
},
"networkAcls": {
"defaultAction": "Allow",
"bypass": "AzureServices"
}
}
},
{
"type": "Microsoft.KeyVault/vaults/secrets",
"apiVersion": "2022-07-01",
"name": "[format('{0}/{1}', parameters('keyVaultName'), parameters('secretName'))]",
"dependsOn": [
"[resourceId('Microsoft.KeyVault/vaults', parameters('keyVaultName'))]"
],
"properties": {
"value": "[parameters('secretValue')]"
}
}
]
}
Creación de un formulario predeterminado
Azure Portal proporciona un espacio aislado para crear y obtener una vista previa de los formularios. Este espacio aislado puede generar un formulario a partir de una plantilla de ARM existente. Usará este formulario predeterminado para empezar a crear un formulario para la especificación de plantilla. Para obtener más información sobre la estructura del formulario, vea FormViewType.
Abra el espacio aislado de vista de formulario.
En Tipo de paquete, seleccione CustomTemplate. Asegúrese de seleccionar el tipo de paquete antes de especificar la plantilla de implementación.
En Plantilla de implementación (opcional), seleccione la plantilla del almacén de claves que guardó localmente. Cuando se le pregunte si desea sobrescribir los cambios actuales, seleccione Yes (Sí). El formulario generado automáticamente se muestra en la ventana de código. El formulario se puede editar desde el portal. Para personalizar el formulario, consulte Personalización de formularios. Si examina detenidamente el formulario generado automáticamente, verá que el título predeterminado se denomina Vista de formulario de prueba y solo hay un paso denominado conceptos básicos definidos.
{ "$schema": "https://schema.management.azure.com/schemas/2021-09-09/uiFormDefinition.schema.json", "view": { "kind": "Form", "properties": { "title": "Test Form View", "steps": [ { "name": "basics", "label": "Basics", "elements": [ ... ] } ] }, "outputs": { ... } } }Para ver que funciona sin modificaciones, seleccione Vista previa.
El espacio aislado muestra el formulario. Tiene campos para seleccionar una suscripción, un grupo de recursos y una región. También tiene campos para todos los parámetros de la plantilla.
La mayoría de los campos son cuadros de texto, pero algunos de ellos son específicos para el tipo de parámetro. Cuando la plantilla incluye valores permitidos para un parámetro, el formulario generado automáticamente utiliza un elemento desplegable. El elemento desplegable se ha rellenado previamente con los valores permitidos.
Entre el título y Detalles del proyecto, no hay pestañas porque el formulario predeterminado solo tiene un paso definido. En la sección Personalización de formularios, dividirá los parámetros en varias pestañas.
Advertencia
No seleccione Create (Crear), ya que iniciará una implementación real. Tendrá la oportunidad de implementar la especificación de plantilla más adelante en este tutorial.
Para salir de la versión preliminar, seleccione Cancelar.
Personalización del formulario
El formulario predeterminado es un buen punto de partida para conocer los formularios, pero es habitual que se desee personalizar. Se puede editar en el espacio aislado o en Visual Studio Code. La opción de vista previa solo está disponible en el espacio aislado.
Dé al formulario un título que describa su uso.
{ "$schema": "https://schema.management.azure.com/schemas/2021-09-09/uiFormDefinition.schema.json#", "view": { "kind": "Form", "properties": { "title": "Key Vault and secret",El formulario predeterminado tenía todos los campos de la plantilla combinados en un paso denominado Aspectos básicos. Para ayudar a los usuarios a conocer los valores que proporcionan, divida el formulario en pasos. Cada uno de ellos paso contiene campos relacionados con una parte lógica de la solución que se va a implementar.
Busque el paso con la etiqueta Basics (Aspectos básicos). Mantendrá este paso, pero agregará los pasos siguientes. Los nuevos pasos se centrarán en configurar el almacén de claves, establecer los permisos de usuario y especificar el secreto. Asegúrese de agregar una coma después del paso de aspectos básicos.
{ "$schema": "https://schema.management.azure.com/schemas/2021-09-09/uiFormDefinition.schema.json#", "view": { "kind": "Form", "properties": { "title": "Key Vault and secret", "steps": [ { "name": "basics", "label": "Basics", "elements": [ ... ] }, { "name": "keyvault", "label": "Key Vault", "elements": [ ] }, { "name": "permissions", "label": "Permissions", "elements": [ ] }, { "name": "secret", "label": "Secret", "elements": [ ] } ] }, "outputs": { ... } } }Importante
Las propiedades del formulario distinguen mayúsculas de minúsculas. Asegúrese de usar las mayúsculas y minúsculas como se muestra en los ejemplos.
Seleccione Vista previa. Verá los pasos, pero la mayoría de ellos no tienen ningún elemento.
Ahora, mueva los elementos a los pasos adecuados. Comience por los elementos con la etiqueta Secret Name (Nombre del secreto) y Secret Value (Valor del secreto). Quite estos elementos del paso Basics (Aspectos básicos) y agréguelos al paso Secret (Secreto).
{ "name": "secret", "label": "Secret", "elements": [ { "name": "secretName", "type": "Microsoft.Common.TextBox", "label": "Secret Name", "defaultValue": "", "toolTip": "Specifies the name of the secret that you want to create.", "constraints": { "required": true, "regex": "", "validationMessage": "" }, "visible": true }, { "name": "secretValue", "type": "Microsoft.Common.PasswordBox", "label": { "password": "Secret Value", "confirmPassword": "Confirm password" }, "toolTip": "Specifies the value of the secret that you want to create.", "constraints": { "required": true, "regex": "", "validationMessage": "" }, "options": { "hideConfirmation": true }, "visible": true } ] }Al mover elementos, debe reparar la sección
outputs. Actualmente, la sección de salidas hace referencia a esos elementos como si estuvieran en el paso de aspectos básicos. Corrija la sintaxis para que haga referencia a los elementos del pasosecret."outputs": { "parameters": { ... "secretName": "[steps('secret').secretName]", "secretValue": "[steps('secret').secretValue]" }Siga moviendo los elementos a los pasos adecuados. En lugar de pasar por cada uno de ellos, examine el formulario actualizado.
{ "$schema": "https://schema.management.azure.com/schemas/2021-09-09/uiFormDefinition.schema.json#", "view": { "kind": "Form", "properties": { "title": "Key Vault and secret", "steps": [ { "name": "basics", "label": "Basics", "elements": [ { "name": "resourceScope", "type": "Microsoft.Common.ResourceScope", "location": { "resourceTypes": [ "microsoft.resources/resourcegroups" ] } } ] }, { "name": "keyvault", "label": "Key Vault", "elements": [ { "name": "keyVaultName", "type": "Microsoft.Common.TextBox", "label": "Key Vault Name", "defaultValue": "", "toolTip": "Specifies the name of the key vault.", "constraints": { "required": true, "regex": "", "validationMessage": "" }, "visible": true }, { "name": "skuName", "type": "Microsoft.Common.DropDown", "label": "Sku Name", "defaultValue": "Standard", "toolTip": "Specifies whether the key vault is a standard vault or a premium vault.", "constraints": { "required": false, "allowedValues": [ { "label": "Standard", "value": "Standard" }, { "label": "Premium", "value": "Premium" } ] }, "visible": true }, { "name": "location", "type": "Microsoft.Common.TextBox", "label": "Location", "defaultValue": "[[resourceGroup().location]", "toolTip": "Specifies the Azure location where the key vault should be created.", "constraints": { "required": false, "regex": "", "validationMessage": "" }, "visible": true }, { "name": "enabledForDeployment", "type": "Microsoft.Common.DropDown", "label": "Enabled For Deployment", "defaultValue": "false", "toolTip": "Specifies whether Azure Virtual Machines are permitted to retrieve certificates stored as secrets from the key vault.", "constraints": { "required": false, "allowedValues": [ { "label": "true", "value": true }, { "label": "false", "value": false } ] }, "visible": true }, { "name": "enabledForDiskEncryption", "type": "Microsoft.Common.DropDown", "label": "Enabled For Disk Encryption", "defaultValue": "false", "toolTip": "Specifies whether Azure Disk Encryption is permitted to retrieve secrets from the vault and unwrap keys.", "constraints": { "required": false, "allowedValues": [ { "label": "true", "value": true }, { "label": "false", "value": false } ] }, "visible": true }, { "name": "enabledForTemplateDeployment", "type": "Microsoft.Common.DropDown", "label": "Enabled For Template Deployment", "defaultValue": "false", "toolTip": "Specifies whether Azure Resource Manager is permitted to retrieve secrets from the key vault.", "constraints": { "required": false, "allowedValues": [ { "label": "true", "value": true }, { "label": "false", "value": false } ] }, "visible": true } ] }, { "name": "permissions", "label": "Permissions", "elements": [ { "name": "tenantId", "type": "Microsoft.Common.TextBox", "label": "Tenant Id", "defaultValue": "[[subscription().tenantId]", "toolTip": "Specifies the Azure Active Directory tenant ID that should be used for authenticating requests to the key vault. Get it by using Get-AzSubscription cmdlet.", "constraints": { "required": false, "regex": "", "validationMessage": "" }, "visible": true }, { "name": "objectId", "type": "Microsoft.Common.TextBox", "label": "Object Id", "defaultValue": "", "toolTip": "Specifies the object ID of a user, service principal or security group in the Azure Active Directory tenant for the vault. The object ID must be unique for the list of access policies. Get it by using Get-AzADUser or Get-AzADServicePrincipal cmdlets.", "constraints": { "required": true, "regex": "", "validationMessage": "" }, "visible": true }, { "name": "keysPermissions", "type": "Microsoft.Common.TextBox", "label": "Keys Permissions", "defaultValue": "[[\"list\"]", "toolTip": "Specifies the permissions to keys in the vault. Valid values are: all, encrypt, decrypt, wrapKey, unwrapKey, sign, verify, get, list, create, update, import, delete, backup, restore, recover, and purge.", "constraints": { "required": false, "regex": "", "validationMessage": "" }, "visible": true }, { "name": "secretsPermissions", "type": "Microsoft.Common.TextBox", "label": "Secrets Permissions", "defaultValue": "[[\"list\"]", "toolTip": "Specifies the permissions to secrets in the vault. Valid values are: all, get, list, set, delete, backup, restore, recover, and purge.", "constraints": { "required": false, "regex": "", "validationMessage": "" }, "visible": true } ] }, { "name": "secret", "label": "Secret", "elements": [ { "name": "secretName", "type": "Microsoft.Common.TextBox", "label": "Secret Name", "defaultValue": "", "toolTip": "Specifies the name of the secret that you want to create.", "constraints": { "required": true, "regex": "", "validationMessage": "" }, "visible": true }, { "name": "secretValue", "type": "Microsoft.Common.PasswordBox", "label": { "password": "Secret Value", "confirmPassword": "Confirm password" }, "toolTip": "Specifies the value of the secret that you want to create.", "constraints": { "required": true, "regex": "", "validationMessage": "" }, "options": { "hideConfirmation": true }, "visible": true } ] } ] }, "outputs": { "parameters": { "keyVaultName": "[steps('keyvault').keyVaultName]", "location": "[steps('keyvault').location]", "enabledForDeployment": "[steps('keyvault').enabledForDeployment]", "enabledForDiskEncryption": "[steps('keyvault').enabledForDiskEncryption]", "enabledForTemplateDeployment": "[steps('keyvault').enabledForTemplateDeployment]", "tenantId": "[steps('permissions').tenantId]", "objectId": "[steps('permissions').objectId]", "keysPermissions": "[steps('permissions').keysPermissions]", "secretsPermissions": "[steps('permissions').secretsPermissions]", "skuName": "[steps('keyvault').skuName]", "secretName": "[steps('secret').secretName]", "secretValue": "[steps('secret').secretValue]" }, "kind": "ResourceGroup", "location": "[steps('basics').resourceScope.location.name]", "resourceGroupId": "[steps('basics').resourceScope.resourceGroup.id]" } } }Guarde este archivo localmente con el nombre keyvaultform.json.
Crear una especificación de plantilla
Al crear la especificación de plantilla, indique ambos archivos.
En el caso de PowerShell, use New-AzTemplateSpec y especifique el formulario en el parámetro -UIFormDefinitionFile.
New-AzTemplateSpec `
-name keyvaultspec `
-version 1 `
-ResourceGroupName templateSpecRG `
-location westus2 `
-templatefile keyvault.json `
-UIFormDefinitionFile keyvaultform.json
En el caso de la CLI de Azure, use az ts create y especifique el formulario en el parámetro --ui-form-definition.
az ts create \
--name keyvaultspec \
--version 1 \
--resource-group templatespecRG \
--location westus2 \
--template-file keyvault.json \
--ui-form-definition keyvaultform.json
Implementación mediante el portal
Para probar el formulario, vaya al portal y, después, a la especificación de plantilla. Seleccione Deploy (Implementar).
Verá el formulario que ha creado. Siga los pasos y especifique los valores adecuados en los distintos campos.
En el paso Basics (Aspectos básicos), verá un campo para Region (Región). Este campo se usa para la ubicación del grupo de recursos. En el paso Key Vault (Almacén de claves), verá un campo para Location (Ubicación). Este campo se usa para la ubicación del almacén de claves.
En el paso Permissions (Permisos), puede especificar su propio identificador de usuario para el identificador de objeto. Use el valor predeterminado (["list"]) para los permisos de clave y secreto. Mejorará esa opción en la sección siguiente.
Cuando haya terminado de especificar valores, seleccione Create (Crear) para implementar la especificación de plantilla.
Mejora del formulario
En la sección anterior, agregó pasos y movió elementos, pero no cambió ninguno de los comportamientos predeterminados. En esta sección, realizará cambios que mejoran la experiencia de los usuarios de la especificación de plantilla.
Anteriormente, los dos campos de permisos eran cuadros de texto. Ahora, usará una lista desplegable. Establezca el tipo en Microsoft.Common.DropDown.
Actualice keysPermissions:
{
"name": "keysPermissions",
"type": "Microsoft.Common.DropDown",
Y secretsPermissions:
{
"name": "secretsPermissions",
"type": "Microsoft.Common.DropDown",
Estos campos deben pasar una matriz a la plantilla. Una lista desplegable normal no funcionará porque solo le permite seleccionar un valor. Para seleccionar más de un valor y pasarlos como una matriz, agregue el campo multiselect y establézcalo en true.
{
"name": "keysPermissions",
"type": "Microsoft.Common.DropDown",
"label": "Keys Permissions",
"multiselect": true,
{
"name": "secretsPermissions",
"type": "Microsoft.Common.DropDown",
"label": "Secrets Permissions",
"multiselect": true,
Por último, debe especificar los valores permitidos para la lista desplegable y un valor predeterminado.
{
"name": "keysPermissions",
"type": "Microsoft.Common.DropDown",
"label": "Keys Permissions",
"multiselect": true,
"defaultValue":{
"value": "list"
},
"toolTip": "Specifies the permissions to keys in the vault. Valid values are: all, encrypt, decrypt, wrapKey, unwrapKey, sign, verify, get, list, create, update, import, delete, backup, restore, recover, and purge.",
"constraints": {
"required": false,
"allowedValues":[
{
"label": "all",
"value": "all"
},
{
"label": "encrypt",
"value": "encrypt"
},
{
"label": "decrypt",
"value": "decrypt"
},
{
"label": "list",
"value": "list"
},
{
"label": "delete",
"value": "delete"
},
{
"label": "backup",
"value": "backup"
},
{
"label": "restore",
"value": "restore"
},
{
"label": "recover",
"value": "recover"
},
{
"label": "purge",
"value": "purge"
},
{
"label": "wrapKey",
"value": "wrapKey"
},
{
"label": "unwrapKey",
"value": "unwrapKey"
},
{
"label": "sign",
"value": "sign"
},
{
"label": "verify",
"value": "verify"
},
{
"label": "get",
"value": "get"
},
{
"label": "create",
"value": "create"
},
{
"label": "update",
"value": "update"
},
{
"label": "import",
"value": "import"
}
]
},
"visible": true
},
{
"name": "secretsPermissions",
"type": "Microsoft.Common.DropDown",
"label": "Secrets Permissions",
"multiselect": true,
"defaultValue":{
"value": "list"
},
"toolTip": "Specifies the permissions to secrets in the vault. Valid values are: all, get, list, set, delete, backup, restore, recover, and purge.",
"constraints": {
"required": false,
"allowedValues":[
{
"label": "all",
"value": "all"
},
{
"label": "get",
"value": "get"
},
{
"label": "list",
"value": "list"
},
{
"label": "set",
"value": "set"
},
{
"label": "delete",
"value": "delete"
},
{
"label": "backup",
"value": "backup"
},
{
"label": "restore",
"value": "restore"
},
{
"label": "recover",
"value": "recover"
},
{
"label": "purge",
"value": "purge"
}
]
},
"visible": true
}
Cree una versión de la especificación de plantilla.
Con PowerShell:
New-AzTemplateSpec `
-name keyvaultspec `
-version 2 `
-ResourceGroupName templateSpecRG `
-location westus2 `
-templatefile keyvault.json `
-UIFormDefinitionFile keyvaultform.json
O la CLI de Azure:
az ts create \
--name keyvaultspec \
--version 2 \
--resource-group templatespecRG \
--location westus2 \
--template-file keyvault.json \
--ui-form-definition keyvaultform.json
Vuelva a implementar la especificación de plantilla con el formulario del portal mejorado.
Observe que los campos de permiso ahora son una lista desplegable que permite varios valores.
Pasos siguientes
Para información sobre la implementación de una especificación de plantilla como una plantilla vinculada, consulte Tutorial: Implementación de una especificación de plantilla como una plantilla vinculada.