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 a implantar 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 de modelo.
Ao criar a especificação do modelo, você empacota o formulário e o modelo do ARM (modelo do Azure Resource Manager) juntos. A implantação da especificação do modelo por meio 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 assinatura 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 modelo
Para mostrar os diferentes elementos do portal que estão disponíveis em um formulário, você usará um modelo do 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 esse arquivo e salve-o localmente. Este tutorial pressupõe que você tenha nomeado o arquivo keyvault.json, mas você pode dar a ele 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. Essa área restrita pode gerar um formulário de um modelo do ARM existente. Você usará esse 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, confira FormViewType.
Abra a Área restrita de exibição de formulário.
Em Tipo de Pacote, selecione CustomTemplate. Selecione o tipo de pacote antes de especificar o modelo de implantação.
Em Modelo de implantação (opcional), selecione o modelo do cofre de chaves que você salvou localmente. Quando for solicitado se você deseja substituir as alterações atuais, selecione Sim. O formulário gerado automaticamente é exibido na janela de código. O formulário é editável no portal. Para personalizar o formulário, confira personalizar o formulário. Se você examinar atentamente o formulário gerado automaticamente, o título padrão será Exibição de Formulário de Teste e haverá apenas uma etapa definida, chamada noções básicas.
{ "$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 verificar se ele funciona sem modificações, selecione Visualizar.
A área restrita exibe o formulário. Ele tem campos para selecionar uma assinatura, um grupo de recursos e uma 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 o modelo inclui valores permitidos para um parâmetro, o formulário gerado automaticamente usa um elemento de lista suspensa. O elemento de lista suspensa é 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ê dividirá os parâmetros em várias guias.
Aviso
Não selecione Criar, pois isso iniciará uma implantação real. Você terá a chance de implantar a especificação do modelo posteriormente neste tutorial.
Para sair da versão prévia, selecione Cancelar.
Personalizar formulário
O formulário padrão é um bom ponto de partida para entender os formulários, mas geralmente você desejará 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 uso dele.
{ "$schema": "https://schema.management.azure.com/schemas/2021-09-09/uiFormDefinition.schema.json#", "view": { "kind": "Form", "properties": { "title": "Key Vault and secret",Seu formulário padrão tinha todos os campos para seu modelo combinados em uma etapa chamada Noções Básicas. Para ajudar os usuários a entender os valores que eles 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.
Localize a etapa rotulada Noções Básicas. Você manterá essa etapa, mas adicionará etapas abaixo dela. As novas etapas se concentrarão na configuração do cofre de chaves, na definição de permissões de usuário e na especificação do segredo. Certifique-se de adicionar uma vírgula após a etapa de noções básicas.
{ "$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 a maiúsculas e minúsculas conforme mostrado nos exemplos.
Selecione Visualização. Você verá as etapas, mas a maioria delas não terá nenhum elemento.
Agora, mova os elementos para as etapas apropriadas. Comece com os elementos rotulados como 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, você precisa corrigir a seção
outputs. Atualmente, a seção de saídas faz referência a esses elementos como se eles ainda estivessem na etapa de noções básicas. Corrija a sintaxe para que ela faça referência aos elementos na etapasecret."outputs": { "parameters": { ... "secretName": "[steps('secret').secretName]", "secretValue": "[steps('secret').secretValue]" }Continue movendo os elementos para as etapas apropriadas. Em vez de percorrer cada uma, dê uma olhada no 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 esse arquivo localmente com o nome keyvaultform.json.
Criar especificação de modelo
Ao criar a especificação do modelo, forneça os dois arquivos.
Para o PowerShell, use New-AzTemplateSpec e forneça o formulário no parâmetro -UIFormDefinitionFile.
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 formulário no parâmetro --ui-form-definition.
az ts create \
--name keyvaultspec \
--version 1 \
--resource-group templatespecRG \
--location westus2 \
--template-file keyvault.json \
--ui-form-definition keyvaultform.json
Implantar por meio do portal
Para testar o formulário, acesse o portal e navegue até a especificação de modelo. Selecione Implantar.
Você verá 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. Esse campo é usado para o local do grupo de recursos. Na etapa Cofre de Chaves, você verá um campo para Localização. Esse campo é usado para o local do cofre de chaves.
Na etapa Permissões, você pode fornecer uma ID de usuário própria para a ID de objeto. Use o valor padrão (["list"]) para permissões de chave e de segredo. Você aprimorará essa opção na próxima seção.
Depois de fornecer todos os outros valores, selecione Criar para implantar a especificação de modelo.
Aprimorar o formulário
Na seção anterior, você adicionou etapas e moveu os elementos, mas não alterou nenhum dos comportamentos padrão. Nesta seção, você fará alterações que aprimoram a experiência para os usuários da sua especificação de modelo.
Anteriormente, os dois campos de permissões eram caixas de texto. Agora, você usará uma lista suspensa. Defina o tipo como Microsoft.Common.DropDown.
Atualizar 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 funcionará porque só permite selecionar um valor. Para selecionar mais de um valor e passá-los como uma matriz, adicione o campo multiselect 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,
Por fim, você precisa especificar 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
}
Para criar uma nova versão da especificação de 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 a especificação do modelo com o formulário do portal aprimorado.
Observe que os campos de permissão agora são listas suspensas que permitem vários valores.
Próximas etapas
Para saber mais sobre como implantar uma especificação de modelo como um modelo vinculado, veja Tutorial: Implantar uma especificação de modelo como um modelo vinculado.