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

项目
08/14/2023

可以创建在 Azure 门户中显示的表单，帮助用户部署模板规格。通过该表单，用户可以输入作为参数传递到模板规格的值。

创建模板规格时，需将表单与 Azure 资源管理器模板（ARM 模板）一起打包。通过门户部署模板规格会自动启动表单。

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

Screenshot of Azure portal form for providing values to a template spec.

先决条件

具有活动订阅的 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": "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')]"
      }
    }
  ]
}

创建默认表单

Azure 门户提供用于创建和预览表单的沙盒。此沙盒可以从现有 ARM 模板呈现表单。你将使用此默认表单开始为模板规格创建表单。有关表单结构的详细信息，请参阅 FormViewType。

打开表单视图沙盒。
选择“包类型”中的“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",

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

找到标记为“基本”的步骤。你将保留此步骤，但需在此步骤下添加其他步骤。新步骤将主要用于配置密钥保管库、设置用户权限以及指定机密。请确保在基本步骤后添加逗号。

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

通过门户部署

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

Screenshot of Azure template spec overview with deploy option highlighted.

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

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

在“权限”步骤中，可提供你自己的用户 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

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

Screenshot of form to provide values for template spec.

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

后续步骤

若要了解如何将模板规格部署为链接模板，请参阅教程：将模板规格部署为链接模板。