教程：为模板规范创建 Azure 门户表单

可以创建显示在Azure门户中的表单视图，以帮助用户部署模板规格。JSON 中描述了窗体视图;Azure门户从该 JSON 在运行时呈现窗体。有关独立于模板规格的窗体视图的概念性介绍，请参阅窗体视图概述。

创建模板规格时，将表单视图和Azure 资源管理器模板（ARM 模板）打包在一起。通过门户部署模板规范会自动打开表单。

以下屏幕截图显示 Azure 门户中打开的表单。

Azure 门户中用于为模板规范提供值的窗体屏幕截图。

先决条件

具有活动订阅的 Azure 帐户。创建试用版订阅。

对于 Azure PowerShell，请使用版本 6.0.0 或更高版本。对于 Azure CLI，请使用版本 2.24.0 或更高版本。

创建模板

若要显示表单中可用的不同门户元素，需使用具有多个参数的 ARM 模板。以下模板可创建密钥保管库、为用户配置密钥保管库权限，并添加机密。

复制此文件并将其保存在本地。本教程假定你将其命名为“keyvault.json”，但你可以将其命名为任何名称。

{
  "$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": "2025-05-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": "2025-05-01",
      "name": "[format('{0}/{1}', parameters('keyVaultName'), parameters('secretName'))]",
      "dependsOn": [
        "[resourceId('Microsoft.KeyVault/vaults', parameters('keyVaultName'))]"
      ],
      "properties": {
        "value": "[parameters('secretValue')]"
      }
    }
  ]
}

创建默认表单

Azure 门户提供用于创建和预览表单的沙盒。此沙盒可以从现有 ARM 模板呈现表单。使用此默认表单开始为模板规格创建表单。

打开表单视图沙盒。
在Package Type中，选择CustomTemplate。指定部署模板之前，请确保选择了包类型。
在“部署模板(可选)”中，选择本地保存的密钥保管库模板。当系统提示是否要覆盖当前更改时，请选择“是”。自动生成的表单显示在代码窗口中。可以从门户编辑表单。若要自定义表单，请参阅自定义表单。如果仔细查看自动生成的表单，则默认标题为“测试表单视图”。只定义了一个名为基础的步骤。
```
{
  "$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": {
      ...
    }
  }
}
```
若要查看是否无需任何修改即可运行，请选择“预览”。

沙盒显示了表单。它包含用于选择订阅、资源组和区域的字段。它还包含模板中所有参数的字段。

大多数字段是文本框，但某些字段特定于某种类型的参数。如果模板包含参数的允许值，则自动生成的表单使用下拉元素。下拉列表中已预先填入允许的值。

标题和“项目详细信息”之间没有选项卡，因为默认表单只定义了一个步骤。在“自定义表单”部分，需要将参数分入多个选项卡。

警告

不要选择“创建”，因为它会启动实际部署。在本教程的后面部分，你有机会部署模板规格。
若要退出预览状态，请选择“取消”。

自定义表单

默认表单是了解表单的良好起点，但通常需要对其进行自定义。可以在沙盒或 Visual Studio Code 中编辑表单。预览选项仅在沙盒中可用。

为表单提供一个标题，用于说明其用途。

{
  "$schema": "https://schema.management.azure.com/schemas/2021-09-09/uiFormDefinition.schema.json#",
  "view": {
    "kind": "Form",
    "properties": {
      "title": "Key Vault and secret",

默认表单将模板中的所有字段合并到一个名为 Basics 的步骤中。为帮助用户了解他们要提供的值，将表单划分为多个步骤。每个步骤都包含与要部署的解决方案的逻辑部分相关的字段。

找到标记为“基本”的步骤。保留此步骤，但添加侧重于配置密钥保管库、设置用户权限和指定机密的步骤。在基本步骤后面添加一个逗号。

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

重要

表单中的属性区分大小写。请确保使用示例中显示的大小写格式。

选择“预览”。你会看到这些步骤，但大多数步骤不包含任何元素。

将元素移动到相应的步骤。首先从标记为机密名称和机密值的元素开始。将这些元素从基础步骤中移除，并将其添加到密钥步骤中。

{
  "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 部分。目前，输出部分仍按这些元素位于基础步骤中时的方式引用它们。修复语法，使其在 secret 步骤中引用这些元素。
```
"outputs": {
  "parameters": {
    ...
    "secretName": "[steps('secret').secretName]",
    "secretValue": "[steps('secret').secretValue]"
  }
```

继续将元素移动到相应步骤。与其逐个查看，不如查看更新后的表单。

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

将此文件以 keyvaultform.json 为名称保存在本地。

创建模板规格

创建模板规格时，请提供这两个文件。

对于 PowerShell，请使用 New-AzTemplateSpec，并在 -UIFormDefinitionFile 参数中提供表单。

New-AzTemplateSpec `
  -name keyvaultspec `
  -version 1 `
  -ResourceGroupName templateSpecRG `
  -location chinanorth2 `
  -templatefile keyvault.json `
  -UIFormDefinitionFile keyvaultform.json

对于Azure CLI，请使用 az ts create，并在 --ui-form-definition 参数中提供表单。

az ts create \
  --name keyvaultspec \
  --version 1 \
  --resource-group templatespecRG \
  --location chinanorth2 \
  --template-file keyvault.json \
  --ui-form-definition keyvaultform.json

通过门户部署

若要测试表单，请转到门户并导航到模板规格。选择“部署”。

Azure 模板规格概述的屏幕截图，突出显示部署选项。

你会看到自己创建的表单。完成这些步骤并为字段提供值。

在“基本”步骤中，你会看到表示“区域”的字段。此字段用于表示资源组的位置。在“密钥保管库”步骤中，你会看到表示“位置”的字段。此字段用于表示密钥保管库的位置。

在权限步骤中，在“对象 ID”字段中输入你的用户 ID。对于密钥和机密权限，使用默认值 (["list"])。在下一部分中，你会改进该选项。

提供所有这些值之后，选择“创建”以部署模板规格。

改进表单

在上一部分中，你已添加步骤并移动元素，但未更改任何默认行为。在本部分中，你会做出更改，以改进模板规格用户体验。

之前，这两个权限字段是文本框。现在，你使用下拉菜单。将类型设置为 Microsoft.Common.DropDown。

更新keysPermissions：

{
  "name": "keysPermissions",
  "type": "Microsoft.Common.DropDown",

以及 secretsPermissions：

{
  "name": "secretsPermissions",
  "type": "Microsoft.Common.DropDown",

这些字段需要将数组传递给模板。常规下拉列表不起作用，因为你只能选择一个值。若要选择多个值并将这些值作为数组传递，请添加 multiselect 字段，并将其设置为 true。

{
  "name": "keysPermissions",
  "type": "Microsoft.Common.DropDown",
  "label": "Keys Permissions",
  "multiselect": true,

{
  "name": "secretsPermissions",
  "type": "Microsoft.Common.DropDown",
  "label": "Secrets Permissions",
  "multiselect": true,

最后，指定下拉列表的允许值和一个默认值。

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

创建新版本的模板规格。

使用 PowerShell：

New-AzTemplateSpec `
  -name keyvaultspec `
  -version 2 `
  -ResourceGroupName templateSpecRG `
  -location chinanorth2 `
  -templatefile keyvault.json `
  -UIFormDefinitionFile keyvaultform.json

或 Azure CLI：

az ts create \
  --name keyvaultspec \
  --version 2 \
  --resource-group templatespecRG \
  --location chinanorth2 \
  --template-file keyvault.json \
  --ui-form-definition keyvaultform.json

使用改进的门户表单重新部署模板规格。

用于为模板规范提供值的 Azure 门户表单的屏幕截图。

请注意，权限字段现在是允许多个值的下拉列表。

后续步骤

有关窗体视图的概念性介绍，请参阅窗体视图概述。
有关支持控件的完整列表，请参阅窗体视图元素。
若要了解如何将模板规格部署为链接模板，请参阅教程：将模板规格部署为链接模板。

Last updated on 2026-07-02