Bicep için en iyi yöntemler

  • Makale

Bu makalede, Bicep dosyalarınızı geliştirirken izlenecek uygulamalar önerilir. Bu uygulamalar, Bicep dosyanızın anlaşılmasını ve kullanılmasını kolaylaştırır.

Eğitim kaynakları

Adım adım yönergeler aracılığıyla Bicep en iyi yöntemleri hakkında bilgi edinmek isterseniz bkz. İşbirliği için Bicep kodunuzu yapılandırma.

Parametreler

  • Parametre bildirimleri için iyi adlandırma kullanın. İyi adlar, şablonlarınızın okunmasını ve anlaşılmasını kolaylaştırır. Net, açıklayıcı adlar kullandığınızdan ve adlandırmanızda tutarlı olduğunuzdan emin olun.

  • Şablonunuzun kullandığı parametreler hakkında dikkatli düşünün. Dağıtımlar arasında değişen ayarlar için parametreleri kullanmayı deneyin. Değişkenler ve sabit kodlanmış değerler, dağıtımlar arasında değişmeyen ayarlar için kullanılabilir.

  • Kullandığınız varsayılan değerlere dikkat edin. Varsayılan değerlerin herkes için güvenli olduğundan emin olun. Örneğin, şablonu test ortamına dağıtan birinin gereksiz yere büyük bir maliyete neden olmaması için düşük maliyetli fiyatlandırma katmanlarını ve SKU'ları kullanmayı göz önünde bulundurun.

  • @allowed Dekoratörü tedbirli kullanın. Bu dekoratörü çok geniş bir şekilde kullanırsanız geçerli dağıtımları engelleyebilirsiniz. Azure hizmetleri SKU'ları ve boyutları ekledikçe izin verilenler listenize güncel olmayabilir. Örneğin, üretimde yalnızca Premium v3 SKU'lara izin vermek mantıklı olabilir, ancak aynı şablonu üretim dışı ortamlarda kullanmanızı engeller.

  • Parametreleriniz için açıklama sağlamak iyi bir uygulamadır. Açıklamaları yararlı hale getirmeye çalışın ve şablonun parametre değerlerinin ne olması gerektiği hakkında önemli bilgileri sağlayın.

    Bicep dosyalarınıza not eklemek için açıklamaları da kullanabilirsiniz // .

  • Parametre bildirimlerini şablon dosyasının herhangi bir yerine koyabilirsiniz, ancak bu bildirimleri dosyanın en üstüne koyarak Bicep kodunuzun kolayca okunmasını sağlayabilirsiniz.

  • Adlandırmayı denetleen parametreler için en düşük ve en yüksek karakter uzunluğunu belirtmek iyi bir uygulamadır. Bu sınırlamalar, daha sonra dağıtım sırasında oluşan hataları önlemeye yardımcı olur.

Bicep parametreleri hakkında daha fazla bilgi için bkz. Bicep'te Parametreler.

Değişkenler

  • Bir değişken tanımladığınızda veri türü gerekli değildir. Değişkenler, çözüm değerinden türü çıkarsar.

  • Değişken oluşturmak için Bicep işlevlerini kullanabilirsiniz.

  • Bicep dosyanızda bir değişken tanımlandıktan sonra değişkenin adını kullanarak değere başvurursunuz.

Bicep değişkenleri hakkında daha fazla bilgi için bkz. Bicep'te değişkenler.

Adlar

  • veya myResourcegibi myVariableName adlar için küçük deve büyük/küçük harf kullanın.

  • uniqueString() işlevi, benzersiz kaynak adları oluşturmak için kullanışlıdır. Aynı parametreleri sağladığınızda, her seferinde aynı dizeyi döndürür. Kaynak grubu kimliğini geçirmek, dizenin aynı kaynak grubuna yapılan her dağıtımda aynı olduğu, ancak farklı kaynak gruplarına veya aboneliklere dağıttığınızda farklı olduğu anlamına gelir.

  • Bu örnekte olduğu gibi kaynak adları oluşturmak için şablon ifadelerini kullanmak iyi bir uygulamadır:

    param shortAppName string = 'toy'
param shortEnvironmentName string = 'prod'
param appServiceAppName string = '${shortAppName}-${shortEnvironmentName}-${uniqueString(resourceGroup().id)}'

    Kaynak adları oluşturmak için şablon ifadeleri kullanmak size çeşitli avantajlar sağlar:

    • tarafından uniqueString() oluşturulan dizeler anlamlı değildir. Proje veya ortam adının kısa tanımlayıcısı gibi anlamlı bilgiler içeren bir ad ve adın benzersiz olma olasılığını daha yüksek hale getirmek için rastgele bir bileşen oluşturmak için şablon ifadesi kullanmak yararlı olur.

    • İşlev, uniqueString() genel olarak benzersiz adları garanti etmez. Kaynak adlarınıza ek metin ekleyerek, var olan bir kaynak adını yeniden kullanılma olasılığını azaltmış olursunuz.

    • uniqueString() Bazen işlev bir sayı ile başlayan dizeler oluşturur. Depolama hesapları gibi bazı Azure kaynakları adlarının sayılarla başlamasına izin vermez. Bu gereksinim, kaynak adları oluşturmak için dize ilişkilendirme kullanmanın iyi bir fikir olduğu anlamına gelir. Benzersiz dizeye bir ön ek ekleyebilirsiniz.

    • Birçok Azure kaynak türünün izin verilen karakterler ve adlarının uzunluğu hakkında kuralları vardır. Kaynak adlarının oluşturulmasını şablona eklemek, şablonu kullanan herkesin bu kurallara uymayı hatırlamak zorunda olmadığı anlamına gelir.

  • Sembolik bir ad kullanmaktan name kaçının. Sembolik ad kaynağı temsil eder, kaynağın adını temsil eder. Örneğin, aşağıdaki söz dizimi yerine:

    resource cosmosDBAccountName 'Microsoft.DocumentDB/databaseAccounts@2023-11-15' = {

    Kullanın:

    resource cosmosDBAccount 'Microsoft.DocumentDB/databaseAccounts@2023-11-15' = {

  • Sonekler kullanarak değişkenleri ve parametreleri ayırt etmekten kaçının.

Kaynak tanımları

  • Karmaşık ifadeleri doğrudan kaynak özelliklerine eklemek yerine, ifadeleri içermek için değişkenleri kullanın. Bu yaklaşım, Bicep dosyanızın okunmasını ve anlaşılmasını kolaylaştırır. Kaynak tanımlarınızı mantıkla karmaşık hale getirmekten kaçınır.

  • Kaynakların nasıl davranacağıyla ilgili varsayımlar yapmak yerine çıkış olarak kaynak özelliklerini kullanmayı deneyin. Örneğin, bir App Service uygulamasının URL'sini almanız gerekiyorsa, URL için kendiniz bir dize oluşturmak yerine uygulamanın defaultHostname özelliğini kullanın. Bazen bu varsayımlar farklı ortamlarda doğru değildir veya kaynaklar çalışma şekillerini değiştirir. Kaynağın size kendi özelliklerini söylemesi daha güvenlidir.

  • Her kaynak için en son API sürümünü kullanmak iyi bir fikirdir. Azure hizmetlerindeki yeni özellikler bazen yalnızca daha yeni API sürümlerinde kullanılabilir.

  • Mümkün olduğunda, Bicep dosyanızda reference ve resourceId işlevlerini kullanmaktan kaçının. Sembolik adı kullanarak Bicep'teki herhangi bir kaynağa erişebilirsiniz. Örneğin, toyDesignDocumentsStorageAccount sembolik adıyla bir depolama hesabı tanımlarsanız, ifadesini toyDesignDocumentsStorageAccount.idkullanarak kaynak kimliğine erişebilirsiniz. Sembolik adı kullanarak kaynaklar arasında örtük bir bağımlılık oluşturursunuz.

  • Açık bağımlılıklar yerine örtük bağımlılıklar kullanmayı tercih edin. Kaynak özelliği kaynaklar arasında açık bir bağımlılık bildirmenize olanak sağlasa dependsOn da, genellikle diğer kaynağın sembolik adını kullanarak özelliklerini kullanmak mümkündür. Bu yaklaşım, iki kaynak arasında örtük bir bağımlılık oluşturur ve Bicep'in ilişkiyi yönetmesini sağlar.

  • Kaynak Bicep dosyasında dağıtılmıyorsa anahtar sözcüğünü kullanarak existing kaynağa sembolik bir başvuru alabilirsiniz.

Alt kaynaklar

  • Çok fazla derin katmanı iç içe yerleştirmekten kaçının. Çok fazla iç içe yerleştirme, Bicep kodunuzun okunmasını ve birlikte çalışmasını zorlaştırır.

  • Alt kaynaklar için kaynak adları oluşturmaktan kaçının. Bicep'in kaynaklarınız arasındaki ilişkileri anladığında sağladığı avantajları kaybedersiniz. Bunun yerine özelliğini veya iç içe yerleştirmeyi parent kullanın.

Çıkışlar

  • Hassas veriler için çıkış oluşturmadığınızdan emin olun. Çıkış değerlerine dağıtım geçmişine erişimi olan herkes erişebilir. Gizli dizileri işlemek için uygun değildirler.

  • Özellik değerlerini çıkışlar arasında geçirmek yerine, zaten var olan kaynakların özelliklerini aramak için mevcut anahtar sözcüğünü kullanın. Diğer kaynaklardaki anahtarları çıkışlar arasında geçirmek yerine bu şekilde aramak en iyi yöntemdir. Her zaman en güncel verileri alırsınız.

Bicep çıkışları hakkında daha fazla bilgi için bkz. Bicep'teki çıkışlar.

Kiracı kapsamları

Kiracı kapsamında ilke veya rol ataması oluşturamazsınız. Ancak tüm kuruluşunuzda erişim vermeniz veya ilke uygulamanız gerekiyorsa, bu kaynakları kök yönetim grubuna dağıtabilirsiniz.

Sonraki adımlar