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

Этот документ знакомит с основными понятиями файла 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.json всегда содержит три свойства:

• обработчик
• версия
• параметры

Свойство 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, это первое свойство в разделе parameters файла createUiDefinition.json. В следующем примере показаны доступные свойства.

"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 позволяет настроить этот этап.

Для 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 имеет простую схему. Его реальные возможности основаны на поддерживаемых элементах и функциях. Эти элементы более подробно описаны здесь:

• Элементы
• Функции

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

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