Die Datei „CreateUiDefinition.json“ für die Benutzeroberfläche zum Erstellen verwalteter Azure-Anwendungen

  • Artikel

In diesem Dokument werden die grundlegenden Konzepte der Datei createUiDefinition.json vorgestellt. Das Azure-Portal verwendet diese Datei zum Definieren der Benutzeroberfläche beim Erstellen einer verwalteten Anwendung.

Die Vorlage sieht wie folgt aus:

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

Eine createUiDefinition.json-Datei hat immer drei Eigenschaften:

  • handler
  • version
  • parameters

Der Handler muss immer Microsoft.Azure.CreateUIDef lauten, und die neueste unterstützte Version ist 0.1.2-preview.

Das Schema der parameters-Eigenschaft hängt von der Kombination aus den angegebenen Werten für „handler“ und „version“ ab. Für verwaltete Anwendungen lauten die unterstützten Eigenschaften config, basics, steps und outputs. Sie verwenden config nur, wenn Sie das Standardverhalten des basics-Schritts außer Kraft setzen müssen. Die Eigenschaften „basics“ und „steps“ enthalten die Elemente (wie Textfelder und Dropdownfelder), die im Azure-Portal angezeigt werden sollen. Mit der outputs-Eigenschaft werden die Ausgabewerte der angegebenen Elemente den Parametern der Azure Resource Manager-Vorlage zugeordnet.

Die Aufnahme von $schema wird empfohlen, ist aber optional. Wenn ein Wert angegeben wird, muss der Wert für version der Version im $schema-URI entsprechen.

Sie können einen JSON-Editor zum Erstellen von „createUiDefinition“ verwenden, und sie dann in der Sandbox für „createUiDefinition“ testen, um eine Vorschau davon anzuzeigen. Weitere Informationen zur Sandbox finden Sie unter Testen Ihrer Portaloberfläche für Azure Managed Applications.

Config

Die config-Eigenschaft ist optional. Verwenden Sie sie entweder, um das Standardverhalten des Grundlagenschritts zu überschreiben oder die Schnittstelle als Schritt-für-Schritt-Assistent festzulegen. Wenn config verwendet wird, handelt es sich hierbei um die erste Eigenschaft im parameters-Abschnitt der Datei createUiDefinition.json. Im folgenden Beispiel wird die verfügbare Eigenschaft gezeigt.

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

Schreiben Sie für die Eigenschaft isValid einen Ausdruck, der zu „true“ oder „false“ aufgelöst wird. Geben Sie für die Eigenschaft permission eine der Ressourcenanbieteraktionen an.

Assistent

Die isWizard-Eigenschaft ermöglicht Ihnen, eine erfolgreiche Überprüfung jedes Schritts zu erzwingen, bevor mit dem nächsten Schritt fortgefahren wird. Wenn die isWizard-Eigenschaft nicht angegeben wird, ist der Standardwert false, und die schrittweise Validierung ist nicht erforderlich.

Wenn isWizard aktiviert, d. h. auf true festgelegt ist, ist die Registerkarte Grundlagen verfügbar, und alle anderen Registerkarten sind deaktiviert. Wenn die Schaltfläche Weiter ausgewählt ist, zeigt das Symbol der Registerkarte an, ob die Validierung einer Registerkarte erfolgreich oder fehlerhaft war. Nachdem die erforderlichen Felder der Registerkarte ausgefüllt und überprüft wurden, ermöglicht die Schaltfläche Weiter die Navigation zur nächsten Registerkarte. Wenn alle Registerkarten die Überprüfung bestanden haben, können Sie auf der Seite Überprüfen und erstellen die Schaltfläche Erstellen auswählen, um die Bereitstellung zu starten.

Registerkarten-Assistent

Überschreiben von Grundlagen

Mit der Grundlagenkonfiguration können Sie den Grundlagenschritt anpassen.

Geben Sie für description eine markdownaktivierte Zeichenfolge an, in der Ihre Ressource beschrieben wird. Mehrzeilige Formate und Verknüpfungen werden unterstützt.

Die Elemente subscription und resourceGroup ermöglichen es Ihnen, mehr Validierungen anzugeben. Die Syntax zum Angeben von Validierungen ist identisch mit der benutzerdefinierten Validierung für ein Textfeld. Sie können auch permission-Validierungen für das Abonnement oder die Ressourcengruppe angeben.

Das Abonnement-Steuerelement (subscription) akzeptiert eine Liste mit Ressourcenanbieter-Namespaces. Sie können z.B. Microsoft.Compute festlegen. Es zeigt eine Fehlermeldung an, wenn der Benutzer ein Abonnement auswählt, das den Ressourcenanbieter nicht unterstützt. Der Fehler tritt auf, wenn der Ressourcenanbieter für dieses Abonnement nicht registriert ist und der Benutzer nicht über die Berechtigung zum Registrieren des Ressourcenanbieters verfügt.

Das Ressourcengruppen-Steuerelement verfügt über eine Option für allowExisting. Wenn diese true ist, können die Benutzer Ressourcengruppen auswählen, die bereits über Ressourcen verfügen. Dieses Flag lässt sich am besten auf Projektmappenvorlagen anwenden, bei denen das Standardverhalten erfordert, dass Benutzer eine neue oder leere Ressourcengruppe auswählen müssen. In den meisten anderen Szenarien ist die Angabe dieser Eigenschaft nicht erforderlich.

Geben Sie für location die Eigenschaften für das Standort-Steuerelement an, das Sie überschreiben möchten. Alle nicht überschriebenen Eigenschaften werden auf ihre Standardwerte festgelegt. resourceTypes akzeptiert ein Array von Zeichenfolgen, das vollqualifizierte Ressourcentypnamen enthält. Die Standortoptionen sind ausschließlich auf Regionen beschränkt, die die Ressourcentypen unterstützen. allowedValuesakzeptiert ein Array von Regionszeichenfolgen. Nur diese Regionen werden in der Dropdownliste angezeigt. Sie können sowohl allowedValues als auch resourceTypes festlegen. Das Ergebnis ist die Schnittmenge beider Listen. Schließlich kann die visible-Eigenschaft verwendet werden, um das Standortdropdown bedingt oder vollständig zu deaktivieren. 

Grundlagen

Der Basics-Schritt ist der erste Schritt, der generiert wird, wenn das Azure-Portal die Datei analysiert. Standardmäßig kann der Benutzer im Basics-Schritt das Abonnement, die Ressourcengruppe und den Speicherort für die Bereitstellungsvorlage auswählen.

Basics-Standard

In diesem Abschnitt können Sie weitere Elemente hinzufügen. Fügen Sie nach Möglichkeit Elemente hinzu, die bereitstellungsweite Parameter abfragen, z. B. den Namen eines Clusters oder Administratoranmeldeinformationen.

Das folgende Beispiel zeigt ein Textfeld, das den Standardelementen hinzugefügt wurde.

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

Schritte

Die Eigenschaft „steps“ enthält null oder mehr nach „basics“ anzuzeigende Schritte. Jeder Schritt enthält mindestens ein Element. Ziehen Sie das Hinzufügen von steps-Elementen pro Rolle oder Ebene der bereitgestellten Anwendung in Betracht. Fügen Sie beispielsweise ein „steps“-Element für primäre Knoteneingaben und ein „steps“-Element für die Workerknoten in einem Cluster hinzu.

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

Ausgaben

Mit der outputs-Eigenschaft ordnet das Azure-Portal Elemente aus basics und steps den Parametern der Azure Resource Manager-Bereitstellungsvorlage zu. Die Schlüssel dieses Wörterbuchs stellen die Namen der Vorlagenparameter dar, und die Werte sind Eigenschaften der Ausgabeobjekte von den referenzierten Elementen.

Um den Ressourcennamen der verwalteten Anwendung festzulegen, müssen Sie einen Wert mit dem Namen applicationResourceName in die Ausgabeeigenschaft eingeben. Wenn Sie diesen Wert nicht festlegen, weist die Anwendung eine GUID für den Namen zu. Sie können ein Textfeld in die Benutzeroberfläche aufnehmen, das einen Namen vom Benutzer anfordert.

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

Ressourcentypen

Um die verfügbaren Standorte nach denen zu filtern, die die bereitzustellenden Ressourcentypen unterstützen, geben Sie ein Array der Ressourcentypen an. Wenn Sie mehrere Ressourcentypen angeben, werden nur die Standorte zurückgegeben, die alle Ressourcentypen unterstützen. Diese Eigenschaft ist optional.

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

Functions

„CreateUiDefinition“ stellt Funktionen zum Arbeiten mit den Eingaben und Ausgaben von Elementen sowie Features wie konditionelle Abschnitte bereit. Diese Funktionen sind sowohl im Hinblick auf die Syntax als auch auf die Funktionalität den Vorlagenfunktionen von Azure Resource Manager ähnlich.

Nächste Schritte

Die Datei createUiDefinition.json besitzt selbst ein einfaches Schema. Die tatsächliche Tiefe ergibt sich aus allen unterstützten Elementen und Funktionen. Diese Elemente werden in den folgenden Dokumenten ausführlicher beschrieben:

Ein aktuelles JSON-Schema für createUiDefinition ist unter folgendem Link verfügbar: https://schema.management.azure.com/schemas/0.1.2-preview/CreateUIDefinition.MultiVm.json.

Ein Beispiel für eine Benutzeroberflächendatei finden Sie unter createUiDefinition.json.