Tutorial: Criar formulários de portal do Azure para uma especificação de modelo
Pode criar um formulário que aparece no portal do Azure para ajudar os utilizadores a implementar uma especificação de modelo. O formulário permite que os utilizadores introduzam valores que são transmitidos como parâmetros para a especificação do modelo.
Quando cria a especificação de modelo, empacota o formulário e o modelo do Azure Resource Manager (modelo arm) em conjunto. A implementação da especificação do modelo através do portal inicia automaticamente o formulário.
A captura de ecrã seguinte 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 Azure PowerShell, utilize a versão 6.0.0 ou posterior. Para a CLI do Azure, utilize a versão 2.24.0 ou posterior.
Criar o modelo
Para mostrar os diferentes elementos do portal que estão disponíveis num formulário, irá utilizar um modelo do ARM com vários parâmetros. O modelo seguinte cria um cofre de chaves, configura permissões para o cofre de chaves para um utilizador e adiciona um segredo.
Copie este ficheiro e guarde-o localmente. Este tutorial pressupõe que lhe deu o nome keyvault.json , mas 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 predefinido
O portal do Azure fornece um sandbox para criar e pré-visualizar formulários. Este sandbox pode compor um formulário a partir de um modelo do ARM existente. Irá utilizar este formulário predefinido para começar a criar um formulário para as especificações do modelo. Para obter mais informações sobre a estrutura do formulário, veja FormViewType.
Abra o sandbox da vista formulário.
Em Tipo de Pacote, selecione CustomTemplate. Certifique-se de que seleciona o tipo de pacote antes de especificar o modelo de implementação.
Em Modelo de implementação (opcional), selecione o modelo do cofre de chaves que guardou localmente. Quando lhe for pedido para substituir as alterações atuais, selecione Sim. O formulário gerado automaticamente é apresentado na janela de código. O formulário é editável a partir do portal. Para personalizar o formulário, veja Personalizar formulário. Se observar de perto o formulário gerado automaticamente, o título predefinido é denominado Vista de Formulário de Teste e existe apenas um passo denominado 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 que funciona sem modificações, selecione Pré-visualizar.
O sandbox apresenta o formulário. Tem campos para selecionar uma subscrição, um grupo de recursos e uma região. Também faz 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 utiliza um elemento pendente. O elemento pendente é pré-preenchido com os valores permitidos.
Entre o título e os detalhes do Projeto, não existem separadores porque o formulário predefinido tem apenas um passo definido. Na secção Personalizar formulário , irá dividir os parâmetros em vários separadores.
Aviso
Não selecione Criar , pois irá iniciar uma implementação real. Terá a oportunidade de implementar a especificação de modelo mais adiante neste tutorial.
Para sair da pré-visualização, selecione Cancelar.
Personalizar formulário
O formulário predefinido é um bom ponto de partida para compreender formulários, mas normalmente vai querer personalizá-lo. Pode editá-lo no sandbox ou no Visual Studio Code. A opção de pré-visualização só está disponível no sandbox.
Atribua ao formulário um título que descreva a sua utilização.
{ "$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 predefinido tinha todos os campos do modelo combinados num passo denominado Básicos. Para ajudar os utilizadores a compreender os valores que estão a fornecer, divida o formulário em passos. Cada passo contém campos relacionados com uma parte lógica da solução a implementar.
Localize o passo com o nome Básicos. Irá manter este passo, mas adicionar passos abaixo do mesmo. Os novos passos irão focar-se na configuração do cofre de chaves, na definição de permissões de utilizador e na especificação do segredo. Certifique-se de que adiciona uma vírgula após o passo básico.
{ "$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 são sensíveis às maiúsculas e minúsculas. Certifique-se de que utiliza a caixa apresentada nos exemplos.
Selecione Pré-visualizar. Verá os passos, mas a maioria não tem elementos.
Agora, mova os elementos para os passos adequados. Comece com os elementos denominados Nome do Segredo e Valor do Segredo. Remova estes elementos do passo Noções Básicas e adicione-os ao passo 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 } ] }Quando move elementos, tem de corrigir a
outputssecção. Atualmente, a secção de saídas referencia esses elementos como se ainda estivessem no passo básico. Corrija a sintaxe para que faça referência aos elementos nosecretpasso."outputs": { "parameters": { ... "secretName": "[steps('secret').secretName]", "secretValue": "[steps('secret').secretValue]" }Continue a mover elementos para os passos adequados. Em vez de percorrer cada um deles, veja 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]" } } }Guarde este ficheiro localmente com o nome keyvaultform.json.
Criar especificações de modelo
Quando criar a especificação do modelo, forneça ambos os ficheiros.
Para o -UIFormDefinitionFile PowerShell, utilize New-AzTemplateSpec e forneça o 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, utilize az ts create e forneça o formulário no --ui-form-definition parâmetro .
az ts create \
--name keyvaultspec \
--version 1 \
--resource-group templatespecRG \
--location westus2 \
--template-file keyvault.json \
--ui-form-definition keyvaultform.json
Implementar através do portal
Para testar o formulário, aceda ao portal e navegue para as especificações do modelo. Selecione Implementar.
Verá o formulário que criou. Siga os passos e forneça valores para os campos.
No passo Noções básicas , verá um campo para Região. Este campo é utilizado para a localização do grupo de recursos. No passo Key Vault, verá um campo para Localização. Este campo é utilizado para a localização do cofre de chaves.
No passo Permissões , pode fornecer o seu próprio ID de utilizador para o ID do objeto. Utilize o valor predefinido (["list"]) para permissões de chave e segredo. Irá melhorar essa opção na secção seguinte.
Quando terminar de fornecer valores, selecione Criar para implementar a especificação do modelo.
Melhorar o formulário
Na secção anterior, adicionou passos e moveu elementos, mas não alterou nenhum dos comportamentos predefinidos. Nesta secção, irá fazer alterações que melhoram a experiência para os utilizadores das especificações do modelo.
Anteriormente, os dois campos de permissões eram caixas de texto. Agora, vai utilizar um menu pendente. Defina o tipo como Microsoft.Common.DropDown.
Atualização keysPermissions:
{
"name": "keysPermissions",
"type": "Microsoft.Common.DropDown",
E secretsPermissions:
{
"name": "secretsPermissions",
"type": "Microsoft.Common.DropDown",
Estes campos têm de passar uma matriz para o modelo. Uma lista pendente normal não funcionará porque só lhe permite selecionar um valor. Para selecionar mais do que um valor e passá-los como uma matriz, adicione o multiselect campo e defina 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, tem de especificar os valores permitidos para a lista pendente e um valor predefinido.
{
"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 das especificações 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
Reimplemente as especificações do modelo com o formulário de portal melhorado.
Repare que os campos de permissão são agora pendentes que permitem vários valores.
Passos seguintes
Para saber mais sobre como implementar uma especificação de modelo como um modelo ligado, veja Tutorial: Implementar uma especificação de modelo como um modelo ligado.