适合 Azure 托管应用程序的创建体验的 CreateUiDefinition.jsonCreateUiDefinition.json for Azure managed application's create experience

本文档介绍 createUiDefinition.json 文件的核心概念。This document introduces the core concepts of the createUiDefinition.json file. 创建托管应用程序时,Azure 门户使用此文件来定义用户界面。The Azure portal uses this file to define the user interface when creating a managed application.

模板如下所示The template is as follows

{
    "$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 始终包含三个属性:A CreateUiDefinition always contains three properties:

  • 处理程序 (handler)handler
  • 版本version
  • parametersparameters

handler 应当始终为 Microsoft.Azure.CreateUIDef,支持的最新版本为 0.1.2-previewThe handler should always be Microsoft.Azure.CreateUIDef, and the latest supported version is 0.1.2-preview.

parameters 属性的架构取决于所指定的 handler 和 version 的组合。The schema of the parameters property depends on the combination of the specified handler and version. 对于托管应用程序,支持的属性为 configbasics``stepsoutputsFor managed applications, the supported properties are config, basics, steps, and outputs. 仅当需要重写 basics 步骤的默认行为时,才使用 configYou use config only when you need to override the default behavior of the basics step. basics 和 steps 属性包含要在 Azure 门户中显示的元素,例如文本框和下拉列表。The basics and steps properties contain the elements - like textboxes and dropdowns - to be displayed in the Azure portal. outputs 属性用来将指定元素的输出值映射到 Azure 资源管理器模板的参数。The outputs property is used to map the output values of the specified elements to the parameters of the Azure Resource Manager template.

建议包括 $schema,但这是可选的。Including $schema is recommended, but optional. 如果指定,则 version 的值必须与 $schema URI 中的版本匹配。If specified, the value for version must match the version within the $schema URI.

可以使用 JSON 编辑器创建 createUiDefinition,然后在 createUiDefinition 沙盒中对其进行测试,以便预览它。You can use a JSON editor to create your createUiDefinition then test it in the createUiDefinition Sandbox to preview it. 有关沙盒的详细信息,请参阅测试 Azure 托管应用程序的门户接口For more information about the sandbox, see Test your portal interface for Azure Managed Applications.

ConfigConfig

config 属性为可选。The config property is optional. 使用它可以重写基本步骤的默认行为,也可以将界面设置为分步向导。Use it to either override the default behavior of the basics step, or to set your interface as a step-by-step wizard. 如果使用 config,则它是 createUiDefinition.json 文件的 parameters 节中的第一个属性。If config is used, it's the first property in the createUiDefinition.json file's parameters section. 以下示例显示可用的属性。The following example shows the available properties.

"config": {
    "isWizard": false,
    "basics": {
        "description": "Customized description with **markdown**, see [more](https://www.microsoft.com).",
        "subscription": {
            "constraints": {
                "validations": [
                    {
                        "isValid": "[expression for checking]",
                        "message": "Please select a valid subscription."
                    },
                    {
                        "permission": "<Resource Provider>/<Action>",
                        "message": "Must have correct permission to complete this step."
                    }
                ]
            },
            "resourceProviders": [
                "<Resource Provider>"
            ]
        },
        "resourceGroup": {
            "constraints": {
                "validations": [
                    {
                        "isValid": "[expression for checking]",
                        "message": "Please select a valid resource group."
                    }
                ]
            },
            "allowExisting": true
        },
        "location": {
            "label": "Custom label for location",
            "toolTip": "provide a useful tooltip",
            "resourceTypes": [
                "Microsoft.Compute/virtualMachines"
            ],
            "allowedValues": [
                "chinaeast",
                "chinanorth2"
            ],
            "visible": true
        }
    }
},

向导Wizard

isWizard 属性使你能够在继续下一步之前要求对每个步骤进行成功的验证。The isWizard property enables you to require successful validation of each step before proceeding to the next step. 如果未指定 isWizard 属性,则默认值为 false,不需要逐步验证。When the isWizard property isn't specified, the default is false, and step-by-step validation isn't required.

启用了 isWizard 时,将设置为 true,“基本信息”选项卡可用,所有其他选项卡被禁用。When isWizard is enabled, set to true, the Basics tab is available and all other tabs are disabled. 选择“下一步”按钮时,该选项卡的图标指示选项卡的验证是通过还是失败。When the Next button is selected the tab's icon indicates if a tab's validation passed or failed. 完成并验证某个选项卡的必填字段之后,即可通过“下一步”按钮导航到下一个选项卡。所有选项卡都通过验证后,你可以进入“查看并创建”页面,选择“创建”按钮开始进行部署。After a tab's required fields are completed and validated the Next button allows navigation to the next tab. When all tabs pass validation, you can go to the Review and Create page and select the Create button to begin the deployment.

选项卡向导

重写基本信息Override basics

基本信息配置允许你自定义基本信息步骤。The basics config lets you customize the basics step.

对于 description,请提供启用了 markdown 的字符串,用于描述资源。For description, provide a markdown-enabled string that describes your resource. 支持多行格式和链接。Multi-line format and links are supported.

通过 subscriptionresourceGroup 元素,可以指定其他验证。The subscription and resourceGroup elements enable you to specify additional validations. 用于指定验证的语法与文本框自定义验证的语法相同。The syntax for specifying validations is identical to the custom validation for text box. 还可以在订阅或资源组上指定 permission 验证。You can also specify permission validations on the subscription or resource group.

订阅控件接受资源提供程序命名空间的列表。The subscription control accepts a list of resource provider namespaces. 例如,可以指定 Microsoft.Compute。For example, you can specify Microsoft.Compute. 当用户选择了不支持资源提供程序的订阅时,会显示错误消息。It shows an error message when the user selects a subscription that doesn't support the resource provider. 如果资源提供程序未在该订阅上注册,并且用户没有注册资源提供程序的权限,则会发生此错误。The error occurs when the resource provider isn't registered on that subscription, and the user doesn't have permission to register the resource provider.

资源组控件有一个 allowExisting 的选项。The resource group control has an option for allowExisting. true 时,用户可以选择已含有资源的资源组。When true, the users can select resource groups that already have resources. 此标志最适用于解决方案模板,其默认行为要求用户必须选择新的或空的资源组。This flag is most applicable to solution templates, where default behavior mandates users must select a new or empty resource group. 在大多数其他情况下,不需要指定该属性。In most other scenarios, specifying this property isn't necessary.

对于 location,指定希望重写的位置控件的属性。For location, specify the properties for the location control you wish to override. 任何未重写的属性均设置为其默认值。Any properties not overridden are set to their default values. resourceTypes 接受包含完全限定资源类型名称的字符串数组。resourceTypes accepts an array of strings containing fully qualified resource type names. 位置选项限为仅支持该资源类型的区域。 allowedValues  接受区域字符串的数组。The location options are restricted to only regions that support the resource types. allowedValues accepts an array of region strings. 下拉列表中仅显示这些区域。Only those regions appear in the dropdown. 可以同时设置 allowedValues 和 resourceTypes\ You can set both allowedValues and resourceTypes\. 结果是两个列表的交集。The result is the intersection of both lists. 最后,可使用 visible 属性有条件地或完全禁用位置下拉列表。Lastly, the visible property can be used to conditionally or completely disable the location dropdown.

基础Basics

“基本信息”步骤是 Azure 门户分析文件时生成的第一步。The Basics step is the first step generated when the Azure portal parses the file. 默认情况下,通过“基本信息”步骤,用户可选择订阅、资源组和部署位置。By default, the basics step lets users choose the subscription, resource group, and location for deployment.

选项卡向导

在本部分中可以添加更多元素。You can add more elements in this section. 在可能的情况下,请添加可查询部署范围内的参数的元素(例如群集名称或管理员凭据)。When possible, add elements that query deployment-wide parameters, like the name of a cluster or administrator credentials.

以下示例展示添加到默认元素中的文本框。The following example shows a text box that has been added to the default elements.

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

步骤Steps

步骤属性包含零个或多个在基本信息步骤后显示的其他步骤。The steps property contains zero or more additional steps to display after basics. 每个步骤包含一个或多个元素。Each step contains one or more elements. 请考虑按所部署的应用程序的角色或层添加步骤。Consider adding steps per role or tier of the application being deployed. 例如,针对群集中的主节点输入添加一个步骤,针对辅助角色节点添加另一个步骤。For example, add a step for master node inputs, and a step for the worker nodes in a cluster.

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

输出Outputs

Azure 门户使用 outputs 属性来将 basicssteps 中的元素映射到 Azure 资源管理器部署模板的参数。The Azure portal uses the outputs property to map elements from basics and steps to the parameters of the Azure Resource Manager deployment template. 此字典中的键是模板参数的名称,值是所引用元素中的输出对象的属性。The keys of this dictionary are the names of the template parameters, and the values are properties of the output objects from the referenced elements.

若要设置托管应用程序资源名称,必须在 outputs 属性中包括名为 applicationResourceName 的值。To set the managed application resource name, you must include a value named applicationResourceName in the outputs property. 如果未设置此值,应用程序会为名称分配 GUID。If you don't set this value, the application assigns a GUID for the name. 可以在用户界面中包含一个文本框,用于向用户请求名称。You can include a textbox in the user interface that requests a name from the user.

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

资源类型Resource types

若要筛选可用位置(仅可用于那些支持要部署的资源类型的位置),请提供资源类型的数组。To filter the available locations to only those locations that support the resource types to deploy, provide an array of the resource types. 如果提供了多个资源类型,则仅返回支持所有资源类型的位置。If you provide more than one resource type, only those locations that support all of the resource types are returned. 此属性是可选的。This property is optional.

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

函数Functions

CreateUiDefinition 提供了用于处理元素的输入和输出的函数,以及条件语句等功能。CreateUiDefinition provides functions for working with elements' inputs and outputs, and features such as conditionals. 这些函数在语法和功能上类似于 Azure 资源管理器模板函数。These functions are similar in both syntax and functionality to Azure Resource Manager template functions.

后续步骤Next steps

createUiDefinition.json 文件本身具有一个简单的架构。The createUiDefinition.json file itself has a simple schema. 它的实际深度来自所有受支持的元素和函数。The real depth of it comes from all the supported elements and functions. 在以下页中更详细地说明了这些项:Those items are described in greater detail at:

此处提供了 createUiDefinition 的当前 JSON 架构:https://schema.management.azure.com/schemas/0.1.2-preview/CreateUIDefinition.MultiVm.jsonA current JSON schema for createUiDefinition is available here: https://schema.management.azure.com/schemas/0.1.2-preview/CreateUIDefinition.MultiVm.json.

有关用户界面文件示例,请参阅 createUiDefinition.jsonFor an example user interface file, see createUiDefinition.json.