ARM şablonlarının yapısını ve söz dizimini anlama

Bu makalede Azure Resource Manager şablonunun (ARM şablonu) yapısı açıklanır. Bir şablonun farklı bölümlerini ve bu bölümlerde kullanılabilen özellikleri sunar.

Bu makale ARM şablonları hakkında bilgi sahibi olan kullanıcılara yöneliktir. Şablonun yapısı hakkında ayrıntılı bilgi sağlar. Şablon oluşturma işleminde size yol gösteren adım adım öğretici için bkz . Öğretici: İlk ARM şablonunuzu oluşturma ve dağıtma. Destekli Learn modülleri aracılığıyla ARM şablonları hakkında bilgi edinmek için bkz. ARM şablonlarını kullanarak Azure'da kaynakları dağıtma ve yönetme.

Şablon biçimi

En basit yapısında, bir şablon aşağıdaki öğelere sahiptir:

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

Her öğenin ayarlayabileceğiniz özellikleri vardır. Bu makalede, şablonun bölümleri daha ayrıntılı olarak açıklanmaktadır.

Tanımlar

Şablonun definitions bölümünde, dizi ve nesne değerlerini doğrulamak için kullanılan şemaları belirtin. Definitions yalnızca languageVersion 2.0 ile kullanılabilir.

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

Tür tanımlarının nasıl kullanılacağına ilişkin örnekler için bkz. ARM şablonlarındaki tür tanımları.

Bicep'te bkz . Kullanıcı tanımlı veri türleri.

Parametreler

Şablonun parameters bölümünde, kaynakları dağıtırken hangi değerleri girebileceğinizi belirtirsiniz. Şablonda 256 parametreyle sınırlısınız. Birden çok özellik içeren nesneleri kullanarak parametre sayısını azaltabilirsiniz.

Bir parametre için kullanılabilir özellikler şunlardı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>"
    }
  }
}

Parametrelerin nasıl kullanılacağına ilişkin örnekler için bkz. ARM şablonlarındaki parametreler.

Bicep'te bkz. parametreler.

Değişkenler

variables bölümünde, şablonunuzun tamamında kullanılabilecek değerler oluşturursunuz. Değişkenleri tanımlamanız gerekmez, ancak bunlar genellikle karmaşık ifadeleri azaltarak şablonunuzu basitleştirir. Her değişkenin biçimi veri türlerinden biriyle eşleşir. Şablonda 256 değişkenle sınırlısınız.

Aşağıdaki örnekte değişken tanımlamaya yönelik kullanılabilir seçenekler gösterilmektedir:

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

Bir değişken için birkaç değer oluşturma hakkında copy bilgi için bkz . Değişken yinelemesi.

Değişkenleri kullanma örnekleri için bkz. ARM şablonundaki değişkenler.

Bicep'te değişkenlere bakın.

İşlevler

Şablonunuzun içinde kendi işlevlerinizi oluşturabilirsiniz. Bu işlevler şablonunuzda kullanılabilir. Genellikle, şablonunuzun tamamında yinelemek istemediğiniz karmaşık ifadeler tanımlarsınız. Şablonlarda desteklenen ifadelerden ve işlevlerden kullanıcı tanımlı işlevleri oluşturursunuz.

Kullanıcı işlevi tanımlarken bazı kısıtlamalar vardır:

• İşlev değişkenlere erişemiyor.
• İşlev yalnızca işlevde tanımlanan parametreleri kullanabilir. Kullanıcı tanımlı bir işlev içinde parameters işlevini kullandığınızda, bu işlevin parametreleriyle sınırlısınız demektir.
• İşlev, kullanıcı tanımlı diğer işlevleri çağıramaz.
• İşlev başvuru işlevini kullanamaz.
• İşlev parametrelerinin varsayılan değerleri olamaz.

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

Özel işlevlerin nasıl kullanılacağına ilişkin örnekler için bkz. ARM şablonunda kullanıcı tanımlı işlevler.

Bicep'te kullanıcı tanımlı işlevler desteklenmez. Bicep çeşitli işlevleri ve işleçleri destekler.

Kaynaklar

resources bölümünde dağıtılan veya güncelleştirilen kaynakları tanımlarsınız. Şablonda 800 kaynakla sınırlısınız.

Kaynakları aşağıdaki yapıyla tanımlarsınız:

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

ARM JSON şablonlarında Bicep sembolik adını desteklemek için, sürümüyle 2.0 veya daha yenisiyle ekleyin languageVersion ve bir dizideki kaynak tanımını bir nesne olarak değiştirin.

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

Daha fazla bilgi için bkz . Kaynaklar.

Bicep'te kaynaklara bakın.

Çıkışlar

outputs bölümünde, dağıtımdan döndürülen değerleri belirtirsiniz. Genellikle, dağıtılan kaynaklardan değerler döndürürsiniz. Şablonda 64 çıkışla sınırlısınız.

Aşağıdaki örnekte çıkış tanımının yapısı gösterilmektedir:

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

Çıkışları kullanma örnekleri için bkz. ARM şablonundaki çıkışlar.

Bicep'te çıkışlara bakın.

Açıklamalar ve meta veriler

Şablonunuz için açıklama ve meta veri eklemek için birkaç seçeneğiniz vardır.

Yorumlar

Satır içi açıklamalar için veya /* ... */kullanabilirsiniz//. Visual Studio Code'da, açıklama içeren parametre dosyalarını açıklamalar (JSONC) dosya türüyle JSON olarak kaydedin, aksi takdirde "JSON'da açıklamalara izin verilmiyor" hata iletisini alırsınız.

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

Visual Studio Code'da Azure Resource Manager Araçları uzantısı arm şablonunu otomatik olarak algılayabilir ve dil modunu değiştirebilir. Visual Studio Code sağ alt köşesinde Azure Resource Manager Şablonu görüyorsanız satır içi açıklamaları kullanabilirsiniz. Satır içi açıklamalar artık geçersiz olarak işaretlenmez.

Bicep'te yorumlara bakın.

Meta veri

Şablonunuzda neredeyse her yere nesne metadata ekleyebilirsiniz. Resource Manager nesneyi yoksayar, ancak JSON düzenleyiciniz özelliğin geçerli olmadığı konusunda sizi uyarabilir. nesnesinde, ihtiyacınız olan özellikleri tanımlayın.

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

için parametersözelliğine sahip bir metadatadescription nesne ekleyin.

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

Şablon portal aracılığıyla dağıtılırken, açıklamada sağladığınız metin otomatik olarak bu parametre için bir ipucu olarak kullanılır.

için resourcesbir comments öğe veya metadata nesne ekleyin. Aşağıdaki örnekte hem bir comments öğe hem de bir nesne gösterilmektedir metadata .

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

için outputsçıkış değerine bir metadata nesne ekleyin.

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

Kullanıcı tanımlı işlevlere nesne metadata ekleyemezsiniz.

Çok satırlı dizeler

Bir dizeyi birden çok satıra bölebilirsiniz. Örneğin, özelliğine location ve aşağıdaki JSON örneğindeki açıklamalardan birine bakın.

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

Bicep'te çok satırlı dizelere bakın.

languageVersion 2.0

languageVersion 2.0'ı kullanmak için şablonunuza ekleyin "languageVersion": "2.0" :

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

languageVersion 2.0 ile birlikte gelen iyileştirmeler ve değişiklikler:

• ARM JSON şablonunda sembolik ad kullanın. Daha fazla bilgi için bkz. Sembolik ad kullanma.
• Kaynak kopyalama döngülerinde sembolik ad kullanın. Bkz . Sembolik ad kullanma.
• Dizilerde dependsOn sembolik ad kullanın. Bkz . DependsOn ve Depend on resources in a loop.
• İşlevde reference kaynak adı yerine sembolik ad kullanın. Başvuruya bakın.
• Kaynak koleksiyonunun çalışma zamanı durumlarını temsil eden bir nesne dizisi döndüren references() işlevi. Başvurulara bakın.
• Arm'nin bir kaynağı dağıtmak yerine okuması için mevcut kaynakları bildirmek için 'mevcut' kaynak özelliğini kullanın. Bkz. Mevcut kaynakları bildirme.
• Kullanıcı tanımlı türler oluşturun. Bkz . Tür tanımı.
• Parametrelerde ve çıkışlarda kullanılacak ek toplama türü doğrulama kısıtlamaları.
• özelliği için expressionEvaluationOptions varsayılan değer şeklindedir inner. Değer outer engellenir. Bkz. İç içe şablonlardaki ifade değerlendirme kapsamı.
• işlevi özelliklerin deployment sınırlı bir alt kümesini döndürür. Bkz. dağıtım.
• Dağıtımlar kaynağı sembolik ad dağıtımında kullanılıyorsa apiVersion 2020-09-01 veya sonraki bir sürümü kullanın.
• Kaynak tanımında, bir ifade içindeki çift kaçış değerleri artık gerekli değildir. Bkz . Kaçış karakterleri.

Sonraki adımlar

• Farklı türlerde çözümler için tam şablonları görüntülemek üzere bkz. Azure Hızlı Başlangıç Şablonları.
• Şablon içinden kullanabileceğiniz işlevler hakkında ayrıntılı bilgi için bkz. ARM şablonu işlevleri.
• Dağıtım sırasında birkaç şablonu birleştirmek için bkz. Azure kaynaklarını dağıtırken bağlantılı ve iç içe şablonları kullanma.
• Şablon oluşturma hakkında öneriler için bkz. ARM şablonu en iyi yöntemleri.
• Sık sorulan soruların yanıtları için bkz. ARM şablonları hakkında sık sorulan sorular.