CreateUiDefinition.json untuk pengalaman membuat aplikasi terkelola Azure

  • Artikel

Dokumen ini memperkenalkan konsep inti file createUiDefinition.json. Portal Microsoft Azure menggunakan file ini untuk menentukan antarmuka pengguna saat membuat aplikasi terkelola.

Templatnya adalah sebagai berikut

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

Sebuah CreateUiDefinition selalu berisi tiga properti:

  • penghandel
  • versi
  • parameter

Penghandel harus selalu Microsoft.Azure.CreateUIDef, dan versi terbaru yang didukung adalah 0.1.2-preview.

Skema properti parameter tergantung pada kombinasi pengatur dan versi yang telah ditentukan. Untuk aplikasi terkelola, properti yang didukung adalah config, basics, steps, dan outputs. Anda hanya menggunakan config saat Anda perlu mengambil alih perilaku default langkah basics tersebut. Properti dasar dan langkah-langkah berisi elemen - seperti kotak teks dan drop-down - untuk ditampilkan di portal Microsoft Azure. Properti output digunakan untuk memetakan nilai output dari elemen yang ditentukan ke parameter templat Azure Resource Manager.

Termasuk $schema direkomendasikan, tetapi opsional. Jika ditentukan, nilai untuk version harus cocok dengan versi dalam URI $schema.

Anda dapat menggunakan penyunting JSON untuk membuat createUiDefinition, lalu uji di Kotak Pasir createUiDefinition untuk mempratinjaunya. Untuk informasi selengkapnya tentang kotak pasir, lihat Menguji antarmuka portal Anda untuk Azure Managed Applications.

Konfigurasi

Properti config bersifat opsional. Gunakan untuk mengambil alih perilaku default langkah dasar, atau untuk mengatur antarmuka Anda sebagai wizard langkah demi langkah. Jika config digunakan, ini adalah properti pertama di bagian file createUiDefinition.jsonparameters. Contoh berikut menunjukkan properti yang tersedia.

"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
        }
    }
},

Untuk properti isValid, tulis ekspresi yang diselesaikan ke benar atau salah. Untuk properti permission, tentukan salah satu tindakan penyedia sumber daya.

Wizard

Properti isWizard memungkinkan Anda untuk memerlukan validasi yang berhasil dari setiap langkah sebelum melanjutkan ke langkah berikutnya. Saat properti isWizard tidak ditentukan, defaultnya adalah salah, dan validasi langkah demi langkah tidak diperlukan.

Saat isWizard diaktifkan, ditetapkan ke benar, tab Dasar tersedia dan semua tab lainnya dinonaktifkan. Saat tombol Berikutnya dipilih, ikon tab menunjukkan apakah validasi tab diteruskan atau gagal. Setelah bidang yang diperlukan sebuah tab selesai dan divalidasi, tombol Berikutnya memungkinkan navigasi ke tab berikutnya. Saat semua tab melewati validasi, Anda bisa masuk ke halaman Tinjau dan Buat dan pilih tombol Buat untuk memulai penyebaran.

Wizard tab

Mengambil alih dasar

Konfigurasi dasar memungkinkan Anda untuk menyesuaikan langkah dasar.

Untuk description, berikan untai (karakter) yang diaktifkan markdown yang menjelaskan sumber daya Anda. Format dan tautan multi-baris didukung.

Elemen subscription dan resourceGroup memungkinkan Anda untuk mengaktifkan lebih banyak validasi. Sintaks untuk menentukan validasi identik dengan validasi kustom untuk kotak teks. Anda juga dapat menentukan validasi permission pada langganan atau grup sumber daya.

Kontrol langganan menerima daftar kumpulan nama XML penyedia sumber daya. Misalnya, Anda dapat menentukan Microsoft.Compute. Ini menunjukkan pesan kesalahan ketika pengguna memilih sebuah langganan yang tidak mendukung penyedia sumber daya. Kesalahan terjadi ketika penyedia sumber daya tidak terdaftar pada langganan tersebut, dan pengguna tidak memiliki izin untuk mendaftarkan penyedia sumber daya.

Kontrol grup sumber daya memiliki opsi untuk allowExisting. Ketika true, pengguna dapat memilih grup sumber daya yang sudah memiliki sumber daya. Bendera ini paling berlaku untuk templat solusi, di mana perilaku default memberikan mandat bahwa pengguna harus memilih grup sumber daya baru atau yang kosong. Di sebagian besar skenario yang lain, menentukan properti ini tidak diperlukan.

Untuk location, tentukan properti untuk kontrol lokasi yang ingin Anda ambil alih. Properti apa pun yang tidak diambil alih diatur ke nilai defaultnya. resourceTypes menerima larik untai (karakter) yang berisi nama jenis sumber daya yang memenuhi syarat sepenuhnya. Opsi lokasi dibatasi hanya untuk wilayah yang mendukung jenis-jenis sumber daya. allowedValues menerima array string wilayah. Hanya wilayah tersebut yang muncul di menu drop-down. Anda dapat mengatur allowedValues sekaligus resourceTypes. Hasilnya adalah persimpangan dari kedua daftar. Terakhir, properti visible dapat digunakan untuk menonaktifkan drop-down lokasi secara kondisional atau sepenuhnya. 

Dasar

Langkah Dasar adalah langkah pertama yang dihasilkan ketika portal Microsoft Azure memilah file. Secara default, langkah dasar memungkinkan pengguna memilih langganan, grup sumber daya, dan lokasi untuk penyebaran.

Default dasar

Anda dapat menambahkan lebih banyak elemen di bagian ini. Jika memungkinkan, tambahkan elemen yang mengkueri parameter yang disebarkan secara luas, seperti nama kluster atau informasi masuk admin.

Contoh berikut ini memperlihatkan sebuah kotak teks yang telah ditambahkan ke elemen default.

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

Langkah-langkah

Properti langkah-langkah berisi nol atau beberapa langkah untuk ditampilkan setelah dasar. Setiap langkah berisi satu atau beberapa elemen. Pertimbangkan untuk menambahkan langkah-langkah per peran atau tingkat aplikasi yang sedang disebarkan. Misalnya, tambahkan sebuah langkah untuk input simpul utama, dan sebuah langkah untuk simpul pekerja dalam kluster.

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

Output

Portal Microsoft Azure menggunakan properti outputs untuk memetakan elemen dari basics dan steps ke parameter templat penyebaran Azure Resource Manager. Kunci kamus ini adalah nama parameter templat, dan nilai adalah properti objek output dari elemen yang telah direferensikan.

Untuk mengatur nama sumber daya aplikasi terkelola, Anda harus menyertakan sebuah nilai bernama applicationResourceName dalam properti output. Jika Anda tidak mengatur nilai ini, aplikasinya menetapkan GUID untuk nama tersebut. Anda dapat menyertakan kotak teks di antarmuka pengguna yang meminta nama dari pengguna.

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

Jenis sumber daya

Untuk memfilter lokasi yang tersedia hanya ke lokasi yang mendukung jenis sumber daya untuk disebarkan, sediakan larik jenis sumber daya. Jika Anda menyediakan lebih dari satu jenis sumber daya, hanya lokasi yang mendukung semua jenis sumber daya yang dikembalikan. Properti ini bersifat opsional.

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

Fungsi

CreateUiDefinition menyediakan fungsi untuk bekerja dengan input dan output elemen, dan fitur seperti kondisional. Fungsi-fungsi ini mirip dalam sintaks dan fungsionalitasnya untuk fungsi templat Azure Resource Manager.

Langkah berikutnya

File createUiDefinition.json itu sendiri memiliki skema sederhana. Kedalaman yang sebenarnya berasal dari semua elemen dan fungsi yang didukung. Item-item tersebut dijelaskan secara lebih rinci di:

Skema JSON saat ini untuk createUiDefinition tersedia di sini: https://schema.management.azure.com/schemas/0.1.2-preview/CreateUIDefinition.MultiVm.json.

Contoh untuk file antarmuka pengguna, lihat createUiDefinition.json.