Aracılığıyla paylaş

Bicep'te Azure Resource Manager şablonu belirtimleri

Şablon belirtimi, daha sonra dağıtmak üzere bir Azure Resource Manager şablonunun (ARM şablonu) depolanmasına yönelik bir kaynak türüdür. Bu kaynak türü, ARM şablonlarını kuruluşunuzdaki diğer kullanıcılarla paylaşmanızı sağlar. Diğer tüm Azure kaynaklarda olduğu gibi, şablon belirtimini paylaşmak için Azure rol tabanlı erişim denetimini (Azure RBAC) kullanabilirsiniz. Bicep dosyaları sağlayarak şablon belirtimleri oluşturmak için Azure CLI veya Azure PowerShell kullanabilirsiniz. Bicep dosyaları depolanmadan önce JSON ARM şablonlarına dönüştürülür. Şu anda şablon belirtimi kaynağı oluşturmak için Azure portalından bicep dosyasını içeri aktaramazsınız.

Microsoft.Resources/templateSpecs, şablon belirtimleri için kaynak türüdür. Bir ana şablondan ve herhangi bir sayıda bağlantılı şablondan oluşur. Azure, şablon belirtimlerini kaynak gruplarında güvenli bir şekilde depolar. Hem ana şablon hem de bağlantılı şablonlar JSON'da olmalıdır. Şablon Özellikleri sürüm oluşturma desteği sağlar.

Şablon belirtimini dağıtmak için PowerShell, Azure CLI, Azure portalı, REST ve diğer desteklenen SDK'lar ve istemciler gibi standart Azure araçlarını kullanın. Şablon veya Bicep dosyası için kullandığınız komutların aynısını kullanırsınız.

Not

Azure PowerShell ile Bicep'te şablon belirtimlerini kullanmak için 6.3.0 veya sonraki bir sürümü yüklemeniz gerekir. Azure CLI ile kullanmak için 2.27.0 veya sonraki bir sürümü kullanın.

Dağıtımınızı tasarlarken her zaman kaynakların yaşam döngüsünü göz önünde bulundurun ve benzer yaşam döngüsünü paylaşan kaynakları tek bir şablon belirtiminde gruplandırın. Örneğin dağıtımlarınız, her örneği kendi veritabanlarını ve kapsayıcılarını içeren birden çok Azure Cosmos DB örneğini içerir. Veritabanları ve kapsayıcılar çok fazla değişmediğinden, Cosmo DB örneğini ve temel veritabanlarını ve kapsayıcılarını içerecek bir şablon belirtimi oluşturmak istiyorsunuz. Daha sonra bu kaynakların birden çok örneğini oluşturmak için Bicep'inizde koşullu deyimleri ve kopyalama döngülerini kullanabilirsiniz.

İpucu

Modül kayıt defteri ve şablon özellikleri arasındaki seçim çoğunlukla tercih konusudur. İkisi arasında seçim yaparken göz önünde bulundurmanız gereken birkaç şey vardır:

  • Modül kayıt defteri yalnızca Bicep tarafından desteklenir. Henüz Bicep kullanmıyorsanız şablon belirtimlerini kullanın.
  • Bicep modülü kayıt defterindeki içerik yalnızca başka bir Bicep dosyasından dağıtılabilir. Şablon özellikleri doğrudan API, Azure PowerShell, Azure CLI ve Azure portalından dağıtılabilir. Azure portalı dağıtım deneyimini özelleştirmek için bile kullanabilirsiniz UiFormDefinition .
  • Bicep, diğer proje yapıtlarını (Bicep olmayan ve ARM şablonu olmayan dosyalar dahil) eklemek için bazı sınırlı özelliklere sahiptir. Örneğin, ve loadTextContent işlevlerini kullanarak loadFileAsBase64 PowerShell betikleri, CLI betikleri ve diğer ikili dosyalar). Şablon özellikleri bu yapıtları paketleyemez.

Gerekli izinler

Azure'da yerleşik olarak iki rol bulunur ve şablon belirtimleri için tanımlanır:

Ayrıca, bicep dosyasını dağıtmak için izinlere de ihtiyacınız vardır. Bkz. Azure CLI veya Azure PowerShell ile Bicep dosyalarını dağıtma.

Şablon belirtimlerini neden kullanmalısınız?

Şablon belirtimleri aşağıdaki avantajları sağlar:

  • Şablon belirtiminiz için standart ARM şablonları veya Bicep dosyaları kullanırsınız.
  • Erişimi paylaşılan erişim imzası belirteçleri yerine Azure RBAC aracılığıyla yönetirsiniz.
  • Kullanıcılar, Bicep dosyasına yazma erişimi olmadan şablon belirtimini dağıtabilir.
  • Şablon belirtimini PowerShell betiği veya DevOps işlem hattı gibi mevcut bir dağıtım işlemiyle tümleştirebilirsiniz.

Şablon özellikleri kurallı şablonlar oluşturmanıza ve bunları kuruluşunuzdaki ekiplerle paylaşmanıza olanak tanır. Şablon belirtimleri, dağıtım için Azure Resource Manager'da kullanılabildiğinden, ancak doğru izinlere sahip olmayan kullanıcılar tarafından erişilemediğinden güvenlidir. Kullanıcıların yalnızca şablonu dağıtmak için şablon belirtimine okuma erişimine ihtiyacı vardır, böylece şablonu başkalarının değiştirmesine izin vermeden paylaşabilirsiniz.

Şablonlarınız şu anda bir GitHub deposunda veya depolama hesabındaysa, şablonları paylaşmaya ve kullanmaya çalışırken çeşitli zorluklarla karşılaşırsınız. Şablonu dağıtmak için şablonu herkese açık hale getirmeniz veya SAS belirteçleriyle erişimi yönetmeniz gerekir. Bu sınırlamayı aşabilmek için kullanıcılar yerel kopyalar oluşturabilir ve bu kopyaların sonunda özgün şablonunuzdan farklı olması gerekir. Şablon belirtimleri şablonların paylaşımını basitleştirir.

Şablon belirtimine eklediğiniz şablonlar, kuruluşunuzun gereksinimlerini ve yönergelerini izlemek için kuruluşunuzdaki yöneticiler tarafından doğrulanmalıdır.

Şablon belirtimi oluşturma

Aşağıdaki örnekte Azure'da depolama hesabı oluşturmaya yönelik basit bir Bicep dosyası gösterilmektedir.

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
param storageAccountType string = 'Standard_LRS'

resource stg 'Microsoft.Storage/storageAccounts@2025-06-01' = {
  name:  'store${uniqueString(resourceGroup().id)}'
  location: resourceGroup().location
  sku: {
    name: storageAccountType
  }
  kind:'StorageV2'
}

Kullanarak bir şablon belirtimi oluşturun:

New-AzTemplateSpec -Name storageSpec -Version 1.0a -ResourceGroupName templateSpecsRg -Location westus2 -TemplateFile ./mainTemplate.bicep

Şablon belirtimleri oluşturmak için Bicep dosyalarını da kullanabilirsiniz. Ancak içeriğinin mainTemplate JSON içinde olması gerekir. Aşağıdaki şablon, depolama hesabı dağıtmak için bir şablon belirtimi oluşturur:

param templateSpecName string = 'CreateStorageAccount'
param templateSpecVersionName string = '0.1'
param location string = resourceGroup().location

resource createTemplateSpec 'Microsoft.Resources/templateSpecs@2022-02-01' = {
  name: templateSpecName
  location: location
  properties: {
    description: 'A basic templateSpec - creates a storage account.'
    displayName: 'Storage account (Standard_LRS)'
  }
}

resource createTemplateSpecVersion 'Microsoft.Resources/templateSpecs/versions@2022-02-01' = {
  parent: createTemplateSpec
  name: templateSpecVersionName
  location: location
  properties: {
    mainTemplate: {
      '$schema': 'https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#'
      'contentVersion': '1.0.0.0'
      'parameters': {
        'storageAccountType': {
          'type': 'string'
          'defaultValue': 'Standard_LRS'
          'allowedValues': [
            'Standard_LRS'
            'Standard_GRS'
            'Standard_ZRS'
            'Premium_LRS'
          ]
        }
      }
      'resources': [
        {
          'type': 'Microsoft.Storage/storageAccounts'
          'apiVersion': '2025-06-01'
          'name': 'store$uniquestring(resourceGroup().id)'
          'location': resourceGroup().location
          'kind': 'StorageV2'
          'sku': {
            'name': '[parameters(\'storageAccountType\')]'
          }
        }
      ]
    }
  }
}

Bicep dosyasına eklenmiş JSON şablonunun şu değişiklikleri yapması gerekir:

  • Satırların sonundaki virgülleri kaldırın.
  • Çift tırnakları tek tırnakla değiştirin.
  • İfadelerin içindeki tek tırnak işaretinden kaçış. Örneğin, 'name': '[parameters(\'storageAccountType\')]'.
  • Bicep dosyasında tanımlanan parametrelere ve değişkenlere erişmek için parametre adlarını ve değişken adlarını doğrudan kullanabilirsiniz. içinde mainTemplatetanımlanan parametrelere ve değişkenlere erişmek için yine de JSON ARM şablonu söz dizimini kullanmanız gerekir. Örneğin, 'name': '[parameters(\'storageAccountType\')]'.
  • Bicep işlevlerini çağırmak için Bicep söz dizimini kullanın. Örneğin, 'location': resourceGroup().location.

Şablon belirtiminin boyutu yaklaşık 2 megabayt ile sınırlıdır. Şablon belirtim boyutu sınırı aşarsa TemplateSpecTooLarge hata kodunu alırsınız. Hata iletisinde şöyle yazıyor:

The size of the template spec content exceeds the maximum limit. For large template specs with many artifacts, the recommended course of action is to split it into multiple template specs and reference them modularly via TemplateLinks.

Aboneliğinizdeki tüm şablon belirtimlerini şu şekilde görüntüleyebilirsiniz:

Get-AzTemplateSpec

Bir şablon belirtiminin, sürümleri de dahil olmak üzere ayrıntılarını şu şekilde görüntüleyebilirsiniz:

Get-AzTemplateSpec -ResourceGroupName templateSpecsRG -Name storageSpec

Şablon belirtimlerini dağıtma

Şablon belirtimini oluşturduktan sonra, Şablon Belirtimi Okuyucusu rolüne sahip kullanıcılar bunu dağıtabilir. ARM şablonunu dağıtmak için uygun izinlere ihtiyacınız olduğunu unutmayın.

Şablon özellikleri Azure portalı, PowerShell, Azure CLI aracılığıyla veya daha büyük bir şablon dağıtımında Bicep modülü olarak dağıtılabilir. Bir kuruluştaki kullanıcılar Azure'daki herhangi bir kapsama (örneğin, kaynak grubu, abonelik, yönetim grubu veya kiracı) bir şablon belirtimi dağıtabilir.

Şablon belirtimini, bir Bicep dosyası için bir yol veya URI'ye geçirmek yerine kaynak kimliğini sağlayarak dağıtırsınız. Kaynak kimliği aşağıdaki biçime sahiptir; şablon belirtimi için bir sürüm adı içerdiğine dikkat edin:

/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.Resources/templateSpecs/{template-spec-name}/versions/{template-spec-version}

Aşağıdaki komutlarla bir şablon belirtimi dağıtabilirsiniz:

$id = "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/templateSpecsRG/providers/Microsoft.Resources/templateSpecs/storageSpec/versions/1.0a"

New-AzResourceGroupDeployment `
  -TemplateSpecId $id `
  -ResourceGroupName demoRG

Uygulamada, genellikle dağıtmak istediğiniz şablon belirtiminin kimliğini almak için veya Get-AzTemplateSpec komutunu çalıştırırsınızaz ts show.

$id = (Get-AzTemplateSpec -Name storageSpec -ResourceGroupName templateSpecsRg -Version 1.0a).Versions.Id

New-AzResourceGroupDeployment `
  -ResourceGroupName demoRG `
  -TemplateSpecId $id

Url'yi aşağıdaki biçimde açarak şablon belirtimini de dağıtabilirsiniz:

https://portal.azure.com/#create/Microsoft.Template/templateSpecVersionId/%2fsubscriptions%2f{subscription-id}%2fresourceGroups%2f{resource-group-name}%2fproviders%2fMicrosoft.Resources%2ftemplateSpecs%2f{template-spec-name}%2fversions%2f{template-spec-version}

Parametreler

Parametrelerin bir şablon belirtimine geçirilmesi, parametreleri bicep dosyasına geçirmeye benzer. Parametre değerlerini satır içi veya parametre dosyasına ekleyin.

Satır içi parametreler

Bir parametreyi satır içinde geçirmek için şunu kullanın:

New-AzResourceGroupDeployment `
  -TemplateSpecId $id `
  -ResourceGroupName demoRG `
  -StorageAccountType Standard_GRS

Parametre dosyaları

  • Bicep parametre dosyalarını kullanın.

    Bicep parametre dosyası oluşturmak için deyimini belirtmeniz using gerekir. Örneğin:

    using 'using 'ts:<subscription-id>/<resource-group-name>/<template-spec-name>:<tag>'

param StorageAccountType = 'Standard_GRS'

    Daha fazla bilgi için bkz . Bicep dağıtımı için parametre dosyaları oluşturma.

    Parametre dosyalarını şu şekilde geçirin:

    Şu anda bir dosyayla .bicepparam şablon belirtimi dağıtmak için PowerShell'i kullanamazsınız.

  • JSON parametre dosyalarını kullanın.

    Aşağıdaki JSON örnek bir JSON parametre dosyasıdır:

    {
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "StorageAccountType": {
      "value": "Standard_GRS"
    }
  }
}

    Parametre dosyasını şu şekilde de geçirebilirsiniz:

    New-AzResourceGroupDeployment `
  -TemplateSpecId $id `
  -ResourceGroupName demoRG `
  -TemplateParameterFile ./mainTemplate.parameters.json

Sürüm oluşturma

Şablon oluşturduğunuzda şablon belirtimi için bir sürüm adı sağlarsınız. Şablon kodunu yinelerken, var olan bir sürümü güncelleştirebilir (düzeltmeler için) veya yeni bir sürüm yayımlayabilirsiniz. Sürüm bir metin dizesidir. Anlamsal sürüm oluşturma dahil olmak üzere herhangi bir sürüm oluşturma sistemini izlemeyi seçebilirsiniz. Şablon belirtimi kullanıcıları, dağıtırken kullanmak istedikleri sürüm adını sağlayabilir ve sınırsız sayıda sürüme sahip olabilir.

Etiketleri kullanma

Etiketler , kaynaklarınızı mantıksal olarak düzenlemenize yardımcı olur. Şablon özelliklerine etiket eklemek için Azure PowerShell veya Azure CLI kullanabilirsiniz. Aşağıdaki örnek, şablon belirtimini oluştururken etiketlerin nasıl belirtileceğini gösterir:

New-AzTemplateSpec `
  -Name storageSpec `
  -Version 1.0a `
  -ResourceGroupName templateSpecsRg `
  -Location westus2 `
  -TemplateFile ./mainTemplate.bicep `
  -Tag @{Dept="Finance";Environment="Production"}

Aşağıdaki örnekte, mevcut şablon belirtimini güncelleştirirken etiketlerin nasıl uygulanacağı gösterilmektedir:

Set-AzTemplateSpec `
  -Name storageSpec `
  -Version 1.0a `
  -ResourceGroupName templateSpecsRg `
  -Location westus2 `
  -TemplateFile ./mainTemplate.bicep `
  -Tag @{Dept="Finance";Environment="Production"}

Hem şablonun hem de sürümlerinin etiketleri olabilir. Etiketler, belirttiğiniz parametrelere bağlı olarak uygulanır veya devralınır:

Şablon belirtimi Sürüm Sürüm parametresi Etiket parametresi Etiket değerleri
Exists Yok Belirtilmemiş Belirtilen şablon belirtimine uygulandı
Exists Yeni Belirtilen Belirtilmemiş şablon belirtiminden sürüme devralındı
Yeni Yeni Belirtilen Belirtilen hem şablon belirtimine hem de sürüme uygulandı
Exists Yeni Belirtilen Belirtilen sürüme uygulandı
Exists Exists Belirtilen Belirtilen sürüme uygulandı

  • Bir şablon belirtimi oluşturduktan sonra, bir Bicep modülünde bu şablon belirtimine bağlanabilirsiniz. Bu modülü içeren Bicep dosyasını dağıttığınızda şablon belirtimi dağıtılır. Daha fazla bilgi için bkz . Modülün yolu.

  • Modül bağlamaya yönelik şablon belirtimlerine yönelik diğer adlar oluşturmak için bkz . Modüller için diğer adlar.

Sonraki adımlar

Şablon belirtimleri hakkında uygulamalı yönergeler için Bkz. Şablon belirtimleri oluşturma.

  • Last updated on