Использование файла CreateUiDefinition.json для создания управляемого приложения Azure

Статья
06/01/2023

В этом документе описывается назначение файла createUiDefinition.json. На основе этого файла портал Azure определяет пользовательский интерфейс при создании управляемого приложения.

Используется следующий шаблон:

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

CreateUiDefinition всегда содержит три свойства:

handler;
version
parameters

Свойство handler должно всегда иметь значение Microsoft.Azure.CreateUIDef, а последняя поддерживаемая версия — 0.1.2-preview.

Схема свойства parameters зависит от сочетания определенных значений handler и version. Для управляемых приложений поддерживаются свойства config, basics, steps и outputs. Значение config используется только в том случае, если необходимо переопределить поведение по умолчанию для шага basics. Свойства basics и steps содержат элементы, например текстовые поля и раскрывающиеся списки, которые отображаются на портале Azure. Свойство outputs используется для сопоставления выходных значений определенных элементов с параметрами шаблона Azure Resource Manager.

Советуем также использовать параметр $schema, но это необязательно. При его использовании значение параметра version должно совпадать с версией в URI $schema.

Вы можете с помощью редактора JSON создать файл createUiDefinition, а затем протестировать и предварительно просмотреть его в песочнице createUiDefinition. Дополнительные сведения об этой песочнице см. в статье Тестирование интерфейса портала для Управляемых приложений Azure.

Config

Свойство config необязательное. Используйте его для переопределения поведения по умолчанию на этапе basics или для настройки интерфейса в пошаговом мастере. Если используется config, то это всегда первое свойство в разделе parameters файла createUiDefinition.js. В следующем примере показаны доступные свойства.

"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
        }
    }
},

Для свойства isValid создайте выражение, которое разрешается в значение true или false. Для свойства permission укажите одно из действий поставщика ресурсов.

Мастер

Свойство isWizard позволяет потребовать, чтобы переход к следующему шагу выполнялся только после успешной проверки предыдущего. Если свойство isWizard не задано явно, по умолчанию ему присваивается значение false, то есть пошаговая проверка не требуется.

Если свойство isWizard присутствует и имеет значение true, отображается вкладка Основные сведения, а все остальные вкладки отключены. При нажатии кнопки Далее значок вкладки указывает, пройдена ли проверка для этой вкладки. Когда все обязательные поля будут заполнены и проверены, кнопка Далее разрешает переход на следующую вкладку. Когда закончится проверка всех вкладок, вы сможете перейти на страницу Проверка и создание и нажать кнопку Создать, чтобы начать развертывание.

Мастер вкладок

Переопределение basics

Конфигурация basics позволяет настроить этот этап.

Для description укажите строку в формате Markdown, которая описывает ресурс. Поддерживается многострочный текст и ссылки.

Элементы subscription и resourceGroup позволяют указать дополнительные проверки. Синтаксис для этих проверок аналогичен настраиваемой проверке для текстового поля. Также можно указать проверки permission для подписки или группы ресурсов.

Элемент управления подписками принимает список пространств имен поставщиков ресурсов. К примеру, здесь можно указать Microsoft.Compute. Если пользователь выбирает подписку, которая не поддерживает поставщик ресурсов, отображается сообщение об ошибке. Эта ошибка возникает, если поставщик ресурсов не зарегистрирован в подписке и пользователь не имеет разрешений на регистрацию поставщика ресурсов.

Элемент управления "Группа ресурсов" имеет параметр для allowExisting. Если он имеет значение true, пользователи могут выбирать группы ресурсов, у которых уже есть ресурсы. Этот флаг наиболее применим для шаблонов решений, где по умолчанию пользователь обязан выбрать новую или пустую группу ресурсов. В большинстве других случаев это свойство указывать не требуется.

Для location укажите свойства элемента управления расположением, который вам нужно переопределить. Для всех свойств, которые не переопределены, устанавливаются значения по умолчанию. resourceTypes принимает массив строк с полными именами типов ресурсов. Параметры расположения принимают только значения регионов, которые поддерживают типы ресурсов. allowedValues принимает массив строк регионов. В раскрывающемся списке отображаются только указанные здесь регионы. Вы можете задать одновременно allowedValues и resourceTypes. Результатом будет пересечение двух списков. Наконец, можно использовать свойство visible для условного или полного отключения раскрывающегося списка расположений. 

Основы

Шаг Основные сведения всегда будет первым шагом, который создается при анализе файла на портале Azure. По умолчанию этот шаг позволяет выбрать подписку, группу ресурсов и расположение для развертывания.

Основные сведения, вариант по умолчанию

В этот раздел можно добавить дополнительные элементы. По возможности добавляйте такие элементы, которые запрашивают параметры на уровне всего развертывания, например имя кластера или учетные данные администратора.

В следующем примере показано текстовое поле, добавленное в список элементов.

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

Шаги

Свойство steps (шаги) содержит ноль или более шагов, которые должны отображаться после шага основных сведений (basics). Каждый шаг содержит один или несколько элементов. Вы можете добавить действия для каждой роли или уровня развертываемого приложения. Например, добавьте шаг для входных данных главного узла и шаг для рабочих узлов в кластере.

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

Выходные данные

Портал Azure использует свойство outputs для сопоставления элементов basics и steps с параметрами шаблона развертывания Azure Resource Manager. Ключами являются имена параметров шаблона, а значениями — свойства выходных объектов из элементов, на которые даются ссылки.

Чтобы задать имя ресурса управляемого приложения, необходимо включить значение applicationResourceName в свойство outputs. Если это значение не задано, приложение задает в качестве имени идентификатор GUID. В пользовательский интерфейс, запрашивающий имя пользователя, можно включить текстовое поле.

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

Типы ресурсов

Чтобы отфильтровать доступные расположения и отобразить только те, которые поддерживают типы ресурсов для развертывания, укажите массив с нужными типами ресурсов. Если вы предоставите более одного типа ресурсов, возвращаются только те расположения, которые поддерживают все указанные типы ресурсов. Это необязательное свойство.

{
    "$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": [
          ...

Функции

CreateUiDefinition предоставляет функции для работы с входными и выходными данными элементов, а также с условиями и другими возможностями. Эти функции по синтаксису и функциональности очень похожи на функции шаблонов Azure Resource Manager.

Дальнейшие действия

Файл createUiDefinition.json имеет простую схему. Его реальные возможности основаны на поддерживаемых элементах и функциях. Эти элементы более подробно описаны здесь:

Elements (XElement Dynamic Property) (Elements (Динамическое свойство XElement))
Функции

Текущая схема JSON для createUiDefinition доступна здесь: https://schema.management.azure.com/schemas/0.1.2-preview/CreateUIDefinition.MultiVm.json.

Пример файла пользовательского интерфейса: createUiDefinition.json.