CreateUiDefinition.json لتجربة إنشاء التطبيق المُدار من Azure

يقدم هذا المستند المفاهيم الأساسية لملف createUiDefinition.json. تستخدم مدخل Microsoft 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
• المعلمات

يجب أن يكون المعالج هو Microsoft.Azure.CreateUIDef دائماً، وأحدث إصدار معتمد هو 0.1.2-preview.

يعتمد مخطط خاصية المعلمات على مجموعة المعالج والإصدار المحددين. بالنسبة للتطبيقات المُدارة، فإن الخصائص المدعومة هي config وbasics وsteps وoutputs. لا تستخدم config إلا عندما تحتاج إلى تجاوز السلوك الافتراضي للخطوة basics. تحتوي خصائص الأساسيات والخطوات على العناصر - مثل مربعات النص والقوائم المنسدلة - ليتم عرضها في مدخل Microsoft Azure. تُستخدم خاصية المخرجات لتعيين قيم الإخراج للعناصر المحددة إلى معلمات قالب Azure Resource Manager.

يُوصى بتضمين $schema، ولكنه اختياري. إذا تم تحديدها، يجب أن تتطابق قيمة version مع الإصدار داخل $schema URI.

يمكنك استخدام محرر JSON لإنشاء createUiDefinition الخاصة بك ثم اختباره في createUiDefinition Sandbox لمعاينته. لمزيدٍ من المعلومات حول آلية تحديد الصلاحيات، راجع اختبار واجهة المدخل لتطبيقات Azure المُدارة.

Config

الخاصية config اختيارية. استخدمه إما لتجاوز السلوك الافتراضي لخطوة الأساسيات، أو لتعيين واجهتك على أنها معالج خطوة بخطوة. إذا تم استخدام config، فهي الخاصية الأولى في قسم parameters للملف createUiDefinition.json. يوضح المثال التالي الخصائص المتاحة.

"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، اكتب تعبيراً يتحول إلى صواب أو خطأ. بالنسبة للخاصية permission، حدد أحد إجراءات موفر المورد.

Wizard

تتيح لك الخاصية isWizard طلب تحقق ناجح من كل خطوة قبل المتابعة إلى الخطوة التالية. عندما لا يتم تحديد الخاصية isWizard، تكون الخاصية الافتراضية false، ولا يلزم التحقق خطوة بخطوة.

عندما يتم تمكين isWizard، اضبط على true، تكون علامة التبويب Basics متاحة ويتم تعطيل جميع علامات التبويب الأخرى. عند تحديد الزر Next، تشير أيقونة علامة التبويب إلى نجاح أو فشل التحقق من علامة التبويب. بعد إكمال الحقول المطلوبة لعلامة التبويب والتحقق من صحتها، يتيح زر Next التنقل إلى علامة التبويب التالية. عندما تجتاز جميع علامات التبويب عملية التحقق، يمكنك الانتقال إلى صفحة Review and Create وتحديد الزر Create لبدء التوزيع.

تجاوز الأساسيات

يتيح لك تكوين الأساسيات تخصيص خطوة الأساسيات.

بالنسبة إلى description، قم بتوفير سلسلة ذات علامة تمييز ممكنة تصف المورد الخاص بك. دعم تنسيق متعدد الخطوط والروابط.

يمكّنك العنصران subscription وresourceGroup من تحديد المزيد من عمليات التحقق. البنية المستخدمة في تحديد عمليات التحقق مماثلة لعملية التحقق المخصصة لمربع النص. يمكنك أيضاً تحديد permission عمليات التحقق من صحة الاشتراك أو مجموعة الموارد.

يقبل عنصر تحكم الاشتراك قائمة بمساحات أسماء موفري الموارد. على سبيل المثال، يمكنك تحديد Microsoft.Compute. يعرض رسالة خطأ عندما يحدد المستخدم اشتراكاً لا يدعم مزود المورد. يحدث الخطأ عندما لا يكون موفر المورد مسجلاً في ذلك الاشتراك، ولا يمتلك المستخدم إذناً لتسجيل موفر المورد.

يحتوي عنصر التحكم في مجموعة الموارد على خيار لـ allowExisting. عند true، يمكن للمستخدمين تحديد مجموعات الموارد التي لديها بالفعل موارد. هذه العلامة قابلة للتطبيق بشكل أكبر على قوالب الحلول، حيث يفرض السلوك الافتراضي على المستخدمين تحديد مجموعة موارد جديدة أو فارغة. في معظم السيناريوهات الأخرى، لا يُعد تحديد هذه الخاصية ضرورياً.

بالنسبة إلى location، حدد خصائص عنصر التحكم في الموقع الذي تريد تجاوزه. يتم تعيين أي خصائص لم يتم تجاوزها على قيمها الافتراضية. يقبلresourceTypes مصفوفة من السلاسل التي تحتوي على أسماء أنواع موارد مؤهلة بالكامل. تقتصر خيارات الموقع على المناطق التي تدعم أنواع الموارد فقط. allowedValues يقبل صفيف سلاسل المنطقة. تظهر هذه المناطق فقط في القائمة المنسدلة. يمكنك تعيين كل من allowedValues وresourceTypes. والنتيجة هي تقاطع كلتا القائمتين. أخيراً، يمكن استخدام الخاصية visible لتعطيل القائمة المنسدلة للموقع بشكل مشروط أو تماماً. 

الأساسيات

الخطوة Basics هي الخطوة الأولى التي يتم إنشاؤها عندما تقوم مدخل Microsoft Azure بتوزيع الملف. بشكل افتراضي، تتيح خطوة الأساسيات للمستخدمين اختيار الاشتراك ومجموعة الموارد والموقع للنشر.

يمكنك إضافة المزيد من العناصر في هذا القسم. عند الإمكان، أضف العناصر التي تستعلم عن معلمات التوزيع، مثل اسم المجموعة أو بيانات اعتماد المسؤول.

يوضح المثال التالي مربع نص تمت إضافته إلى العناصر الافتراضية.

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

المخرجات

يستخدم مدخل Microsoft 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 functions للعمل مع مدخلات ومخرجات العناصر، وميزات مثل الشرطية. تتشابه هذه الوظائف في كلٍّ من البنية والوظائف لوظائف قالب Azure Resource Manager.

الخطوات التالية

يحتوي ملف createUiDefinition.json نفسه على مخطط بسيط. العمق الحقيقي له يأتي من جميع العناصر والوظائف المدعومة. هذه العناصر موصوفة بمزيدٍ من التفصيل في:

• العناصر
• الوظائف

مخطط JSON الحالي لـ createUiDefinition متاح هنا: https://schema.management.azure.com/schemas/0.1.2-preview/CreateUIDefinition.MultiVm.json.

للحصول على مثال لملف واجهة المستخدم، راجع createUiDefinition.json.