適用於 Azure 受控應用程式建立體驗的 CreateUiDefinition

發行項
03/22/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 一律包含三個屬性：

handler (處理常式)
version
parameters

處理常式應一律為 Microsoft.Azure.CreateUIDef，而最新的支援版本為 0.1.2-preview。

parameters 屬性的結構描述取決於指定的處理常式和版本之組合。針對受控應用程式，支援的屬性為 config、basics、steps 和 outputs。只有當您需要覆寫 basics 步驟的預設行為時，才會使用 config。 basics 和 steps屬性包含要在 Azure 入口網站中顯示的元素 - 如同文字方塊和下拉式清單。 outputs 屬性可用來將指定元素的輸出值對應至 Azure Resource Manager 範本的參數。

建議包含 $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": [
                "eastus",
                "westus2"
            ],
            "visible": true
        }
    }
},

針對 isValid 屬性，撰寫可解析為 true 或 false 的運算式。針對 permission 屬性，指定其中一個資源提供者動作 (部分機器翻譯)。

精靈

isWizard 屬性可讓您在繼續進行下一個步驟之前，要求每個步驟的驗證成功。未指定 isWizard 屬性時，預設值為 false，且不需要逐步驗證。

當 isWizard 啟用並設定為 true 時，[基本] 索引標籤可供使用，且會停用所有其他索引標籤。選取 [下一步] 按鈕時，索引標籤的圖示會指出索引標籤的驗證通過或失敗。在索引標籤的必要欄位完成並通過驗證後，按 [下一步] 按鈕可瀏覽至下一個索引標籤。所有索引標籤都通過驗證時，您可以移至 [檢閱和建立] 頁面，然後選取 [建立] 按鈕以開始部署。

Tab wizard

覆寫基本概念

基本設定可讓您自訂基本步驟。

針對 description，提供已啟用 Markdown 的字串來描述您的資源。支援多行格式和連結。

subscription 和 resourceGroup 元素可讓您指定更多驗證。指定驗證的語法與文字方塊的自訂驗證完全相同。您也可以在訂用帳戶或資源群組上指定 permission 驗證。

訂用帳戶控制項會接受資源提供者命名空間的清單。例如，您可以指定 Microsoft.Compute。當使用者選取不支援資源提供者的訂用帳戶時，便會顯示錯誤訊息。當資源提供者未在該訂用帳戶上註冊，且使用者沒有註冊資源提供者的權限時，便會發生此錯誤。

資源群組控制項具有 allowExisting 的選項。若為 true，使用者可以選取已有資源的資源群組。此旗標最適用於解決方案範本，其預設行為會強制使用者必須選取新的或空白的資源群組。在多數其他情況下，不需要指定此屬性。

針對 location，指定您想要覆寫的位置控制項屬性。任何未覆寫的屬性都會設定為其預設值。 resourceTypes 會接受包含完整資源類型名稱的字串陣列。位置選項僅限於支援資源類型的區域。 allowedValues 會接受區域字串的陣列。只有那些區域會顯示在下拉式清單中。 您可以同時設定 allowedValues 和 resourceTypes。結果會是這兩個清單的交集。最後，visible 屬性可用來有條件地或完全停用位置下拉式清單。 

基本概念

[基本] 步驟是在 Azure 入口網站剖析檔案時產生的第一個步驟。依預設，[基本] 步驟可讓使用者選擇要部署的訂用帳戶、資源群組和位置。

Basics default

您可以在此區段中新增更多元素。可能的話，新增查詢整個部署參數的元素 (例如叢集的名稱或管理員認證)。

下列範例顯示已新增至預設元素的文字方塊。

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

步驟

steps 屬性包含要在 [基本] 之後顯示的零或多個步驟。每個步驟都包含一或多個元素。請考慮針對每個角色或要進行部署的應用程式層新增步驟。例如，新增適用於主要節點輸入的步驟，以及適用於叢集中背景工作角色節點的步驟。

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

輸出

Azure 入口網站會使用 outputs 屬性，將 basics 和 steps 的屬性對應至 Azure Resource Manager 部署範本的參數。這個字典的金鑰是範本參數的名稱，而值則是所參照元素的輸出物件之屬性。

若要設定受控應用程式資源名稱，您必須在輸出屬性中包含名為 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 Resource Manager 範本函式類似。

下一步

createUiDefinition.json 檔案本身有簡單的結構描述。它的實際深度來自於所有支援的元素和函式。這些項目會在以下位置更詳細地描述：

下列位置會提供 createUiDefinition 的目前 JSON 結構描述：https://schema.management.azure.com/schemas/0.1.2-preview/CreateUIDefinition.MultiVm.json。

如需使用者介面檔案範例，請參閱 createUiDefinition.json。

適用於 Azure 受控應用程式建立體驗的 CreateUiDefinition

Config

精靈

覆寫基本概念

基本概念

步驟

輸出

資源類型

函式

下一步

其他資源