CreateUiDefinition.json para a experiência de criação do aplicativo gerenciado do Azure

Este documento apresenta os conceitos básicos do arquivo createUiDefinition.json. O portal do Azure usa este arquivo para definir a interface do usuário durante a criação de um aplicativo gerenciado.

O modelo é o seguinte

{
  "$schema": "https://schema.management.azure.com/schemas/0.1.2-preview/CreateUIDefinition.MultiVm.json#",
  "handler": "Microsoft.Azure.CreateUIDef",
  "version": "0.1.2-preview",
  "parameters": {
    "config": {
      "isWizard": false,
      "basics": {}
    },
    "basics": [],
    "steps": [],
    "outputs": {},
    "resourceTypes": []
  }
}

Um arquivo createUiDefinition.json sempre contém três propriedades:

• handler
• version
• parameters

O manipulador deve sempre ser Microsoft.Azure.CreateUIDef, e a versão mais recente com suporte é 0.1.2-preview.

O esquema da propriedade parameters depende da combinação do manipulador e da versão especificados. Para aplicativos gerenciados, as propriedades com suporte são config, basics, steps e outputs. Use config somente quando precisar substituir o comportamento padrão da etapa basics. As propriedades basic e steps contêm os elementos, como caixas de texto e listas suspensas, que serão exibidos no portal do Azure. A propriedade saídas é usada para mapear os valores de saída de elementos especificados para os parâmetros do modelo do ARM.

A inclusão de $schema é opcional, mas recomendada. Se especificado, o valor de version deve corresponder à versão dentro do URI $schema.

Você pode usar um editor de JSON para criar seu createUiDefinition e testá-lo na Área Restrita do createUiDefinition para visualizá-lo. Confira mais informações sobre a área restrita em Testar sua interface do portal para Aplicativos Gerenciados do Azure.

Config

A propriedade config é opcional. Use-a para substituir o comportamento padrão da etapa básica ou para definir a interface como um assistente passo a passo. Se config for usada, será a primeira propriedade na seção parameters do arquivo createUiDefinition.json. O exemplo a seguir mostra as propriedades disponíveis.

"config": {
  "isWizard": false,
  "basics": {
    "description": "Customized description with **markdown**, see [more](https://www.microsoft.com).",
    "subscription": {
      "constraints": {
        "validations": [
          {
            "isValid": "[not(contains(subscription().displayName, 'Test'))]",
            "message": "Can't use test subscription."
          },
          {
            "permission": "Microsoft.Compute/virtualmachines/write",
            "message": "Must have write permission for the virtual machine."
          },
          {
            "permission": "Microsoft.Compute/virtualMachines/extensions/write",
            "message": "Must have write permission for the extension."
          }
        ]
      },
      "resourceProviders": [
        "Microsoft.Compute"
      ]
    },
    "resourceGroup": {
      "constraints": {
        "validations": [
          {
            "isValid": "[not(contains(resourceGroup().name, 'test'))]",
            "message": "Resource group name can't contain 'test'."
          }
        ]
      },
      "allowExisting": true
    },
    "location": {
      "label": "Custom label for location",
      "toolTip": "provide a useful tooltip",
      "resourceTypes": [
        "Microsoft.Compute/virtualMachines"
      ],
      "allowedValues": [
        "eastus",
        "westus2"
      ],
      "visible": true
    }
  }
},

Para a propriedade isValid, escreva uma expressão que seja resolvida como verdadeira ou falsa. Para a propriedade permission, especifique uma das ações do provedor de recursos.

Assistente

A propriedade isWizard permite que você exija uma validação bem-sucedida de cada etapa antes de prosseguir para a próxima etapa. Quando a propriedade isWizard não é especificada, o padrão é falso e a validação passo a passo não é necessária.

Quando isWizard está habilitada, defina como verdadeiro, a guia Noções Básicas está disponível, e todas as outras guias estão desabilitadas. Quando o botão Avançar é selecionado, o ícone da guia indica se a validação de uma guia foi aprovada ou falhou. Depois que os campos obrigatórios de uma guia estão concluídos e validados, o botão Avançar permite a navegação para a próxima guia. Quando todas as guias são aprovadas na validação, você pode ir para a página Examinar e Criar e selecionar o botão Criar para iniciar a implantação.

Noções básicas de substituição

A configuração de noções básicas permite que você personalize a etapa básica.

Para description, forneça uma cadeia de caracteres habilitada para markdown que descreva seu recurso. Há suporte para formato e links de várias linhas.

Os elementos subscription eresourceGroup permitem especificar mais validações. A sintaxe para especificar validações é idêntica à validação personalizada para a caixa de texto. Você também pode especificar validações de permission na assinatura ou no grupo de recursos.

O controle de assinatura aceita uma lista de namespaces do provedor de recursos. Por exemplo, você pode especificar Microsoft.Compute. Ele mostra uma mensagem de erro quando o usuário seleciona uma assinatura que não dá suporte ao provedor de recursos. O erro ocorre quando o provedor de recursos não está registrado nessa assinatura e o usuário não tem permissão para registrar o provedor de recursos.

O controle do grupo de recursos tem uma opção para allowExisting. Quando true, os usuários podem selecionar grupos de recursos que já têm recursos. Esse sinalizador é mais aplicável aos modelos de solução, em que o comportamento padrão exige que os usuários selecionem um grupo de recursos novo ou vazio. Na maioria dos outros cenários, a especificação dessa propriedade não é necessária.

Para location, especifique as propriedades para o controle de localização que você deseja substituir. Todas as propriedades não substituídas são definidas com seus valores padrão. resourceTypes aceita uma matriz de cadeias de caracteres que contêm nomes de tipo de recurso totalmente qualificados. As opções de local são restritas apenas a regiões que dão suporte aos tipos de recursos. allowedValues aceita uma matriz de cadeias de caracteres de região. Apenas essas regiões aparecem na lista suspensa. Você pode definir allowedValues e resourceTypes. O resultado é a interseção de ambas as listas. Por fim, a propriedade visible pode ser usada para desabilitar de modo condicional ou completo a lista suspensa local. 

Noções básicas

A etapa Noções Básicas é a primeira etapa gerada quando o portal do Azure analisa o arquivo. Por padrão, a etapa Noções Básicas permite que os usuários escolham a assinatura, o grupo de recursos e o local para implantação.

Você pode adicionar mais elementos nesta seção. Quando possível, adicione elementos que consultem parâmetros de toda a implantação, como nome de um cluster ou credenciais de administrador.

O exemplo a seguir mostra uma caixa de texto que foi adicionada aos elementos padrão.

"basics": [
  {
    "name": "textBox1",
    "type": "Microsoft.Common.TextBox",
    "label": "Textbox on basics",
    "defaultValue": "my text value",
    "toolTip": "",
    "visible": true
  }
]

Etapas

As etapas propriedade contêm zero ou mais etapas para exibir depois das noções básicas. Cada etapa contém um ou mais elementos. Considere adicionar etapas por função ou camada do aplicativo que está sendo implantado. Por exemplo, adicione uma etapa nas entradas para os nós mestres e uma etapa para os nós de trabalho em um cluster.

"steps": [
  {
    "name": "demoConfig",
    "label": "Configuration settings",
    "elements": [
       ui-elements-needed-to-create-the-instance
    ]
  }
]

Saídas

O portal do Azure usa a propriedade outputs para mapear os elementos de basics e steps para os parâmetros do modelo de implantação do Azure Resource Manager. As chaves do dicionário são os nomes dos parâmetros do modelo, e os valores são propriedades dos objetos da saída dos elementos referenciados.

Para definir o nome de recurso do aplicativo gerenciado, inclua um valor chamado applicationResourceName na propriedade outputs. Se você não definir esse valor, o aplicativo atribuirá um GUID para o nome. Você pode incluir uma caixa de texto na interface do usuário que solicita um nome de usuário.

"outputs": {
  "vmName": "[steps('appSettings').vmName]",
  "trialOrProduction": "[steps('appSettings').trialOrProd]",
  "userName": "[steps('vmCredentials').adminUsername]",
  "pwd": "[steps('vmCredentials').vmPwd.password]",
  "applicationResourceName": "[steps('appSettings').vmName]"
}

Tipos de recurso

Para filtrar os locais disponíveis somente para os locais que dão suporte aos tipos de recursos a serem implantados, forneça uma matriz dos tipos de recursos. Se você fornecer mais de um tipo de recurso, somente os locais que dão suporte a todos os tipos de recursos serão retornados. Essa propriedade é opcional.

{
  "$schema": "https://schema.management.azure.com/schemas/0.1.2-preview/CreateUIDefinition.MultiVm.json#",
  "handler": "Microsoft.Azure.CreateUIDef",
  "version": "0.1.2-preview",
  "parameters": {
    "resourceTypes": [
      "Microsoft.Compute/disks"
    ],
    "basics": [
        ...

Funções

O CreateUiDefinition fornece funções para trabalhar com entradas e saídas de elementos e recursos como condicionais. Essas funções são semelhantes na sintaxe e na funcionalidade para as funções de modelo do Azure Resource Manager.

Próximas etapas

O próprio arquivo createUiDefinition.json tem um esquema simples. A profundidade real dele é proveniente de todos os elementos e funções com suporte. Esses itens são descritos mais detalhadamente em:

• Elementos
• Funções

Um esquema JSON atual para createUiDefinition está disponível aqui: https://schema.management.azure.com/schemas/0.1.2-preview/CreateUIDefinition.MultiVm.json.

Para ver um arquivo de interface do usuário de exemplo, consulte createUiDefinition.json.