CreateUiDefinition.json para experiência de criação de aplicação gerida do Azure

Este documento introduz os conceitos fundamentais do ficheiro createUiDefinition.json . O portal do Azure utiliza este ficheiro para definir a interface do utilizador ao criar uma aplicação gerida.

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": [ ]
    }
}

A CreateUiDefinition contém sempre três propriedades:

  • manipulador
  • versão
  • parâmetros

O manipulador deve ser Microsoft.Azure.CreateUIDefsempre , e a versão mais recente suportada é 0.1.2-preview.

O esquema da propriedade dos parâmetros depende da combinação do manipulador especificado e da versão. Para aplicações geridas, as propriedades suportadas sãoconfig, basicsstepseoutputs. Só se usa config quando é necessário anular o comportamento predefinido do basics passo. As propriedades básicas e de etapas contêm os elementos - como caixas de texto e dropdowns - a serem exibidos no portal do Azure. A propriedade outputs é usada para mapear os valores de saída dos elementos especificados para os parâmetros do modelo Azure Resource Manager.

Incluindo $schema é recomendado, mas opcional. Se especificado, o valor para version deve corresponder à versão dentro do $schema URI.

Pode utilizar um editor JSON para criar o seu createUiDefinition e, em seguida, testá-lo na createUiDefinition Sandbox para pré-visualizar. Para obter mais informações sobre a caixa de areia, consulte a interface do portal para aplicações geridas azure.

Configurar

A config propriedade é opcional. Use-o para anular o comportamento predefinido do passo básico, ou para definir a sua interface como um assistente passo a passo. Se config for usado, é a primeira propriedade na secção de ficheiros createUiDefinition.json.parameters 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 isValid propriedade, escreva uma expressão que se resolva para verdadeiro ou falso. Para o permission imóvel, especifique uma das ações do fornecedor de recursos.

Feiticeiro

A isWizard propriedade permite-lhe exigir validação bem sucedida de cada passo antes de seguir para o passo seguinte. Quando a isWizard propriedade não é especificada, o padrão é falso, e a validação passo a passo não é necessária.

Quando isWizard estiver ativado, definido como verdadeiro, o separador Básicos está disponível e todos os outros separadores estão desativados. Quando o botão Seguinte é selecionado, o ícone do separador indica se a validação de um separador passou ou falhou. Depois de concluídos e validados os campos necessários após o separador, o botão Seguinte permite a navegação para o separador seguinte. Quando todos os separadores passam a validação, pode ir à página 'Rever e Criar' e selecionar o botão Criar para iniciar a implementação.

Tab wizard

Sobrepor-se ao básico

O básico config permite-lhe personalizar o passo básico.

Para description, fornecer uma cadeia ativada por marcação que descreve o seu recurso. O formato e as ligações multi-linha são suportados.

Os subscription elementos e resourceGroup elementos permitem especificar mais validações. A sintaxe para especificar validações é idêntica à validação personalizada para caixa de texto. Também pode especificar permission validações no grupo de subscrição ou recursos.

O controlo de subscrição aceita uma lista de espaços de nome do fornecedor de recursos. Por exemplo, pode especificar Microsoft.Compute. Mostra uma mensagem de erro quando o utilizador seleciona uma subscrição que não suporta o fornecedor de recursos. O erro ocorre quando o fornecedor de recursos não está registado nessa subscrição, e o utilizador não tem permissão para registar o fornecedor de recursos.

O controlo do grupo de recursos tem uma opção para allowExisting. Quando true, os utilizadores podem selecionar grupos de recursos que já possuem recursos. Esta bandeira é mais aplicável aos modelos de solução, onde o comportamento padrão determina que os utilizadores devem selecionar um grupo de recursos novo ou vazio. Na maioria dos outros cenários, especificar esta propriedade não é necessário.

Para location, especificar as propriedades para o controlo de localização que deseja anular. Quaisquer propriedades não ultrapassadas são definidas para os seus valores padrão. resourceTypes aceita uma variedade de cordas que contenham nomes de tipo de recurso totalmente qualificados. As opções de localização são restritas apenas a regiões que suportam os tipos de recursos. allowedValues aceita uma variedade de cordas da região. Apenas essas regiões aparecem no recuo. Pode definir os dois allowedValues e resourceTypes. O resultado é a intersecção de ambas as listas. Por último, a visible propriedade pode ser usada para desativar condicional ou completamente a localização. 

Noções básicas

O passo Basics é o primeiro passo gerado quando o portal do Azure analisa o ficheiro. Por predefinição, o passo básico permite que os utilizadores escolham a subscrição, o grupo de recursos e a localização para implementação.

Basics default

Pode adicionar mais elementos nesta secção. Quando possível, adicione elementos que consultam parâmetros de implantação, como o nome de um cluster ou credenciais de administrador.

O exemplo a seguir mostra uma caixa de texto que foi adicionada aos elementos predefinidos.

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

Passos

A propriedade dos passos contém zero ou mais passos para exibir após o básico. Cada passo contém um ou mais elementos. Considere adicionar passos por função ou nível da aplicação que está a ser implementada. Por exemplo, adicione um passo para as entradas de nó primário, e um passo para os nós operários 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 outputs propriedade para mapear elementos de basics e steps para os parâmetros do modelo de implantação Resource Manager Azure. As teclas deste dicionário são os nomes dos parâmetros do modelo, e os valores são propriedades dos objetos de saída dos elementos referenciados.

Para definir o nome do recurso de aplicação gerido, deve incluir um valor nomeado applicationResourceName na propriedade de saídas. Se não definir este valor, a aplicação atribui um GUID para o nome. Pode incluir uma caixa de texto na interface do utilizador que solicita um nome ao utilizador.

"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 apenas para os locais que suportam os tipos de recursos a implementar, forneça uma matriz dos tipos de recursos. Se fornecer mais de um tipo de recurso, apenas os locais que suportam todos os tipos de recursos são devolvidos. Esta 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

A CreateUiDefinition fornece funções para trabalhar com entradas e saídas de elementos, e funcionalidades como condicionalidades. Estas funções são semelhantes tanto na sintaxe como na funcionalidade do Azure Resource Manager funções do modelo.

Passos seguintes

O ficheiro createUiDefinition.json em si tem um esquema simples. A verdadeira profundidade vem de todos os elementos e funções suportados. Estes itens são descritos com maior detalhe em:

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

Para um ficheiro de interface de utilizador, consulte createUiDefinition.json.