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

發行項
03/20/2024

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

建立範本規格時，您會將表單和 Azure Resource Manager 範本 (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]。請務必先選取套件類型，再指定部署範本。
在 [部署範本 (選擇性)] 中，選取您在本機儲存的金鑰保存庫範本。當系統提示您是否要覆寫目前的變更時，請選取 [是]。自動產生的表單隨即於程式碼視窗中顯示。表單可從入口網站編輯。若要自訂表單，請參閱自訂表單。如果您仔細查看自動產生的表單，預設標題為 Test Form View (測試表單檢視)，而且僅定義一個名為 basics (基本) 的步驟。
```
{
  "$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": {
      ...
    }
  }
}
```
若要查看其在沒有任何修改的情況下運作，請選取 [預覽]。

沙箱會顯示該表單。其具有選取訂用帳戶、資源群組以及區域的欄位。其也提供來自範本所有參數的欄位。

大部分的欄位都是文字方塊，但有些欄位則是參數類型的特定欄位。如果您的範本包含允許的參數值，自動產生的表單即會使用下拉式元素。下拉式元素會預先填入允許的值。

在標題與 Project details (專案詳細資料) 之間，沒有任何索引標籤，因為預設表單僅定義單一步驟。在 Customize form (自訂表單) 區段中，您必須將參數分成多個索引標籤。

警告

請勿選取 [建立]，因為會啟動實際部署。稍後於本教學課程中，您將有機會部署該範本規格。
若要結束預覽，請選取 [取消]。

自訂表單

預設表單是了解表單的好起點，但您通常會希望能自訂表單。您可以在沙箱或 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

透過入口網站部署

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

Screenshot of Azure template spec overview with deploy option highlighted.

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

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

在 [許可權] 步驟中，您可以為物件識別碼提供您自己的使用者識別碼。使用預設值 (["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

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

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

請注意，您的權限欄位目前為允許多個值的下拉式清單。

下一步

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

Share via