Förstå strukturen och syntaxen för ARM-mallar

I den här artikeln beskrivs strukturen för en Azure Resource Manager-mall (ARM-mall). Den visar de olika avsnitten i en mall och de egenskaper som är tillgängliga i dessa avsnitt.

Den här artikeln är avsedd för användare som känner till ARM-mallar. Den innehåller detaljerad information om mallens struktur. En stegvis självstudiekurs som vägleder dig genom processen att skapa en mall finns i Självstudie: Skapa och distribuera din första ARM-mall. Mer information om ARM-mallar via en guidad uppsättning Learn-moduler finns i Distribuera och hantera resurser i Azure med hjälp av ARM-mallar.

Tips

Bicep är ett nytt språk som erbjuder samma funktioner som ARM-mallar, men med en syntax som är enklare att använda. Om du överväger infrastruktur som kodalternativ rekommenderar vi att du tittar på Bicep.

Mer information om elementen i en Bicep-fil finns i Förstå strukturen och syntaxen för Bicep-filer.

Mallformat

I den enklaste strukturen har en mall följande element:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "",
  "apiProfile": "",
  "parameters": {  },
  "variables": {  },
  "functions": [  ],
  "resources": [  ],
  "outputs": {  }
}
Elementnamn Krävs Beskrivning
$schema Ja Plats för JSON-schemafilen (JavaScript Object Notation) som beskriver versionen av mallspråket. Vilket versionsnummer du använder beror på distributionens omfattning och JSON-redigeraren.

Om du använder Visual Studio Code med azure Resource Manager-verktygstillägget använder du den senaste versionen för resursgruppsdistributioner:
https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#

Andra redigerare (inklusive Visual Studio) kanske inte kan bearbeta det här schemat. För dessa redigerare använder du:
https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#

För prenumerationsdistributioner använder du:
https://schema.management.azure.com/schemas/2018-05-01/subscriptionDeploymentTemplate.json#

För distributioner av hanteringsgrupper använder du:
https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#

För klientdistributioner använder du:
https://schema.management.azure.com/schemas/2019-08-01/tenantDeploymentTemplate.json#
contentVersion Ja Version av mallen (till exempel 1.0.0.0). Du kan ange valfritt värde för det här elementet. Använd det här värdet för att dokumentera betydande ändringar i mallen. När du distribuerar resurser med mallen kan det här värdet användas för att se till att rätt mall används.
apiProfile Inga En API-version som fungerar som en samling API-versioner för resurstyper. Använd det här värdet för att undvika att behöva ange API-versioner för varje resurs i mallen. När du anger en API-profilversion och inte anger någon API-version för resurstypen använder Resource Manager API-versionen för den resurstyp som definieras i profilen.

Egenskapen API-profil är särskilt användbar när du distribuerar en mall till olika miljöer, till exempel Azure Stack och globala Azure. Använd API-profilversionen för att se till att mallen automatiskt använder versioner som stöds i båda miljöerna. En lista över de aktuella API-profilversionerna och resursernas API-versioner som definierats i profilen finns i API-profil.

Mer information finns i Spåra versioner med API-profiler.
parameters Inga Värden som anges när distributionen körs för att anpassa resursdistributionen.
Variabler Inga Värden som används som JSON-fragment i mallen för att förenkla mallspråkuttryck.
Funktioner Inga Användardefinierade funktioner som är tillgängliga i mallen.
Resurser Ja Resurstyper som distribueras eller uppdateras i en resursgrupp eller prenumeration.
Utgångar Inga Värden som returneras efter distributionen.

Varje element har egenskaper som du kan ange. I den här artikeln beskrivs avsnitten i mallen i detalj.

Parametrar

parameters I avsnittet i mallen anger du vilka värden du kan ange när du distribuerar resurserna. Du är begränsad till 256 parametrar i en mall. Du kan minska antalet parametrar med hjälp av objekt som innehåller flera egenskaper.

Tillgängliga egenskaper för en parameter är:

"parameters": {
  "<parameter-name>" : {
    "type" : "<type-of-parameter-value>",
    "defaultValue": "<default-value-of-parameter>",
    "allowedValues": [ "<array-of-allowed-values>" ],
    "minValue": <minimum-value-for-int>,
    "maxValue": <maximum-value-for-int>,
    "minLength": <minimum-length-for-string-or-array>,
    "maxLength": <maximum-length-for-string-or-array-parameters>,
    "metadata": {
      "description": "<description-of-the parameter>"
    }
  }
}
Elementnamn Krävs Beskrivning
parameternamn Ja Namnet på parametern. Måste vara en giltig JavaScript-identifierare.
typ Ja Typ av parametervärde. De tillåtna typerna och värdena är sträng, securestring, int, bool, object, secureObject och array. Se Datatyper i ARM-mallar.
Standardvärde Inga Standardvärde för parametern om inget värde anges för parametern.
allowedValues Inga Matris med tillåtna värden för parametern för att se till att rätt värde anges.
minValue Inga Det minsta värdet för int-typparametrar, det här värdet är inkluderande.
Maxvalue Inga Det maximala värdet för int-typparametrar, det här värdet är inkluderande.
Minlength Inga Den minsta längden för parametrarna sträng, säker sträng och matristyp är det här värdet inkluderande.
Maxlength Inga Den maximala längden för parametrarna sträng, säker sträng och matristyp, det här värdet är inkluderande.
beskrivning Inga Beskrivning av parametern som visas för användare via portalen. Mer information finns i Kommentarer i mallar.

Exempel på hur du använder parametrar finns i Parametrar i ARM-mallar.

I Bicep, se parametrar.

Variabler

I avsnittet variables skapar du värden som kan användas i hela mallen. Du behöver inte definiera variabler, men de förenklar ofta mallen genom att minska komplexa uttryck. Formatet för varje variabel matchar en av datatyperna. Du är begränsad till 256 variabler i en mall.

I följande exempel visas tillgängliga alternativ för att definiera en variabel:

"variables": {
  "<variable-name>": "<variable-value>",
  "<variable-name>": {
    <variable-complex-type-value>
  },
  "<variable-object-name>": {
    "copy": [
      {
        "name": "<name-of-array-property>",
        "count": <number-of-iterations>,
        "input": <object-or-value-to-repeat>
      }
    ]
  },
  "copy": [
    {
      "name": "<variable-array-name>",
      "count": <number-of-iterations>,
      "input": <object-or-value-to-repeat>
    }
  ]
}

Information om hur du använder copy för att skapa flera värden för en variabel finns i Variabel iteration.

Exempel på hur du använder variabler finns i Variabler i ARM-mall.

Se variabler i Bicep.

Functions

I mallen kan du skapa egna funktioner. De här funktionerna är tillgängliga för användning i mallen. Vanligtvis definierar du komplicerade uttryck som du inte vill upprepa i mallen. Du skapar användardefinierade funktioner från uttryck och funktioner som stöds i mallar.

När du definierar en användarfunktion finns det vissa begränsningar:

  • Funktionen kan inte komma åt variabler.
  • Funktionen kan bara använda parametrar som definieras i funktionen. När du använder parameterfunktionen i en användardefinierad funktion är du begränsad till parametrarna för den funktionen.
  • Funktionen kan inte anropa andra användardefinierade funktioner.
  • Funktionen kan inte använda referensfunktionen.
  • Parametrar för funktionen kan inte ha standardvärden.
"functions": [
  {
    "namespace": "<namespace-for-functions>",
    "members": {
      "<function-name>": {
        "parameters": [
          {
            "name": "<parameter-name>",
            "type": "<type-of-parameter-value>"
          }
        ],
        "output": {
          "type": "<type-of-output-value>",
          "value": "<function-return-value>"
        }
      }
    }
  }
],
Elementnamn Krävs Beskrivning
namnområde Ja Namnområde för de anpassade funktionerna. Använd för att undvika namngivningskonflikter med mallfunktioner.
function-name Ja Namnet på den anpassade funktionen. När du anropar funktionen kombinerar du funktionsnamnet med namnområdet. Om du till exempel vill anropa en funktion med namnet uniqueName i namnområdet contoso använder du "[contoso.uniqueName()]".
parameternamn Inga Namnet på parametern som ska användas i den anpassade funktionen.
parameter-value Inga Typ av parametervärde. De tillåtna typerna och värdena är sträng, securestring, int, bool, object, secureObject och array.
output-type Ja Typ av utdatavärde. Utdatavärden stöder samma typer som funktionsindataparametrar.
output-value Ja Mallspråkuttryck som utvärderas och returneras från funktionen.

Exempel på hur du använder anpassade funktioner finns i Användardefinierade funktioner i ARM-mall.

I Bicep stöds inte användardefinierade funktioner. Bicep stöder en mängd olika funktioner och operatorer.

Resurser

I avsnittet resources definierar du de resurser som distribueras eller uppdateras. Du är begränsad till 800 resurser i en mall.

Du definierar resurser med följande struktur:

"resources": [
  {
      "condition": "<true-to-deploy-this-resource>",
      "type": "<resource-provider-namespace/resource-type-name>",
      "apiVersion": "<api-version-of-resource>",
      "name": "<name-of-the-resource>",
      "comments": "<your-reference-notes>",
      "location": "<location-of-resource>",
      "dependsOn": [
          "<array-of-related-resource-names>"
      ],
      "tags": {
          "<tag-name1>": "<tag-value1>",
          "<tag-name2>": "<tag-value2>"
      },
      "identity": {
        "type": "<system-assigned-or-user-assigned-identity>",
        "userAssignedIdentities": {
          "<resource-id-of-identity>": {}
        }
      },
      "sku": {
          "name": "<sku-name>",
          "tier": "<sku-tier>",
          "size": "<sku-size>",
          "family": "<sku-family>",
          "capacity": <sku-capacity>
      },
      "kind": "<type-of-resource>",
      "scope": "<target-scope-for-extension-resources>",
      "copy": {
          "name": "<name-of-copy-loop>",
          "count": <number-of-iterations>,
          "mode": "<serial-or-parallel>",
          "batchSize": <number-to-deploy-serially>
      },
      "plan": {
          "name": "<plan-name>",
          "promotionCode": "<plan-promotion-code>",
          "publisher": "<plan-publisher>",
          "product": "<plan-product>",
          "version": "<plan-version>"
      },
      "properties": {
          "<settings-for-the-resource>",
          "copy": [
              {
                  "name": ,
                  "count": ,
                  "input": {}
              }
          ]
      },
      "resources": [
          "<array-of-child-resources>"
      ]
  }
]
Elementnamn Krävs Beskrivning
Villkor Inga Booleskt värde som anger om resursen ska etableras under den här distributionen. När trueskapas resursen under distributionen. När falsehoppas resursen över för den här distributionen. Se villkor.
typ Ja Resurstyp. Det här värdet är en kombination av namnområdet för resursprovidern och resurstypen (till exempel Microsoft.Storage/storageAccounts). Information om tillgängliga värden finns i mallreferensen. För en underordnad resurs beror formatet på typen på om den är kapslad i den överordnade resursen eller definieras utanför den överordnade resursen. Se Ange namn och typ för underordnade resurser.
apiVersion Ja Version av REST-API:et som ska användas för att skapa resursen. När du skapar en ny mall anger du det här värdet till den senaste versionen av resursen som du distribuerar. Så länge mallen fungerar efter behov fortsätter du att använda samma API-version. Genom att fortsätta att använda samma API-version minimerar du risken för att en ny API-version ändrar hur mallen fungerar. Överväg att uppdatera API-versionen endast när du vill använda en ny funktion som introduceras i en senare version. Information om tillgängliga värden finns i mallreferensen.
name Ja Namn på resursen. Namnet måste följa URI-komponentbegränsningar som definierats i RFC3986. Azure-tjänster som exponerar resursnamnet för externa parter verifierar namnet för att se till att det inte är ett försök att förfalska en annan identitet. För en underordnad resurs beror namnets format på om det är kapslat i den överordnade resursen eller definierat utanför den överordnade resursen. Se Ange namn och typ för underordnade resurser.
kommentarer Inga Dina anteckningar för att dokumentera resurserna i mallen. Mer information finns i Kommentarer i mallar.
location Det varierar Geoplatser som stöds för den angivna resursen. Du kan välja någon av de tillgängliga platserna, men vanligtvis är det klokt att välja en som är nära dina användare. Vanligtvis är det också bra att placera resurser som interagerar med varandra i samma region. De flesta resurstyper kräver en plats, men vissa typer (till exempel en rolltilldelning) kräver ingen plats. Se Ange resursplats.
dependsOn Inga Resurser som måste distribueras innan den här resursen distribueras. Resource Manager utvärderar beroenden mellan resurser och distribuerar dem i rätt ordning. När resurser inte är beroende av varandra distribueras de parallellt. Värdet kan vara en kommaavgränsad lista över resursnamn eller unika resursidentifierare. Visa endast en lista över resurser som har distribuerats i den här mallen. Resurser som inte har definierats i den här mallen måste redan finnas. Undvik att lägga till onödiga beroenden eftersom de kan göra distributionen långsammare och skapa cirkulära beroenden. Vägledning om hur du anger beroenden finns i Definiera ordningen för distribution av resurser i ARM-mallar.
tags Inga Taggar som är associerade med resursen. Använd taggar för att logiskt organisera resurser i hela prenumerationen.
identity Inga Vissa resurser stöder hanterade identiteter för Azure-resurser. Dessa resurser har ett identitetsobjekt på resursdeklarationens rotnivå. Du kan ange om identiteten är användartilldelad eller systemtilldelad. För användartilldelade identiteter anger du en lista över resurs-ID:n för identiteterna. Ange nyckeln till resurs-ID och värdet till ett tomt objekt. Mer information finns i Konfigurera hanterade identiteter för Azure-resurser på en virtuell Azure-dator med hjälp av mallar.
sku Inga Vissa resurser tillåter värden som definierar SKU:n att distribuera. Du kan till exempel ange typen av redundans för ett lagringskonto.
Typ Inga Vissa resurser tillåter ett värde som definierar vilken typ av resurs du distribuerar. Du kan till exempel ange vilken typ av Azure Cosmos DB-instans som ska skapas.
omfång Inga Omfångsegenskapen är endast tillgänglig för tilläggsresurstyper. Använd det när du anger ett omfång som skiljer sig från distributionsomfånget. Se Ange omfång för tilläggsresurser i ARM-mallar.
kopiering Inga Om mer än en instans behövs, antalet resurser som ska skapas. Standardläget är parallellt. Ange serieläge när du inte vill att alla eller resurserna ska distribueras samtidigt. Mer information finns i Skapa flera instanser av resurser i Azure Resource Manager.
planera Inga Vissa resurser tillåter värden som definierar planen för distribution. Du kan till exempel ange Marketplace-avbildningen för en virtuell dator.
properties Inga Resursspecifika konfigurationsinställningar. Värdena för egenskaperna är samma som de värden som du anger i begärandetexten för REST API-åtgärden (PUT-metoden) för att skapa resursen. Du kan också ange en kopieringsmatris för att skapa flera instanser av en egenskap. Information om hur du fastställer tillgängliga värden finns i mallreferensen.
resources Inga Underordnade resurser som är beroende av den resurs som definieras. Ange endast resurstyper som tillåts av schemat för den överordnade resursen. Beroendet av den överordnade resursen är inte underförstått. Du måste uttryckligen definiera det beroendet. Se Ange namn och typ för underordnade resurser.

Se resurser i Bicep.

Utdata

I avsnittet outputs anger du värden som returneras från distributionen. Vanligtvis returnerar du värden från resurser som har distribuerats. Du är begränsad till 64 utdata i en mall.

I följande exempel visas strukturen för en utdatadefinition:

"outputs": {
  "<output-name>": {
    "condition": "<boolean-value-whether-to-output-value>",
    "type": "<type-of-output-value>",
    "value": "<output-value-expression>",
    "copy": {
      "count": <number-of-iterations>,
      "input": <values-for-the-variable>
    }
  }
}
Elementnamn Krävs Beskrivning
output-name Ja Namnet på utdatavärdet. Måste vara en giltig JavaScript-identifierare.
Villkor Inga Booleskt värde som anger om det här utdatavärdet returneras. När trueingår värdet i utdata för distributionen. När falsehoppas utdatavärdet över för den här distributionen. När det inte anges är truestandardvärdet .
typ Ja Typ av utdatavärde. Utdatavärden stöder samma typer som mallens indataparametrar. Om du anger securestring för utdatatypen visas inte värdet i distributionshistoriken och kan inte hämtas från en annan mall. Om du vill använda ett hemligt värde i mer än en mall lagrar du hemligheten i en 密钥保管库 och refererar till hemligheten i parameterfilen. Mer information finns i Använda Azure 密钥保管库 för att skicka säkert parametervärde under distributionen.
värde Inga Mallspråkuttryck som utvärderas och returneras som utdatavärde. Ange antingen värde eller kopia.
kopiering Inga Används för att returnera fler än ett värde för utdata. Ange värde eller kopia. Mer information finns i Utdataiteration i ARM-mallar.

Exempel på hur du använder utdata finns i Utdata i ARM-mall.

Se utdata i Bicep.

Kommentarer och metadata

Du har några alternativ för att lägga till kommentarer och metadata i mallen.

Kommentarer

För infogade kommentarer kan du använda antingen // eller /* ... */. I Visual Studio Code sparar du parameterfilerna med kommentarer som JSON-filtypen med kommentarer (JSONC), annars får du ett felmeddelande om att kommentarer inte tillåts i JSON.

Anteckning

När du använder Azure CLI för att distribuera mallar med kommentarer använder du version 2.3.0 eller senare och anger växeln --handle-extended-json-format .

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2018-10-01",
  "name": "[variables('vmName')]", // to customize name, change it in variables
  "location": "[parameters('location')]", //defaults to resource group location
  "dependsOn": [ /* storage account and network interface must be deployed first */
    "[resourceId('Microsoft.Storage/storageAccounts/', variables('storageAccountName'))]",
    "[resourceId('Microsoft.Network/networkInterfaces/', variables('nicName'))]"
  ],

I Visual Studio Code kan tillägget Azure Resource Manager Tools automatiskt identifiera en ARM-mall och ändra språkläget. Om du ser Azure Resource Manager Template längst ned till höger i Visual Studio Code kan du använda infogade kommentarer. Infogade kommentarer markeras inte längre som ogiltiga.

Visual Studio Code Azure Resource Manager mallläge

I Bicep kan du se kommentarer.

Metadata

Du kan lägga till ett metadata objekt nästan var som helst i mallen. Resource Manager ignorerar objektet, men JSON-redigeraren kan varna dig om att egenskapen inte är giltig. I objektet definierar du de egenskaper som du behöver.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "metadata": {
    "comments": "This template was developed for demonstration purposes.",
    "author": "Example Name"
  },

För parameterslägger du till ett metadata objekt med en description egenskap.

"parameters": {
  "adminUsername": {
    "type": "string",
    "metadata": {
      "description": "User name for the Virtual Machine."
    }
  },

När du distribuerar mallen via portalen används den text som du anger i beskrivningen automatiskt som ett tips för den parametern.

Visa parametertips

För resourceslägger du till ett comments element eller ett metadata objekt. I följande exempel visas både ett comments element och ett metadata objekt.

"resources": [
  {
    "type": "Microsoft.Storage/storageAccounts",
    "apiVersion": "2018-07-01",
    "name": "[concat('storage', uniqueString(resourceGroup().id))]",
    "comments": "Storage account used to store VM disks",
    "location": "[parameters('location')]",
    "metadata": {
      "comments": "These tags are needed for policy compliance."
    },
    "tags": {
      "Dept": "[parameters('deptName')]",
      "Environment": "[parameters('environment')]"
    },
    "sku": {
      "name": "Standard_LRS"
    },
    "kind": "Storage",
    "properties": {}
  }
]

För outputslägger du till ett metadata objekt i utdatavärdet.

"outputs": {
  "hostname": {
    "type": "string",
    "value": "[reference(variables('publicIPAddressName')).dnsSettings.fqdn]",
    "metadata": {
      "comments": "Return the fully qualified domain name"
    }
  },

Du kan inte lägga till ett metadata objekt i användardefinierade funktioner.

Flerradssträngar

Du kan dela upp en sträng i flera rader. Se till exempel location egenskapen och en av kommentarerna i följande JSON-exempel.

Anteckning

Om du vill distribuera mallar med flerradssträngar använder du Azure PowerShell eller Azure CLI. För CLI använder du version 2.3.0 eller senare och anger växeln --handle-extended-json-format .

Flerradssträngar stöds inte när du distribuerar mallen via Azure-Portal, en DevOps-pipeline eller REST API.

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2018-10-01",
  "name": "[variables('vmName')]", // to customize name, change it in variables
  "location": "[
    parameters('location')
    ]", //defaults to resource group location
  /*
    storage account and network interface
    must be deployed first
  */
  "dependsOn": [
    "[resourceId('Microsoft.Storage/storageAccounts/', variables('storageAccountName'))]",
    "[resourceId('Microsoft.Network/networkInterfaces/', variables('nicName'))]"
  ],

Se flerradssträngar i Bicep.

Nästa steg