Tutorial: Criar formulários do portal do Azure para uma especificação de modelo
Você pode criar um formulário que aparece no portal do Azure para ajudar os usuários na implantação de uma especificação de modelo. O formulário permite que os usuários insiram valores que são passados como parâmetros para a especificação do modelo.
Ao criar a especificação de modelo, você empacota o formulário e o modelo do Azure Resource Manager (modelo ARM) juntos. A implantação da especificação do modelo através do portal inicia automaticamente o formulário.
A captura de tela a seguir mostra um formulário aberto no portal do Azure.
Pré-requisitos
Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
Para o Azure PowerShell, use a versão 6.0.0 ou posterior. Para a CLI do Azure, use a versão 2.24.0 ou posterior.
Criar o modelo
Para mostrar os diferentes elementos do portal que estão disponíveis em um formulário, use um modelo ARM com vários parâmetros. O modelo a seguir cria um cofre de chaves, configura permissões para o cofre de chaves para um usuário e adiciona um segredo.
Copie este ficheiro e guarde-o localmente. Este tutorial pressupõe que você o nomeou keyvault.json mas você pode dar-lhe qualquer nome.
{
"$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')]"
}
}
]
}
Criar formulário padrão
O portal do Azure fornece uma área restrita para criar e visualizar formulários. Esta área restrita pode renderizar um formulário a partir de um modelo ARM existente. Use este formulário padrão para começar a criar um formulário para sua especificação de modelo. Para obter mais informações sobre a estrutura do formulário, consulte FormViewType.
Abra a área restrita do modo Formulário.
Em Tipo de Pacote, selecione CustomTemplate. Certifique-se de selecionar o tipo de pacote antes de especificar o modelo de implantação.
Em Modelo de implantação (opcional), selecione o modelo de cofre de chaves que você salvou localmente. Quando lhe for perguntado se pretende substituir as alterações atuais, selecione Sim. O formulário gerado automaticamente é exibido na janela de código. Pode editar o formulário a partir do portal. Para personalizar o formulário, consulte Personalizar formulário. Se você observar atentamente o formulário gerado automaticamente, o título padrão é Testar modo de exibição de formulário. Há apenas uma etapa chamada noções básicas definidas.
{ "$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 se funciona sem modificações, selecione Pré-visualizar.
A área restrita exibe o formulário. Ele tem campos para selecionar uma assinatura, grupo de recursos e região. Ele também tem campos para todos os parâmetros do modelo.
A maioria dos campos são caixas de texto, mas alguns campos são específicos para o tipo de parâmetro. Quando seu modelo inclui valores permitidos para um parâmetro, o formulário gerado automaticamente usa um elemento suspenso. O elemento suspenso é preenchido previamente com os valores permitidos.
Entre o título e os detalhes do projeto, não há guias porque o formulário padrão tem apenas uma etapa definida. Na seção Personalizar formulário, você divide os parâmetros em várias guias.
Aviso
Não selecione Criar , pois ele inicia uma implantação real. Você tem a chance de implantar a especificação do modelo mais adiante neste tutorial.
Para sair da visualização, selecione Cancelar.
Personalizar formulário
O formulário padrão é um bom ponto de partida para entender os formulários, mas geralmente você deseja personalizá-lo. Você pode editá-lo na área restrita ou no Visual Studio Code. A opção de visualização só está disponível na área restrita.
Dê ao formulário um título que descreva o seu uso.
{ "$schema": "https://schema.management.azure.com/schemas/2021-09-09/uiFormDefinition.schema.json#", "view": { "kind": "Form", "properties": { "title": "Key Vault and secret",O formulário padrão tinha todos os campos do modelo combinados em uma etapa chamada Noções básicas. Para ajudar os usuários a entender os valores que estão fornecendo, divida o formulário em etapas. Cada etapa contém campos relacionados a uma parte lógica da solução a ser implantada.
Encontre a etapa rotulada como Noções básicas. Mantenha esta etapa, mas adicione etapas que se concentram em configurar o cofre de chaves, definir permissões de usuário e especificar o segredo. Adicione uma vírgula após a etapa básica.
{ "$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
As propriedades no formulário diferenciam maiúsculas de minúsculas. Certifique-se de usar o invólucro mostrado nos exemplos.
Selecione Pré-visualizar. Você vê as etapas, mas a maioria delas não tem nenhum elemento.
Mova os elementos para as etapas apropriadas. Comece com os elementos rotulados Nome Secreto e Valor Secreto. Remova esses elementos da etapa Noções básicas e adicione-os à etapa Segredo.
{ "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 } ] }Ao mover elementos, corrija a
outputsseção. Atualmente, a seção de saídas faz referência a esses elementos como se eles ainda estivessem na etapa básica. Corrija a sintaxe para que ela faça referência aossecretelementos na etapa."outputs": { "parameters": { ... "secretName": "[steps('secret').secretName]", "secretValue": "[steps('secret').secretValue]" }Continue movendo os elementos para as etapas apropriadas. Em vez de passar por cada um, olhe para o formulário atualizado.
{ "$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]" } } }Salve este arquivo localmente com o nome keyvaultform.json.
Criar especificação de modelo
Ao criar a especificação do modelo, forneça ambos os arquivos.
Para PowerShell, use New-AzTemplateSpec e forneça o -UIFormDefinitionFile formulário no parâmetro.
New-AzTemplateSpec `
-name keyvaultspec `
-version 1 `
-ResourceGroupName templateSpecRG `
-location westus2 `
-templatefile keyvault.json `
-UIFormDefinitionFile keyvaultform.json
Para a CLI do Azure, use az ts create e forneça o --ui-form-definition formulário no parâmetro.
az ts create \
--name keyvaultspec \
--version 1 \
--resource-group templatespecRG \
--location westus2 \
--template-file keyvault.json \
--ui-form-definition keyvaultform.json
Implantar através do portal
Para testar o formulário, vá para o portal e navegue até a especificação do modelo.
Você vê o formulário que criou. Percorra as etapas e forneça valores para os campos.
Na etapa Noções básicas, você verá um campo para Região. Este campo é para o local do grupo de recursos. Na etapa Cofre da Chave , você verá um campo para Localização. Este campo refere-se à localização do cofre das chaves.
Na etapa Permissões, forneça sua ID de usuário para a ID do objeto. Use o valor padrão (["list"]) para permissões de chave e segredo. Você melhora essa opção na próxima seção.
Quando terminar de fornecer valores, selecione Criar para implantar a especificação do modelo.
Melhorar o formulário
Na seção anterior, você adicionou etapas e moveu elementos, mas não alterou nenhum dos comportamentos padrão. Nesta seção, você faz alterações que melhoram a experiência dos usuários da especificação do modelo.
Anteriormente, os dois campos de permissões eram caixas de texto. Agora, você usa uma lista suspensa. Defina o tipo como Microsoft.Common.DropDown.
Atualização keysPermissions:
{
"name": "keysPermissions",
"type": "Microsoft.Common.DropDown",
E secretsPermissions:
{
"name": "secretsPermissions",
"type": "Microsoft.Common.DropDown",
Esses campos precisam passar uma matriz para o modelo. Uma lista suspensa regular não funciona porque só permite selecionar um valor. Para selecionar mais de um valor e passá-los como uma matriz, adicione o multiselect campo e defina-o como true.
{
"name": "keysPermissions",
"type": "Microsoft.Common.DropDown",
"label": "Keys Permissions",
"multiselect": true,
{
"name": "secretsPermissions",
"type": "Microsoft.Common.DropDown",
"label": "Secrets Permissions",
"multiselect": true,
Finalmente, especifique os valores permitidos para a lista suspensa e um valor padrão.
{
"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
}
Crie uma nova versão da especificação do modelo.
Com o PowerShell:
New-AzTemplateSpec `
-name keyvaultspec `
-version 2 `
-ResourceGroupName templateSpecRG `
-location westus2 `
-templatefile keyvault.json `
-UIFormDefinitionFile keyvaultform.json
Ou a CLI do Azure:
az ts create \
--name keyvaultspec \
--version 2 \
--resource-group templatespecRG \
--location westus2 \
--template-file keyvault.json \
--ui-form-definition keyvaultform.json
Reimplante sua especificação de modelo com o formulário de portal aprimorado.
Observe que seus campos de permissão agora são menus suspensos que permitem vários valores.
Próximos passos
Para saber mais sobre como implantar uma especificação de modelo como um modelo vinculado, consulte Tutorial: Implantar uma especificação de modelo como um modelo vinculado.