适合 Azure 托管应用程序的创建体验的 CreateUiDefinition.json

项目
07/10/2024

本文档介绍 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)
版本
parameters

handler 应当始终为 Microsoft.Azure.CreateUIDef，支持的最新版本为 0.1.2-preview。

parameters 属性的架构取决于所指定的 handler 和 version 的组合。对于托管应用程序，支持的属性为 config、basicssteps 和 outputs。仅当需要重写 basics 步骤的默认行为时，才使用 config。 basics 和 steps 属性包含要在 Azure 门户中显示的元素，例如文本框和下拉列表。 outputs 属性用来将指定元素的输出值映射到 Azure 资源管理器模板的参数。

建议包括 $schema，但这是可选的。如果指定，则 version 的值必须与 $schema URI 中的版本匹配。

可以使用 JSON 编辑器创建 createUiDefinition，然后在 createUiDefinition 沙盒中对其进行测试，以便预览它。有关沙盒的详细信息，请参阅测试 Azure 托管应用程序的门户接口。

Config

config 属性为可选。使用它可以重写基本步骤的默认行为，也可以将界面设置为分步向导。如果使用 config，则它是 createUiDefinition.json 文件的 parameters 节中的第一个属性。以下示例显示可用的属性。

"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": [
        "chinaeast",
        "chinanorth2"
      ],
      "visible": true
    }
  }
},

对于 isValid 属性，请编写解析为 true 或 false 的表达式。对于 permission 属性，请指定一个资源提供程序操作。

向导

isWizard 属性使你能够在继续下一步之前要求对每个步骤进行成功的验证。如果未指定 isWizard 属性，则默认值为 false，不需要逐步验证。

启用了 isWizard 时，将设置为 true，“基本信息”选项卡可用，所有其他选项卡被禁用。选择“下一步”按钮时，该选项卡的图标指示选项卡的验证是通过还是失败。完成并验证某个选项卡的必填字段之后，即可通过“下一步”按钮导航到下一个选项卡。所有选项卡都通过验证后，你可以进入“查看并创建”页面，选择“创建”按钮开始进行部署。

选项卡向导

重写基本信息

基本信息配置允许你自定义基本信息步骤。

对于 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": [
  {
    "name": "demoConfig",
    "label": "Configuration settings",
    "elements": [
       ui-elements-needed-to-create-the-instance
    ]
  }
]

输出

Azure 门户使用 outputs 属性来将 basics 和 steps 中的元素映射到 Azure 资源管理器部署模板的参数。此字典中的键是模板参数的名称，值是所引用元素中的输出对象的属性。

若要设置托管应用程序资源名称，必须在 outputs 属性中包括名为 applicationResourceName 的值。如果未设置此值，应用程序会为名称分配 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 资源管理器模板函数。

后续步骤

createUiDefinition.json 文件本身具有一个简单的架构。它的实际深度来自所有受支持的元素和函数。在以下页中更详细地说明了这些项：

此处提供了 createUiDefinition 的当前 JSON 架构：https://schema.management.azure.com/schemas/0.1.2-preview/CreateUIDefinition.MultiVm.json。

有关用户界面文件示例，请参阅 createUiDefinition.json。

通过

适合 Azure 托管应用程序的创建体验的 CreateUiDefinition.json

Config

向导

重写基本信息

基础

步骤

输出

资源类型

函数

后续步骤

其他资源