Az ARM-sablonok struktúrájának és szintaxisának megismerése

Ez a cikk a Azure Resource Manager (ARM-sablon) struktúráját ismerteti. Bemutatja a sablon különböző szakaszait és az abban elérhető tulajdonságokat.

Ez a cikk olyan felhasználóknak való, akik ismerik az ARM-sablonokat. Részletes információkat nyújt a sablon szerkezetével kapcsolatban. A sablonok létrehozásának folyamatán végigvezető részletes oktatóanyagért lásd: Oktatóanyag: Az első ARM-sablon létrehozásaés üzembe helyezése. Az ARM-sablonok interaktív modulkészleten keresztüli megismerése a Microsoft Learn: Erőforrások üzembe helyezése és kezelése az Azure-ban ARM-sablonok használatával.

Sablon formátuma

A sablon legegyszerűbb struktúrája a következő elemeket tartalmazza:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "",
  "apiProfile": "",
  "parameters": {  },
  "variables": {  },
  "functions": [  ],
  "resources": [  ],
  "outputs": {  }
}
Elem neve Kötelező Leírás
$schema Yes A sablonnyelv JavaScript Object Notation (JSON) sémafájljának helye. A használt verziószám az üzemelő példány hatókörétől és a JSON-szerkesztőtől függ.

Ha a Visual Studio Code-et használja a Azure Resource Manager Toolsbővítvítménysel, használja a legújabb verziót az erőforráscsoportok üzembe helyezéséhez:
https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#

Előfordulhat, hogy más szerkesztők (Visual Studio) nem tudják feldolgozni ezt a sémát. Ezekhez a szerkesztőkhez használja a következőt:
https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#

Előfizetések üzembe helyezéséhez használja a következőt:
https://schema.management.azure.com/schemas/2018-05-01/subscriptionDeploymentTemplate.json#

Felügyeleti csoportok központi telepítéséhez használja a következőt:
https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#

Bérlői üzemelő példányok esetén használja a következőt:
https://schema.management.azure.com/schemas/2019-08-01/tenantDeploymentTemplate.json#
contentVersion (tartalomverzió) Yes A sablon verziója (például 1.0.0.0). Ehhez az elemhez bármilyen értéket meg lehet adni. Ezzel az értékkel dokumentálja a sablon jelentős változásait. Amikor erőforrásokat helyez üzembe a sablon használatával, ezzel az értékkel győződhet meg arról, hogy a megfelelő sablont használja.
apiProfile No Egy API-verzió, amely az erőforrástípusok API-verzióinak gyűjteményeként szolgál. Ezzel az értékkel elkerülheti, hogy a sablonban minden egyes erőforráshoz API-verziót kelljen megadnia. Ha megad egy API-profilverziót, és nem ad meg API-verziót az erőforrástípushoz, a Resource Manager a profilban meghatározott API-verziót használja az adott erőforrástípushoz.

Az API-profiltulajdonság különösen hasznos, ha különböző környezetekben, például az Azure-ban Azure Stack üzembe helyez egy sablont. Az API-profil verziójával győződjön meg arról, hogy a sablon automatikusan a mindkét környezetben támogatott verziókat használja. Az AKTUÁLIS API-profilverziók és a profilban definiált erőforrások API-verzióinak listáját lásd: API-profil.

További információ: Verziók nyomon követése API-profilokkal.
Paraméterek No Az üzembe helyezés végrehajtásakor megadott értékek az erőforrások üzembe helyezésének testreszabásához.
Változók No A sablonban JSON-töredékekként használt értékek a sablonnyelvi kifejezések egyszerűsítéséhez.
Funkciók No A sablonon belül elérhető, felhasználó által definiált függvények.
Erőforrások Yes Erőforráscsoportban vagy előfizetésben üzembe helyezett vagy frissített erőforrástípusok.
Kimenetek No Az üzembe helyezés után visszaadott értékek.

Minden elem rendelkezik beállítható tulajdonságokkal. Ez a cikk részletesebben ismerteti a sablon szakaszait.

Paraméterek

A sablon szakaszában megadhatja, hogy mely értékeket adhatja meg az erőforrások parameters üzembe helyezésekor. Egy sablonban legfeljebb 256 paramétert használhat. A paraméterek számát több tulajdonságot tartalmazó objektumok használatával csökkentheti.

A paraméterek elérhető tulajdonságai a következők:

"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>"
    }
  }
}
Elem neve Kötelező Leírás
paraméternév Yes A paraméter neve. Érvényes JavaScript-azonosítónak kell lennie.
típus Yes A paraméterérték típusa. Az engedélyezett típusok és értékek a következőek: string, securestring, int, bool, object, secureObject, és array. Lásd: Adattípusok ARM-sablonokban.
defaultValue (alapértelmezett érték) No A paraméter alapértelmezett értéke, ha nincs megadva érték a paraméterhez.
allowedValues (engedélyezett érték) No A paraméter engedélyezett értékeinek tömbje, amely biztosítja, hogy a megfelelő érték legyen megadva.
minValue (minimális érték) No Az int típusú paraméterek minimális értéke, amely a befogadó érték.
maxValue (maximális érték) No Az int típusú paraméterek maximális értéke, amely a befogadó érték.
Minlength No A sztring, a biztonságos sztring és a tömbtípus paramétereinek minimális hossza, ez az érték befogadó.
Maxlength No A sztring, a biztonságos sztring és a tömbtípus paramétereinek maximális hossza, ez az érték befogadó.
leírás No A felhasználók számára a portálon keresztül megjelenített paraméter leírása. További információ: Megjegyzések a sablonokban.

Példák a paraméterek használatára: Paraméterek az ARM-sablonokban.

Változók

A szakaszban variables olyan értékeket fog létrehozni, amelyek a sablonban használhatók. Nem kell változókat definiálni, de gyakran leegyszerűsítik a sablont az összetett kifejezések csökkentésével. Az egyes változók formátuma megegyezik az adattípusok egyikének formátumával.

Az alábbi példa a változó definiálása során rendelkezésre álló lehetőségeket mutatja be:

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

További információ a változók több copy értékének létrehozásáról: Változó iterációja.

Példák a változók használatára: Változók az ARM-sablonban.

Functions

A sablonon belül saját függvényeket is létrehozhat. Ezek a függvények a sablonban használhatók. Általában olyan összetett kifejezéseket definiál, amelyek nem ismétlődnek a sablonban. A felhasználó által definiált függvényeket sablonokban támogatott kifejezésekből és függvényekből hozhatja létre.

A felhasználói függvények meghatározásakor bizonyos korlátozások vonatkoznak:

  • A függvény nem fér hozzá a változókhoz.
  • A függvény csak a függvényben definiált paramétereket használhatja. Ha a parameters függvényt egy felhasználó által definiált függvényen belül használja, akkor a függvény paramétereire lesz korlátozva.
  • A függvény nem hívhat meg más, felhasználó által definiált függvényeket.
  • A függvény nem használhatja a referencia-függvényt.
  • A függvény paramétereinek nem lehet alapértelmezett értéke.
"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>"
        }
      }
    }
  }
],
Elem neve Kötelező Leírás
névtér Yes Az egyéni függvények névtere. A használatával elkerülheti a sablonfunkciók elnevezési ütközését.
függvény neve Yes Az egyéni függvény neve. A függvény hívatakor kombinálja a függvény nevét a névtérhez. Ha például a contoso névtérben egy nevű függvényt kell uniqueName hívnia, használja a "[contoso.uniqueName()]" következőt: .
paraméter-név No Az egyéni függvényben használt paraméter neve.
paraméter-érték No A paraméterérték típusa. Az engedélyezett típusok és értékek a következőek: string, securestring, int, bool, object, secureObject, és array.
output-type (kimenet típusa) Yes A kimeneti érték típusa. A kimeneti értékek a függvénybemeneti paraméterekkel azonos típusokat támogatnak.
output-value Yes A függvény által kiértékelt és onnan visszaadott sablonnyelvi kifejezés.

Példák az egyéni függvények használatára: Felhasználó által definiált függvények az ARM-sablonban.

Források

A szakaszban meghatározhatja az üzembe helyezett vagy frissített resources erőforrásokat.

Az erőforrásokat a következő struktúrával definiálhatja:

"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>"
      ]
  }
]
Elem neve Kötelező Leírás
Feltétel No Logikai érték, amely azt jelzi, hogy az erőforrás üzembe helyezése az üzembe helyezés során meg fog-e jelenni. A true létrehozásakor az erőforrás az üzembe helyezés során jön létre. Amikor false a rendszer kihagyja az erőforrást ehhez az üzemelő példányhoz. Lásd a feltételt.
típus Yes Az erőforrás típusa. Ez az érték az erőforrás-szolgáltató névterének és az erőforrástípusnak (például) a Microsoft.Storage/storageAccounts kombinációja. Az elérhető értékek meghatározásához tekintse meg a sablonreferenciát. Gyermekerőforrásnál a típus formátuma attól függ, hogy a szülőerőforrásba van beágyazva, vagy a szülőerőforráson kívül van definiálva. Lásd: Gyermekerőforrások nevének és típusának beállítása.
apiVersion Yes A REST API erőforrás létrehozásához használni. Új sablon létrehozásakor állítsa ezt az értéket az üzembe helyezett erőforrás legújabb verziójára. Amíg a sablon szükség szerint működik, továbbra is ugyanazt az API-verziót használja. Ha továbbra is ugyanazt az API-verziót használja, azzal minimálisra csökkentheti annak kockázatát, hogy egy új API-verzió módosítja a sablon működését. Az API-verziót csak akkor érdemes frissíteni, ha egy újabb verzióban bevezetett új funkciót szeretne használni. Az elérhető értékek meghatározásához tekintse meg a sablonreferenciát.
name Yes Az erőforrás neve. A névnek követnie kell az RFC3986 szabványban meghatározott URI-összetevőkorlátozásokat. Az erőforrásnevet külső felek számára elérhetővé tő Azure-szolgáltatások ellenőrzik a nevet, és ellenőrzik, hogy nem egy másik identitás hamisítására tett kísérletről van-e szó. Gyermekerőforrásnál a név formátuma attól függ, hogy a szülőerőforrásba van beágyazva, vagy a szülőerőforráson kívül van definiálva. Lásd: Gyermekerőforrások nevének és típusának beállítása.
megjegyzések No Megjegyzései a sablon erőforrásainak dokumentálása érdekében. További információ: Megjegyzések sablonokban.
location Változó A megadott erőforrás támogatott földrajzi helyei. Bármelyik elérhető helyet kiválaszthatja, de általában a felhasználókhoz közeli helyet kell választania. Általában az is logikus, hogy az egymással kommunikáló erőforrásokat ugyanabban a régióban helyezzük el. A legtöbb erőforrástípushoz hely szükséges, de egyes típusok (például a szerepkör-hozzárendelések) nem igényelnek helyet. Lásd: Erőforrás helyének beállítása.
dependsOn No Az erőforrásokat az erőforrás üzembe helyezése előtt kell üzembe helyezni. Resource Manager kiértékeli az erőforrások közötti függőségeket, és a megfelelő sorrendben telepíti őket. Ha az erőforrások nem függenek egymástól, a rendszer párhuzamosan üzembe helyezi őket. Az érték lehet egy erőforrásnevek vagy erőforrás-egyedi azonosítók vesszővel elválasztott listája. Csak az ebben a sablonban üzembe helyezett erőforrásokat sorolja fel. Az ebben a sablonban nem definiált erőforrásoknak már léteznie kell. Kerülje a szükségtelen függőségek hozzáadását, mert lelassíthatja az üzembe helyezést, és körkörös függőségeket hozhat létre. A függőségek beállításával kapcsolatos útmutatásért lásd az erőforrások ARM-sablonokban való üzembe helyezésének sorrendjét.
tags No Az erőforráshoz társított címkék. Címkék alkalmazása az erőforrások logikai rendszerezéséhez az előfizetésben.
identity No Egyes erőforrások támogatják az Azure-erőforrások felügyelt identitását. Ezek az erőforrások egy identitásobjektummal rendelkezik az erőforrás-deklaráció gyökérszintje alatt. Megadhatja, hogy az identitás felhasználóhoz vagy rendszerhez legyen rendelve. Felhasználó által hozzárendelt identitások esetében adja meg az identitások erőforrás-azonosítóinak listáját. Állítsa a kulcsot az erőforrás-azonosítóra, az értékét pedig egy üres objektumra. További információ: Azure-erőforrások felügyelt identitásának konfigurálása Azure-beli virtuális gépen sablonok használatával.
Sku No Egyes erőforrások engedélyezik az üzembe helyező termékváltozatot meghatározó értékeket. Megadhatja például egy tárfiók redundanciának típusát.
Fajta No Egyes erőforrások olyan értéket engedik, amely meghatározza az üzembe helyezett erőforrás típusát. Megadhatja például a létrehozni kívánt Cosmos DB típusát.
scope No A hatókör tulajdonság csak a bővítmény típusú erőforrástípusokhoz érhető el. Akkor használja, ha a központi telepítési hatókörtől eltérő hatókört ad meg. Lásd: Setting scope for extension resources in ARM templates (Bővítmény-erőforrások hatókörének beállítása AZ ARM-sablonokban).
másolás No Ha egynél több példányra van szükség, a létrehozni szükséges erőforrások száma. Az alapértelmezett mód a párhuzamos. Akkor adja meg a soros módot, ha nem szeretné, hogy az összes erőforrás vagy az erőforrások egyszerre telepítsenek. További információ: Több erőforráspéldány létrehozásaa Azure Resource Manager.
Terv No Egyes erőforrások olyan értékeket engedélyeznek, amelyek meghatározzák az üzembe helyezési tervet. Megadhatja például egy virtuális gép piactéri rendszerképét.
properties No Erőforrás-specifikus konfigurációs beállítások. A tulajdonságok értékei ugyanazok, mint a kérelem törzsében megadott értékek a REST API (PUT metódus) számára az erőforrás létrehozásához. Egy tulajdonság több példányának létrehozásához megadhatja a másolási tömböt is. Az elérhető értékek meghatározásához tekintse meg a sablonreferenciát.
resources No A definiált erőforrástól függő gyermekerőforrások. Csak a szülőerőforrás sémája által engedélyezett erőforrástípusokat adja meg. A szülőerőforrástól való függőség nem implicit. Ezt a függőséget explicit módon kell meghatároznia. Lásd: Gyermekerőforrások nevének és típusának beállítása.

Kimenetek

A szakaszban outputs az üzembe helyezésből visszaadott értékeket adja meg. Általában az üzembe helyezett erőforrásokból ad vissza értékeket.

Az alábbi példa egy kimeneti definíció szerkezetét mutatja be:

"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>
    }
  }
}
Elem neve Kötelező Leírás
output-name (kimenet neve) Yes A kimeneti érték neve. Érvényes JavaScript-azonosítónak kell lennie.
Feltétel No Logikai érték, amely jelzi, hogy ez a kimeneti érték lesz-e visszaadva. Amikor a érték szerepel az üzemelő true példány kimenetében. Ha , a rendszer kihagyja a kimeneti false értéket ehhez az üzembe helyezéshez. Ha nincs megadva, az alapértelmezett érték true .
típus Yes A kimeneti érték típusa. A kimeneti értékek a sablonbemeneti paraméterekkel azonos típusokat támogatnak. Ha a kimenet típusaként a securestring értéket adja meg, az érték nem jelenik meg az üzembehelyezés előzményeiben, és nem olvasható be másik sablonból. Ha egynél több sablonban is titkos értéket használ, tárolja a titkos adatokat egy Key Vault a paraméterfájlban hivatkozva a titkos adatokat. További információ: Use Azure Key Vault to pass secure parameter value during deployment(Biztonságos paraméterértékek megadása az üzembe helyezés során az Azure Key Vault használatával).
érték No A kiértékelt és kimeneti értékként visszaadott sablonnyelvi kifejezés. Adja meg az értéket, vagy másolja a következőt:.
másolás No Egy kimenethez egynél több értéket ad vissza. Adja meg az értéket, vagy másolja a következőt:. További információ: Kimeneti iteráció ARM-sablonokban.

Példák a kimenetek használatára: Outputs in ARM template (Kimenetek ARM-sablonban).

Megjegyzések és metaadatok

Több lehetőség is van arra, hogy megjegyzéseket és metaadatokat fűz a sablonhoz.

Megjegyzések

Beágyazott megjegyzésekhez a vagy a // /* ... */ használható.

Megjegyzés

Ha az Azure CLI-t használja megjegyzésekhez fűző sablonok üzembe helyezéséhez, használja a 2.3.0-s vagy újabb verziót, és adja meg a --handle-extended-json-format kapcsolót.

{
  "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'))]"
  ],

A Visual Studio Code-ban az Azure Resource Manager Tools bővítmény automatikusan észleli az ARM-sablonokat, és megváltoztathatja a nyelvi módot. Ha a Azure Resource Manager jobb alsó sarkában használhatja a Visual Studio sablont, használhatja a beágyazott megjegyzéseket. A beágyazott megjegyzések már nem érvénytelenként vannak megjelölve.

Visual Studio Kód Azure Resource Manager sablon módban

Metaadatok

A sablonban szinte bárhol hozzáadhat metadata objektumot. Resource Manager figyelmen kívül hagyja az objektumot, de a JSON-szerkesztő figyelmeztetheti, hogy a tulajdonság érvénytelen. A objektumban adja meg a szükséges tulajdonságokat.

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

A parameters számára adjon hozzá egy objektumot egy metadata description tulajdonsággal.

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

Amikor a sablont a portálon keresztül telepíti, a rendszer automatikusan a leírásban megadott szöveget használja tippként az adott paraméterhez.

Paraméter tipp megjelenítése

A resources elemhez adjon hozzá comments egy elemet vagy egy metadata objektumot. Az alábbi példa egy elemet comments és egy objektumot is mutat metadata be.

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

A outputs parancshoz adjon hozzá egy objektumot a metadata kimeneti értékhez.

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

Felhasználó által definiált függvények metadata nem adhatnak hozzá objektumokat.

Többsoros sztringek

Egy sztringet több sorra is fel lehet tördörni. Például tekintse meg a location tulajdonságot és az alábbi JSON-példában található megjegyzések egyikét.

Megjegyzés

A többsoros sztringeket is tartalmazó sablonok üzembe helyezéséhez használja Azure PowerShell Azure CLI-t. A CLI-hez használja a 2.3.0-s vagy újabb verziót, és adja meg a --handle-extended-json-format kapcsolót.

A többsoros sztringek nem támogatottak, ha a sablont a Azure Portal, a DevOps-folyamaton vagy a 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'))]"
  ],

Következő lépések