Creare e pubblicare una specifica di modello

  • 3 minuti

Si esaminerà ora come creare e pubblicare una specifica di modello.

Crea un modello

Per creare un modello come specifica di modello, scrivi un modello di Azure Resource Manager (modello di ARM) proprio come fai normalmente. È possibile includere parametri, variabili, risorse e output.

È possibile usare i modelli collegati, che consentono di definire le parti della distribuzione in file separati. Quando si lavora con le specifiche di modello, i modelli collegati possono essere incorporati nella specifica di modello ed essere usati come riferimento dal modello principale.

È importante che tutti gli utenti dell'organizzazione possano facilmente comprendere e usare il modello, in particolare i parametri. Assicurarsi di usare nomi di parametro chiari e comprensibili. Usare le proprietà dei parametri e i metadati del modello per fornire informazioni sui valori che i parametri devono includere, come in questo esempio:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "environmentType": {
      "type": "string",
      "allowedValues": [
        "Production",
        "NonProduction"
      ],
      "metadata": {
        "description": "The type of the environment to deploy. This will determine the SKUs and cost of the resources."
      }
    },
    "key": {
      "type": "secureString",
      "metadata": {
        "description": "The secret key to use."
      }
    },
    "location": {
      "type": "string",
      "metadata": {
        "description": "The Azure region into which the resources should be deployed."
      }
    },
    "sqlServerCount": {
      "type": "int",
      "maxValue": 5,
      "metadata": {
        "description": "The number of Azure SQL logical servers to create."
      }
    }
  },
  "resources": []
}

Nell'esempio i parametri del modello usano le proprietà allowedValues, maxValue e description per chiarire a che cosa servono i parametri e qual è l'effetto dell'impostazione dei valori. Il modello include anche il tipo secureString per indicare che il parametro key contiene dati segreti.

È importante che tutti gli utenti dell'organizzazione possano facilmente comprendere e usare il modello, in particolare i parametri. Assicurarsi di usare nomi di parametro chiari e comprensibili. Usare le espressioni Decorator dei parametri per fornire informazioni sui valori che i parametri devono includere, come in questo esempio:

@description('The type of the environment to deploy. This will determine the SKUs and cost of the resources.')
@allowed([
  'Production'
  'NonProduction'
])
param environmentType string

@secure()
@description('The secret key to use.')
param key string

@description('The Azure region into which the resources should be deployed.')
param location string

@description('The number of Azure SQL logical servers to create.')
@maxValue(5)
param sqlServerCount int

Nell'esempio i parametri del modello usano le espressioni Decorator @allowed, @maxValue e @description per chiarire a che cosa servono i parametri e qual è l'effetto dell'impostazione dei valori. Il modello include anche l'espressione Decorator secure per indicare che il parametro key contiene dati segreti.

Quando qualcuno distribuisce una specifica di modello usando il portale di Azure, il portale:

  • Mostra il nome e la descrizione del parametro.
  • Nasconde l'immissione di testo per i parametri sicuri.
  • Applica i valori consentiti e i limiti di lunghezza e di valore definiti.

Questo screenshot illustra l'immissione dei valori dei parametri:

Screenshot that shows the Azure portal interface for entering parameter values for a template spec deployment.

È importante pensare a come la specifica di modello viene usata dagli utenti e assicurarsi che i parametri siano chiari e comprensibili.

Pubblicare la specifica di modello in Azure

Dopo aver scritto il modello, invece di inviarlo ad Azure per la distribuzione, pubblica la specifica di modello.

Importante

Quando si pubblica un file Bicep come specifica di modello, il codice Bicep viene convertito in un modello JSON. Il processo di conversione del codice Bicep in JSON rimuove alcune informazioni nel file Bicep. Ad esempio, i commenti, i nomi simbolici per le risorse e l'ordine in cui si definiscono le risorse potrebbero mancare o essere diversi in JSON. Non è pertanto possibile pubblicare facilmente un file Bicep come specifica di modello e quindi recuperare il file Bicep originale (roundtrip). È consigliabile conservare una copia del codice Bicep originale in un repository di codice come Git, soprattutto quando si usano le specifiche dei modelli.

Per creare una specifica di modello, usare il cmdlet New-AzTemplateSpec. L'esempio seguente mostra come creare una specifica per il modello di account di archiviazione:

New-AzTemplateSpec `
  -Name StorageWithoutSAS `
  -Location westus `
  -DisplayName 'Storage account with SAS disabled' `
  -Description 'This template spec creates a storage account, which is preconfigured to disable SAS authentication.' `
  -Version '1.0' `
  -TemplateFile main.bicep

New-AzTemplateSpec `
  -Name StorageWithoutSAS `
  -Location westus `
  -DisplayName 'Storage account with SAS disabled' `
  -Description 'This template spec creates a storage account, which is preconfigured to disable SAS authentication.' `
  -Version '1.0' `
  -TemplateFile azuredeploy.json

Verranno ora esaminate le caratteristiche di ognuno dei parametri:

  • -Name è il nome risorsa della specifica di modello, che non può includere spazi.
  • -Location è la posizione in cui devono essere creati i metadati della specifica di modello. È tuttavia possibile distribuire la specifica di modello in qualsiasi area.
  • -DisplayName è un nome in formato leggibile, che può includere spazi.
  • -Description è una descrizione in formato leggibile, che è possibile usare per fornire dettagli sul contenuto della specifica di modello e sulle situazioni in cui è opportuno usarla.
  • -Version è la versione della specifica di modello. Riceverai informazioni sulle versioni più avanti in questo modulo.
  • -TemplateFile è il percorso del modello di ARM per cui creare la specifica di modello.

Per creare una specifica di modello, usare il comando az ts create. L'esempio seguente mostra come creare una specifica per il modello di account di archiviazione:

az ts create \
  --name StorageWithoutSAS \
  --location westus \
  --display-name "Storage account with SAS disabled" \
  --description "This template spec creates a storage account, which is preconfigured to disable SAS authentication." \
  --version 1.0 \
  --template-file main.bicep

az ts create \
  --name StorageWithoutSAS \
  --location westus \
  --display-name "Storage account with SAS disabled" \
  --description "This template spec creates a storage account, which is preconfigured to disable SAS authentication." \
  --version 1.0 \
  --template-file azuredeploy.json

Verranno ora esaminate le caratteristiche di ognuno degli argomenti:

  • --name è il nome risorsa della specifica di modello, che non può includere spazi.
  • --location è la posizione in cui devono essere creati i metadati della specifica di modello. È tuttavia possibile distribuire la specifica di modello in qualsiasi area.
  • --display-name è un nome in formato leggibile, che può includere spazi.
  • --description è una descrizione in formato leggibile, che è possibile usare per fornire dettagli sul contenuto della specifica di modello e sulle situazioni in cui è opportuno usarla.
  • --version è la versione della specifica di modello. Riceverai informazioni sulle versioni più avanti in questo modulo.
  • --template-file è il percorso del modello di ARM per cui creare la specifica di modello.

Suggerimento

È anche possibile definire una specifica di modello in un modello di ARM. Poiché una specifica di modello è di per sé una risorsa di Azure, è possibile distribuire un modello che definisce una risorsa con il tipo Microsoft.Deployments/templateSpecs.