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

  • Article

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 模板，支持的属性为 basics、steps 和 outputs。 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 中的 basics、steps 和 outputs这三个字段的内容。 下面的一个 ARM 模板部署用户界面，basics 对应图中的步骤 “1” ，steps 对应图中的步骤 “2” 和 “3” 。下面对这三部分分别进行介绍，案例中用到的函数和元素在 2.4 后续步骤 中有参考页面。

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

2. createUiDefinition.json 文件开发

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

2.1 Outputs

Azure 门户使用 outputs 属性来将 basics 和 steps 中的元素映射到 ARM 部署模板的参数。 此字典中的键是模板参数的名称，值是所引用元素中的输出对象的属性。如下所示，定义了集群的名称和 ssh 登录密码/公钥，basics 和 steps 的参数分别在 2.2 Basics 和 2.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 文件。

后续步骤

反馈