Skapa och publicera en mallspecifikation

  • 3 minuter

Nu ska vi titta på hur du skapar och publicerar en mallspecifikation.

Skapa en mall

Om du vill skapa en mall för användning som en mallspecifikation skriver du en Azure Resource Manager-mall (ARM-mall) precis som vanligt. Du kan inkludera parametrar, variabler, resurser och utdata.

Du kan använda länkade mallar som gör att du kan definiera delar av distributionen i separata filer. När du arbetar med mallspecifikationer kan länkade mallar bäddas in i mallspecifikationen och refereras från huvudmallen.

Det är viktigt att mallen är enkel för alla i organisationen att förstå och använda, särskilt dess parametrar. Se till att du använder tydliga och begripliga parameternamn. Använd parameteregenskaper och mallmetadata för att ge information om de värden som du förväntar dig att dina parametrar ska inkludera, som i det här exemplet:

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

I exemplet använder allowedValuesmallparametrarna egenskaperna , maxValueoch description för att tydliggöra vad parametrarna är till för och vad effekten av att ange deras värden är. Mallen innehåller också typen secureString som anger att parametern key innehåller hemliga data.

Det är viktigt att mallen är enkel för alla i organisationen att förstå och använda, särskilt parametrarna. Se till att du använder tydliga och begripliga parameternamn. Använd parameterdekoratörer för att ge information om de värden som du förväntar dig att dina parametrar ska inkludera, som i det här exemplet:

@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

I exemplet använder @allowedmallparametrarna , @maxValueoch @description dekoratörer för att tydliggöra vad parametrarna är till för och vad effekten av att ange deras värden är. Mallen innehåller även dekoratören secure som anger att parametern key innehåller hemliga data.

När någon distribuerar en mallspecifikation med hjälp av Azure-portalen, portalen:

  • Visar parameternamnet och beskrivningen.
  • Döljer textposten för säkra parametrar.
  • Framtvingar de tillåtna värden, längdgränser och värdegränser som du definierar.

Den här skärmbilden illustrerar posten med parametervärden:

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

Det är viktigt att tänka på hur användarna använder mallspecifikationen och se till att parametrarna är tydliga och begripliga.

Publicera mallspecifikationen till Azure

När mallen har skrivits publicerar du mallspecifikationen i stället för att skicka mallen till Azure för distribution.

Viktigt!

När du publicerar en Bicep-fil som en mallspecifikation konverteras din Bicep-kod till en JSON-mall. Processen med att konvertera Bicep-koden till JSON tar bort en del av informationen i Bicep-filen. Dina kommentarer, symboliska namn för resurser och i vilken ordning du definierar dina resurser kan till exempel saknas eller skilja sig åt i JSON. Det innebär att du inte enkelt kan publicera en Bicep-fil som en mallspecifikation och sedan få tillbaka den ursprungliga Bicep-filen (kallas även roundtripping). Det är en bra idé att behålla en kopia av din ursprungliga Bicep-kod på en kodlagringsplats som Git, särskilt när du arbetar med mallspecifikationer.

Om du vill skapa en mallspecifikation använder du cmdleten New-AzTemplateSpec . I följande exempel visas hur du kan skapa en mallspecifikation för lagringskontomallen:

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

Nu ska vi titta på var och en av parametrarna:

  • -Name är resursnamnet för mallspecifikationen, som inte kan innehålla blanksteg.
  • -Location är den plats där mallspecifikationens metadata ska skapas. Du kan dock distribuera mallspecifikationen till valfri region.
  • -DisplayName är ett läsbart namn som kan användas av människor, vilket kan innehålla blanksteg.
  • -Description är en beskrivning som kan läsas av människor och som du kan använda för att ge information om innehållet i mallspecifikationen och när någon kan använda den.
  • -Version är versionen av mallspecifikationen. Du lär dig mer om versioner senare i den här modulen.
  • -TemplateFile är sökvägen till ARM-mallen som mallspecifikationen ska skapas för.

Använd kommandot för az ts create att skapa en mallspecifikation. I följande exempel visas hur du kan skapa en mallspecifikation för lagringskontomallen:

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

Nu ska vi titta på vart och ett av argumenten:

  • --name är resursnamnet för mallspecifikationen, som inte kan innehålla blanksteg.
  • --location är den plats där mallspecifikationens metadata ska skapas. Du kan dock distribuera mallspecifikationen till valfri region.
  • --display-name är ett läsbart namn som kan användas av människor, vilket kan innehålla blanksteg.
  • --description är en beskrivning som kan läsas av människor och som du kan använda för att ge information om innehållet i mallspecifikationen och när någon kan använda den.
  • --version är versionen av mallspecifikationen. Du lär dig mer om versioner senare i den här modulen.
  • --template-file är sökvägen till ARM-mallen som mallspecifikationen ska skapas för.

Dricks

Du kan också definiera en mallspecifikation i en ARM-mall! Eftersom en mallspecifikation i sig är en Azure-resurs kan du distribuera en mall som definierar en resurs med typen Microsoft.Deployments/templateSpecs.