Azure 市场 ARM 模板 Azure 门户用户界面指南

ARM 模板具有强大的部署功能,它的输入参数可以由发布者定义,因此具有良好的的弹性。发布者在 Azure 市场发布 ARM 模板的同时,还需要发布 ARM 模板 Azure 门户用户界面文件 createUiDefinition.json,这个文件用于定义 ARM 模板在Azure 门户中部署时的参数输入和用户界面。 本文档主要介绍 createUiDefinition.json(请注意这个文件名是固定的) 文件的基本概念和开发制作。

本文中的 “Azure 市场”作用范围均指中国大陆。

1. createUiDefinition.json 文件结构

createUiDefinition.json 是 JSON 格式的文本文件,它和 ARM 模板相对应,CreateUiDefinition.json 始终包含三个属性 handler、version和parameters,schema为可选,如下列表所示:

  • handler,handler 应当始终为 Microsoft.Compute.MultiVm,支持的最新版本为 0.1.2-preview

  • version,版本固定为 0.1.2-preview

  • parameters,parameters 属性的架构取决于所指定的 handler 和 version 的组合。 对于ARM 模板,支持的属性为 basicsstepsoutputs。 basics 和 steps 属性包含要在 Azure 门户中显示的_元素_,例如文本框和下拉列表。 outputs 属性用来将指定元素的输出值映射到 Azure 资源管理器部署模板的参数。

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

    {
     "$schema": "https://schema.management.azure.com/schemas/0.1.2-preview/CreateUIDefinition.MultiVm.json#",
     "handler": "Microsoft.Compute.MultiVm",
     "version": "0.1.2-preview",
     "parameters": {
          "basics": [ ],
          "steps": [ ],
          "outputs": { }
      }
    }
    

制作 createUiDefinition.json 的主要工作就是填写 parameters 中的 basicsstepsoutputs这三个字段的内容。 下面的一个 ARM 模板部署用户界面,basics 对应图中的步骤 “1” ,steps 对应图中的步骤 “2” 和 “3” 。下面对这三部分分别进行介绍,案例中用到的函数和元素在 2.4 后续步骤 中有参考页面。

注意:开发调试 createUiDefinition.json 的时候,在浏览器中按F12,查看Console菜单下是否报错,以及是否打印 outputs 输出结果。

2. createUiDefinition.json 文件开发

本节详细讲解 createUiDefinition.json 中 parameters 中的 basicsstepsoutputs这三个字段的内容,并附有参考目录和示例文件。请注意,"label"、"toolTip"、"validationMessage"、"subLabel"等字段可以使用中文。

2.1 Outputs

Azure 门户使用 outputs 属性来将 basics 和 steps 中的元素映射到 ARM 部署模板的参数。 此字典中的键是模板参数的名称,值是所引用元素中的输出对象的属性。如下所示,定义了集群的名称和 ssh 登录密码/公钥,basics 和 steps 的参数分别在 2.2 Basics2.3 Steps 中有示例:

"outputs": {
  "clusterName": "[basics('clusterNameUi')]",
  "clusterLoginUserName": "[basics('clusterLoginUserNameUi')]",
  "sshUserName": "[steps('cluster').sshUserNameUi]",
  "sshAuthenticationType": "[steps('cluster').sshCredentialUi.authenticationType]",
  "sshPassword": "[steps('cluster').sshCredentialUi.password]",
  "sshPublicKey": "[steps('cluster').sshCredentialUi.sshPublicKey]"
}

请注意,案例中的键 "clusterName" 对应着 ARM 模板中的参数,例如如下模板参数:

......
"parameters": {
  "clusterName": {
    "type": "string",
    "metadata": {
      "description": "The name of the cluster to create."
      }
  },
......

2.2 Basics

基础步骤始终是 Azure 门户在分析文件时生成的向导的第一个步骤。 除了会显示 basics 中指定的元素外,该门户还会为用户注入其他元素以用于为部署选择订阅、资源组和位置。 通常,对部署范围内的参数进行查询的元素(例如群集名称或管理员凭据)应当放在此步骤中。

如果元素的行为依赖于用户的订阅、资源组或位置,则不能在 basics 中使用该元素。 例如,Microsoft.Compute.SizeSelector 需要依赖于用户的订阅和位置来确定可用大小的列表。 因此,Microsoft.Compute.SizeSelector 只能用于 steps 中。 通常,只有 Microsoft.Common 命名空间中的元素可以用于 basics 中。 但是也允许其他命名空间中不依赖于用户上下文的某些元素(例如 Microsoft.Compute.Credentials)。

如下所示,对于集群名称 "clusterNameUi" 的定义。

"basics": [
  {
    "name": "clusterNameUi",
    "type": "Microsoft.Common.TextBox",
    "label": "HDInsight 集群名称",
    "toolTip": "名称长度不得长于50个字符,可以包含字母、数字和连字符。",
    "constraints": {
      "required": true,
      "regex": "^[a-zA-Z0-9][a-zA-Z0-9-]{0,57}[a-zA-Z0-9]$",
      "validationMessage": "名称长度不得长于50个字符,可以包含字母、数字和连字符。"
    }
  },
  {
    "name": "clusterLoginUserNameUi",
    "type": "Microsoft.Common.TextBox",
    "label": "集群管理员用户名",
    "toolTip": "用来向集群提交任务以及登录集群仪表板的用户名。",
    "constraints": {
      "required": true,
      "regex": "^[a-z0-9]{1,64}$",
      "validationMessage": "用户名必须由1-64个小写字母或数字组成。"
    }
  },
......

2.3 Steps

steps 属性可以包含要在 basics 后显示的零个或多个其他步骤,每个步骤都包含一个或多个元素。 请考虑按所部署的应用程序的角色或层添加步骤。 例如,针对群集中的主节点添加一个用于输入的步骤,针对辅助角色节点添加另一个步骤。

如下用例展示了 “elements” 中的两个参数。

"steps": [
  {
    "name": "cluster",
    "label": "集群配置",
    "subLabel": {
      "preValidation": "设置集群参数",
      "postValidation": "完成"
    },
    "bladeTitle": "集群配置",
    "elements": [
      {
        "name": "sshUserNameUi",
        "type": "Microsoft.Compute.UserNameTextBox",
        "label": "SSH 登录用户名",
        "toolTip": "用于远程访问集群节点。",
        "constraints": {
          "required": true,
          "validationMessage": "用户名必须由1-64个小写字母或数字组成。"
        },
        "osPlatform": "Linux"
      },
      {
        "name": "sshCredentialUi",
        "type": "Microsoft.Compute.CredentialsCombo",
        "label": {
          "authenticationType": "身份验证类型",
          "password": "密码",
          "confirmPassword": "确认密码",
          "sshPublicKey": "SSH 公钥"
        },
        "osPlatform": "Linux"
      },
  ......

2.4 元素和函数参考以及示例文件

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

有关用户界面文件示例,请参阅 Azure 快速启动模板样例文档。请搜索样例下的 createUiDefinition.json 文件。

后续步骤

反馈