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 har viss kunskap om 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.

Mallformat

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

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "",
  "contentVersion": "",
  "apiProfile": "",
  "definitions": { },
  "parameters": { },
  "variables": { },
  "functions": [ ],
  "resources": [ ], /* or "resources": { } with languageVersion 2.0 */
  "outputs": { }
}

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

Definitioner

I avsnittet definitions i mallen anger du de scheman som används för att validera matris- och objektvärden. Definitions kan endast användas med languageVersion 2.0.

"definitions": {
  "<definition-name": {
    "type": "<data-type-of-definition>",
    "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>,
    "prefixItems": <schema-for-validating-array>,
    "items": <schema-for-validating-array-or-boolean>,
    "properties": <schema-for-validating-object>,
    "additionalProperties": <schema-for-validating-object-or-boolean>,
    "discriminator": <schema-to-apply>,
    "nullable": <boolean>,
    "metadata": {
      "description": "<description-of-the-type-definition>"
    }
  }
}

Exempel på hur du använder typdefinitioner finns i Typdefinitioner i ARM-mallar.

I Bicep läser du Användardefinierade datatyper.

Parametrar

I avsnittet parameters 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>,
    "prefixItems": <schema-for-validating-array>,
    "items": <schema-for-validating-array-or-boolean>,
    "properties": <schema-for-validating-object>,
    "additionalProperties": <schema-for-validating-object-or-boolean>,
    "discriminator": <schema-to-apply>,
    "nullable": <boolean>,
    "metadata": {
      "description": "<description-of-the parameter>"
    }
  }
}

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.

I Bicep, se variabler.

Funktioner

I mallen kan du skapa egna funktioner. Dessa funktioner är tillgängliga för användning i mallen. Vanligtvis definierar du komplicerade uttryck som du inte vill upprepa i hela 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>"
        }
      }
    }
  }
],

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

Om du vill stödja symboliskt Bicep-namn i ARM JSON-mallar lägger du till languageVersion med versionen 2.0 eller senare och ändrar resursdefinitionen från en matris till ett objekt.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",
  "resources": {
    "<name-of-the-resource>": {
      ...
    }
  }
}

Mer information finns i Resurser.

I Bicep, se resurser.

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

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

I Bicep, se utdata.

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 visas ett felmeddelande med texten "Kommentarer tillåts inte i JSON".

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2023-03-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 Azure Resource Manager Tools-tillägget automatiskt identifiera en ARM-mall och ändra språkläget. Om du ser Azure Resource Manager-mallen längst ned till höger i Visual Studio Code kan du använda infogade kommentarer. Infogade kommentarer markeras inte längre som ogiltiga.

I Bicep kan du läsa 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.

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": "2022-09-01",
    "name": "[format('{0}{1}', '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.

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2023-03-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'))]"
  ],

I Bicep kan du läsa flerradssträngar.

languageVersion 2.0

Om du vill använda languageVersion 2.0 lägger du till "languageVersion": "2.0" i mallen:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",
  "resources": {
    "<name-of-the-resource>": {
      ...
    }
  }
}

Förbättringar och ändringar som medföljer languageVersion 2.0:

• Använd symboliskt namn i ARM JSON-mallen. Mer information finns i Använda symboliskt namn.
• Använd symboliskt namn i resurskopieloopar. Se Använda symboliskt namn.
• Använd symboliskt namn i dependsOn matriser. Se DependsOn och Depend on resources in a loop (Beroenden och Beroende på resurser) i en loop.
• Använd symboliskt namn i stället för resursnamn i reference funktionen. Se hänvisning.
• En references()-funktion som returnerar en matris med objekt som representerar en resurssamlings körningstillstånd. Se referenser.
• Använd resursegenskapen "befintlig" för att deklarera befintliga resurser för ARM att läsa i stället för att distribuera en resurs. Se Deklarera befintliga resurser.
• Skapa användardefinierade typer. Se Typdefinition.
• Ytterligare verifieringsbegränsningar för aggregeringstyper som ska användas i parametrar och utdata.
• Standardvärdet för expressionEvaluationOptions egenskapen är inner. Värdet outer blockeras. Se Utvärderingsomfång för uttryck i kapslade mallar.
• Funktionen deployment returnerar en begränsad delmängd av egenskaper. Se distribution.
• Om Distributionsresursen används i en symbolisk namndistribution använder du apiVersion 2020-09-01 eller senare.
• I resursdefinitionen behövs inte längre dubbla escape-värden i ett uttryck. Se Escape-tecken.

Om du använder någon av följande Bicep-funktioner aktiveras automatiskt språkversion 2.0-kodgenerering:

• användardefinierade typer
• användardefinierade funktioner
• kompilera tidsimporter
• experimentella funktioner

Nästa steg

• Om du vill visa kompletta mallar för många olika typer av lösningar kan du se Azure-snabbstartsmallar.
• Mer information om de funktioner som du kan använda från en mall finns i ARM-mallfunktioner.
• Om du vill kombinera flera mallar under distributionen kan du läsa Använda länkade och kapslade mallar när du distribuerar Azure-resurser.
• Rekommendationer om hur du skapar mallar finns i Metodtips för ARM-mallar.
• Svar på vanliga frågor finns i Vanliga frågor och svar om ARM-mallar.