CreateUiDefinition.json per l'esperienza di creazione di un'applicazione gestita di Azure

Questo documento illustra i concetti di base del file createUiDefinition.json. Il portale di Azure usa questo file per definire l'interfaccia utente quando si crea un'applicazione gestita.

Il modello è il seguente

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

Un file createUiDefinition.json contiene sempre tre proprietà:

• gestore
• versione
• parameters

Il gestore deve sempre essere Microsoft.Azure.CreateUIDef e la versione supportata più recente è 0.1.2-preview.

Lo schema della proprietà parameters dipende dalla combinazione delle proprietà handler e version specificate. Per le applicazioni gestite sono supportate le proprietà config, basics, steps e outputs. Si usa config solo quando è necessario eseguire l'override del comportamento predefinito del passaggio basics. Le proprietà basics e steps contengono elementi, ad esempio caselle di testo ed elenchi a discesa, da visualizzare nel portale di Azure. La proprietà outputs viene usata per eseguire il mapping dei valori di output degli elementi specificati ai parametri del modello di Azure Resource Manager.

L'inclusione di $schema è consigliata ma facoltativa. Se specificato, il valore per la proprietà version deve corrispondere alla versione nell'URI di $schema.

È possibile usare un editor JSON per creare createUiDefinition e quindi testarlo nella sandbox createUiDefinition per visualizzarlo in anteprima. Per altre informazioni sulla sandbox, vedere Testare l'interfaccia del portale per le applicazioni gestite di Azure.

Config

La proprietà config è facoltativa. Usarla per eseguire l'override del comportamento predefinito del passaggio relativo a Dati principali o per impostare l'interfaccia come procedura guidata dettagliata. Se si usa config, si tratta della prima proprietà nella sezione parameters del file createUiDefinition.json. L'esempio seguente mostra le proprietà disponibili.

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

Per la proprietà isValid, scrivere un'espressione che si risolve in true o false. Per la proprietà permission, specificare una delle azioni del provider di risorse.

Procedura guidata

La proprietà isWizard consente di richiedere la convalida corretta di ogni passaggio prima di procedere al passaggio successivo. Quando la proprietà isWizard non è specificata, il valore predefinito è false e non è necessaria la convalida di ogni passaggio.

Quando isWizard è abilitato, impostato su true, la scheda Dati principali è disponibile e tutte le altre schede sono disabilitate. Quando si seleziona il pulsante Avanti, l'icona della scheda indica se la convalida di una scheda è stata superata o meno. Dopo aver completato e convalidato i campi obbligatori di una scheda, il pulsante Avanti consente di passare alla scheda successiva. Quando tutte le schede superano la convalida, è possibile passare alla pagina Rivedi e crea e selezionare il pulsante Crea per avviare la distribuzione.

Eseguire l'override di Dati principali

La configurazione di Dati principali consente di personalizzare il passaggio corrispondente.

Per description specificare una stringa abilitata per Markdown che descrive la risorsa. Sono supportati il formato multilinea e i collegamenti ipertestuali.

Gli elementi subscription e resourceGroup consentono di specificare più convalide. La sintassi per specificare le convalide è identica alla convalida personalizzata per la casella di testo. È anche possibile specificare convalide permission nella sottoscrizione o nel gruppo di risorse.

Il controllo della sottoscrizione accetta un elenco di spazi dei nomi di provider di risorse. Ad esempio, è possibile specificare Microsoft.Compute. Viene visualizzato un messaggio di errore quando l'utente seleziona una sottoscrizione che non supporta il provider di risorse. L'errore si verifica quando il provider di risorse non è registrato in tale sottoscrizione e l'utente non è autorizzato a registrare il provider di risorse.

Il controllo gruppo di risorse ha un'opzione per allowExisting. Quando true, gli utenti possono selezionare gruppi di risorse che hanno già risorse. Questo flag è applicabile soprattutto ai modelli di soluzione, in cui il comportamento predefinito impone agli utenti di selezionare un gruppo di risorse nuovo o vuoto. Nella maggior parte degli altri scenari non è necessario specificare questa proprietà.

Per location specificare le proprietà per il controllo della posizione di cui si desidera eseguire l'override. Tutte le proprietà non sottoposte a override vengono impostate sui valori predefiniti. resourceTypes accetta una matrice di stringhe contenenti nomi di tipi di risorse completi. Le opzioni di posizione sono limitate alle sole aree che supportano i tipi di risorse. allowedValues accetta una matrice di stringhe di aree. Nell'elenco a discesa vengono visualizzate solo queste aree. È possibile impostare sia allowedValues che resourceTypes. Il risultato è l'intersezione di entrambi gli elenchi. Infine, la proprietà visible può essere usata per disabilitare completamente o in modo condizionale l'elenco a discesa delle posizioni. 

Nozioni di base

Il passaggio Dati principali è il primo passaggio generato quando il portale di Azure analizza il file. Per impostazione predefinita, il passaggio Dati principali consente agli utenti di scegliere la sottoscrizione, il gruppo di risorse e il percorso della distribuzione.

È possibile aggiungere altri elementi in questa sezione. Quando possibile, aggiungere elementi che eseguono query su parametri a livello di distribuzione, ad esempio il nome di un cluster o credenziali di amministratore.

L'esempio seguente illustra una casella di testo aggiunta agli elementi predefiniti.

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

Passaggi

La proprietà steps contiene zero o più passaggi da visualizzare dopo Dati principali. Ogni passaggio contiene uno o più elementi. Prendere in considerazione l'aggiunta di passaggi per ogni ruolo o livello dell'applicazione in fase di distribuzione. Ad esempio, aggiungere un passaggio per gli input del nodo principale e un passaggio per i nodi di lavoro in un cluster.

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

Output

Il portale di Azure usa la proprietà outputs per il mapping di elementi da basics e steps ai parametri del modello di distribuzione Azure Resource Manager. Le chiavi di questo dizionario sono i nomi dei parametri del modello e i valori sono le proprietà degli oggetti di output dagli elementi a cui si fa riferimento.

Per impostare il nome della risorsa applicazione gestita, è necessario includere un valore denominato applicationResourceName nella proprietà di output. Se non si imposta questo valore, l'applicazione assegna un GUID per il nome. È possibile includere una casella di testo nell'interfaccia utente che richiede un nome all'utente.

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

Tipi di risorsa

Per filtrare come disponibili solo le posizioni che supportano i tipi di risorse da distribuire, specificare una matrice dei tipi di risorse. Se si specificano più tipi di risorse, vengono restituite solo le posizioni che supportano tutti i tipi. Questa proprietà è facoltativa.

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

Funzioni

CreateUiDefinition fornisce funzioni per l'uso degli input e degli output degli elementi e funzionalità, ad esempio condizionali. Queste funzioni sono simili per sintassi e funzionalità alle funzioni del modello di Azure Resource Manager.

Passaggi successivi

Il file createUiDefinition.json stesso ha uno schema semplice. ma supporta numerosi elementi e funzioni, illustrati in modo dettagliato nei documenti seguenti:

• Elementi
• Funzioni

Uno schema JSON corrente per createUiDefinition è disponibile qui: https://schema.management.azure.com/schemas/0.1.2-preview/CreateUIDefinition.MultiVm.json.

Per un esempio di file di interfaccia utente, vedere createUiDefinition.json.