教學課程：為範本規格建立 Azure 入口網站表單

發行項
02/04/2025

您可以建立顯示在 Azure 入口網站中的表單，協助使用者部署範本規格。表單可讓使用者輸入作為參數傳遞給範本規格的值。

建立範本規格時，您會將表單和 Azure Resource Manager 範本 (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": "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 westus2 `
  -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 westus2 \
  --template-file keyvault.json \
  --ui-form-definition keyvaultform.json

透過入口網站部署

若要測試表單，請移至入口網站並瀏覽至您的範本規格。選取 [部署]。

Azure 範本規格概觀的螢幕快照，其中已醒目提示 [部署] 選項。

您會看到您所建立的表單。完成這些步驟，並提供欄位的值。

在 [基本] 步驟中，您會看到 [區域] 欄位。此欄位適用於資源群組的位置。在 金鑰保存庫 步驟中，您會看到 [位置] 欄位。此欄位適用於金鑰儲存庫的位置。

在 [ 許可權] 步驟中，提供對象標識碼的使用者標識碼。使用預設值 (["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 westus2 `
  -templatefile keyvault.json `
  -UIFormDefinitionFile keyvaultform.json

或 Azure CLI：

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

使用改善的入口網站表單，重新部署您的範本規格。

Azure 入口網站表單的螢幕快照，用於提供範本規格的值。

請注意，您的許可權欄位現在是允許多個值的下拉式清單。

下一步

若要了解如何將範本規格部署為連結的範本，請參閱教學課程：將範本規格部署為連結的範本。

共用方式為