Azure App Service ve Azure İşlevleri için Uygulama Yapılandırması referanslarını kullanma

Bu makalede, kod değişikliği yapmadan Azure App Service veya Azure İşlevleri uygulamalarında yapılandırma verileriyle çalışma gösterilmektedir. Azure Uygulama Yapılandırması , uygulama yapılandırmasını merkezi olarak yönetmek için kullanabileceğiniz bir Azure hizmetidir. Ayrıca yapılandırma değerlerinizi zaman içinde veya sürümler arasında denetlemek için etkili bir araçtır.

Uygulama Yapılandırması'na erişim izni verme

App Service'te Uygulama Yapılandırması başvurularını kullanmaya başlamak için önce bir Uygulama Yapılandırma deposu oluşturun. Ardından, uygulamanıza depolama alanındaki yapılandırma anahtarı/değer çiftlerine erişim izni verirsiniz.

Uygulama Yapılandırma deposu oluşturmak için Uygulama Yapılandırması hızlı başlangıcını tamamlayın.
Uygulamanız için yönetilen kimlik oluşturun.

Uygulama Yapılandırması başvuruları varsayılan olarak uygulamanın sistem tarafından atanan kimliğini kullanır, ancak kullanıcı tarafından atanan bir kimlik belirtebilirsiniz.
Kimliğe Uygulama Yapılandırma deposuna doğru erişim izinleri kümesini verin. Mağazanızın rol atamalarını güncelleştirin. Bu kimliğe, kapsamı kaynak üzerinde olan Uygulama Yapılandırması Veri Okuyucusu rolünü atayın.

Kullanıcı tarafından atanan kimlikle Uygulama Yapılandırma deposuna erişme

Bazı durumlarda, uygulamaları oluşturduğunuzda uygulamaların yapılandırmaya başvurması gerekebilir, ancak sistem tarafından atanan bir kimlik henüz kullanılamaz. Bu senaryoda, Uygulama Yapılandırma deposu için önceden kullanıcı tarafından atanan bir kimlik oluşturabilirsiniz .

Kullanıcı tarafından atanan kimliğe izinler verdikten sonra şu adımları tamamlayın:

Kimliği uygulamanıza atayın.

App'ı, bu kimliği Uygulama Yapılandırması referans işlemleri için kullanacak şekilde yapılandırmak amacıyla, keyVaultReferenceIdentity özelliğini kullanıcı tarafından atanan kimliğin kaynak kimliğine ayarlayın. Özellik adında keyVault olsa da, özdeşlik Uygulama Yapılandırması referansları için de geçerlidir. Kod şu şekildedir:

userAssignedIdentityResourceId=$(az identity show -g MyResourceGroupName -n MyUserAssignedIdentityName --query id -o tsv)
appResourceId=$(az webapp show -g MyResourceGroupName -n MyAppName --query id -o tsv)
az rest --method PATCH --uri "${appResourceId}?api-version=2021-01-01" --body "{'properties':{'keyVaultReferenceIdentity':'${userAssignedIdentityResourceId}'}}"

Bu yapılandırma, uygulamadaki tüm başvurular için geçerlidir.

Uygulamanıza atıfta bulunulan anahtar kasalarına erişim izni verin

Uygulama Yapılandırması, ham yapılandırma değerlerini depolamaya ek olarak Azure Key Vault başvurularını depolamak için kendi biçimine sahiptir. Uygulama Yapılandırması başvurusunun değeri, Uygulama Yapılandırma deposundaki bir Key Vault başvurusuysa, uygulamanızın başvuruda belirtilen anahtar kasasına erişme izinlerine de sahip olması gerekir.

Not

App Configuration Key Vault referansları App Service ve Azure Functions Key Vault referansları ile karıştırılmamalıdır. Uygulamanız bu referansların herhangi bir kombinasyonunu kullanabilir, ancak bazı önemli farklılıklar vardır. Eğer kasanız ağ kısıtlamalı olması gerekiyorsa veya uygulamanızın en son sürümlere düzenli olarak güncellenmesi gerekiyorsa, Uygulama Yapılandırması referansı yerine App Service ve Azure Functions yaklaşımını kullanmayı göz önünde bulundurun.

Uygulamanızın bir anahtar kasasına erişim izni vermek için:

Uygulama Yapılandırması referansı için kullandığınız kimliği belirleyin. Aynı kimliğe kasa erişimi vermelisiniz.
Bu kimlik için Key Vault'ta bir erişim ilkesi oluşturun. Bu ilkede Gizli al iznini etkinleştirin. Yönetilen kimlikle uyumlu olmadıklarından yetkili uygulamayı veya applicationId ayarları yapılandırmayın.

Referans sözdizimi

Uygulama Yapılandırması referansı @Microsoft.AppConfiguration({referenceString}) biçimindedir; burada {referenceString}, aşağıdaki tabloda açıklandığı şekilde bir değerle değiştirilir.

Referans dize bölümü	Açıklama
`Endpoint` = `<endpointURL>`	`Endpoint` (gerekli). Uygulama Yapılandırma kaynağınızın URL'si.
`Key` = `<myAppConfigKey>`	`Key` (gerekli). Uygulama ayarına atamak istediğiniz anahtarın adı.
`Label` = `<myKeyLabel>`	`Label` (isteğe bağlı). içinde `Key`belirtilen anahtar etiketinin değeri.

İşte Label içeren eksiksiz bir kaynak örneği:

@Microsoft.AppConfiguration(Endpoint=https://myAppConfigStore.azconfig.io; Key=myAppConfigKey; Label=myKeyLabel)

Aşağıda şunları içermeyen bir örnek verilmiştir Label:

@Microsoft.AppConfiguration(Endpoint=https://myAppConfigStore.azconfig.io; Key=myAppConfigKey)

Uygulamada yapılan ve sitenin yeniden başlatılmasına neden olan tüm yapılandırma değişiklikleri, Uygulama Yapılandırma deposundan başvurulan tüm anahtar/değer çiftlerinin hemen yeniden yapılandırılmasına neden olur.

Not

Uygulama Yapılandırması'nda anahtar/değer çiftleri güncelleştirildiğinde bu değerlerin otomatik olarak yenilenmesi ve yeniden kullanılması şu anda desteklenmemektedir.

Uygulama Yapılandırması'ndan kaynak uygulama ayarları

Uygulama ayarları için Uygulama Yapılandırma başvurularını değer olarak kullanabilirsiniz, böylece yapılandırma verilerini site yapılandırma ayarları yerine doğrudan Uygulama Yapılandırma içinde tutabilirsiniz. Uygulama ayarları ve Uygulama Yapılandırması anahtar/değer çiftlerinin her ikisi de bekleme sırasında güvenli bir şekilde şifrelenir. Merkezi yapılandırma yönetimi özelliklerine ihtiyacınız varsa Uygulama Yapılandırması'na yapılandırma verileri ekleyin.

Bir uygulama ayarı için Uygulama Yapılandırması başvurusu kullanmak için, başvuruyu ayarın değeri olarak atayın. Uygulamanız her zamanki gibi anahtarı aracılığıyla yapılandırma değerine başvurabilir. Kod değişikliği gerekmez.

İpucu

App Yapılandırması referanslarını kullanan çoğu uygulama ayarı, her bir ortam için ayrı depolar veya etiketler oluşturabilmeniz için slot ayarları olarak işaretlenmelidir.

Azure Dosyaları bağlama konusunda dikkat edilmesi gerekenler

Uygulamalar, Azure Dosyaları dosya sistemi olarak bağlamak için WEBSITE_CONTENTAZUREFILECONNECTIONSTRING uygulama ayarını kullanabilir. Bu ayar, uygulamanın düzgün şekilde başlatılabilmesini sağlamak için ek doğrulama denetimleri sunar. Platform, Azure Dosyalar'da içerik paylaşımına sahip olmayı kullanır ve ayarda WEBSITE_CONTENTSHARE belirtilmemişse varsayılan bir ad kabul eder. Platform, bu ayarları değiştiren tüm istekler için içerik paylaşımının mevcut olduğunu doğrulamaya çalışır. Paylaşım yoksa platform bunu oluşturmaya çalışır. İçerik paylaşımını bulamıyor veya oluşturamıyorsa istek engellenir.

Bu ayar için Uygulama Yapılandırması başvurularını kullanırsanız, platform gelen isteği işlerken bağlantının kendisi çözümlenemediğinden bu doğrulama denetimi varsayılan olarak başarısız olur. Bu sorunu önlemek için WEBSITE_SKIP_CONTENTSHARE_VALIDATION'ı 1'e ayarlayarak doğrulamayı atlayabilirsiniz. Bu ayar tüm denetimleri atlar ve içerik paylaşımı otomatik olarak oluşturulmaz. Paylaşımın önceden oluşturulmuş olduğundan emin olmalısınız.

Dikkat

Doğrulamayı atlarsanız ve bağlantı dizesi veya içerik paylaşımı geçersizse, uygulama düzgün başlatılamaz ve yalnızca HTTP 500 hataları sağlar.

Site oluşturduğunuzda, yönetilen kimlik izinleri yayılmadığında veya sanal ağ tümleştirmesi ayarlanmamışsa içerik paylaşımını bağlama işlemi başarısız olabilir. Gerekli kuruluma uyum sağlamak için dağıtım şablonunda daha sonraya kadar Azure Dosyalar ayarlamayı erteleyebilirsiniz. Daha fazla bilgi için sonraki bölümdeki Azure Resource Manager dağıtımına bakın. App Service, Azure Dosyalar ayarlanana ve dosyalar kopyalanmayana kadar yalnızca varsayılan bir dosya sistemi kullanır. Azure Dosyalar bağlanmadan önceki ara dönemde dağıtım girişimi olmadığından emin olun.

Azure Resource Manager dağıtımı

Azure Resource Manager (ARM) şablonlarını kullanarak kaynak dağıtımlarını otomatikleştirirseniz, Uygulama Yapılandırması başvurularının çalışması için bağımlılıklarınızı belirli bir sırada sıralamanız gerekebilir. Bu senaryoda, site tanımında bir siteConfig özellik kullanmak yerine uygulama ayarlarınızı kendi kaynakları olarak tanımlamanız gerekir. Sistem tarafından atanan kimliğin siteyle oluşturulması için önce site tanımlanmalıdır. Yönetilen kimlik daha sonra erişim politikası içinde kullanılır.

Uygulama Yapılandırması başvuruları içeren bir işlev uygulaması için örnek şablon aşağıda verilmiştir:

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "roleNameGuid": {
            "type": "string",
            "defaultValue": "[newGuid()]",
            "metadata": {
                "description": "A new GUID used to identify the role assignment"
            }
        }
    },
    "variables": {
        "functionAppName": "DemoMBFunc",
        "appConfigStoreName": "DemoMBAppConfig",
        "resourcesRegion": "West US2",
        "appConfigSku": "standard",
        "FontNameKey": "FontName",
        "FontColorKey": "FontColor",
        "myLabel": "Test",
        "App Configuration Data Reader": "[concat('/subscriptions/', subscription().subscriptionId, '/providers/Microsoft.Authorization/roleDefinitions/', '516239f1-63e1-4d78-a4de-a74fb236a071')]"
    },
    "resources": [
        {
            "type": "Microsoft.Web/sites",
            "name": "[variables('functionAppName')]",
            "apiVersion": "2021-03-01",
            "location": "[variables('resourcesRegion')]",
            "identity": {
                "type": "SystemAssigned"
            },
            //...
            "resources": [
                {
                    "type": "config",
                    "name": "appsettings",
                    "apiVersion": "2021-03-01",
                    //...
                    "dependsOn": [
                        "[resourceId('Microsoft.Web/sites', variables('functionAppName'))]",
                        "[resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))]"
                    ],
                    "properties": {
                        "WEBSITE_FONTNAME": "[concat('@Microsoft.AppConfiguration(Endpoint=', reference(resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))).endpoint,'; Key=',variables('FontNameKey'),'; Label=',variables('myLabel'), ')')]",
                        "WEBSITE_FONTCOLOR": "[concat('@Microsoft.AppConfiguration(Endpoint=', reference(resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))).endpoint,'; Key=',variables('FontColorKey'),'; Label=',variables('myLabel'), ')')]",
                        "WEBSITE_ENABLE_SYNC_UPDATE_SITE": "true"
                        //...
                    }
                },
                {
                    "type": "sourcecontrols",
                    "name": "web",
                    "apiVersion": "2021-03-01",
                    //...
                    "dependsOn": [
                        "[resourceId('Microsoft.Web/sites', variables('functionAppName'))]",
                        "[resourceId('Microsoft.Web/sites/config', variables('functionAppName'), 'appsettings')]"
                    ]
                }
            ]
        },
        {
            "type": "Microsoft.AppConfiguration/configurationStores",
            "name": "[variables('appConfigStoreName')]",
            "apiVersion": "2019-10-01",
            "location": "[variables('resourcesRegion')]",
            "sku": {
                "name": "[variables('appConfigSku')]"
            },
            //...
            "dependsOn": [
                "[resourceId('Microsoft.Web/sites', variables('functionAppName'))]"
            ],
            "properties": {
            },
            "resources": [
                {
                    "type": "keyValues",
                    "name": "[variables('FontNameKey')]",
                    "apiVersion": "2021-10-01-preview",
                    //...
                    "dependsOn": [
                        "[resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))]"

                    ],
                    "properties": {
                        "value": "Calibri",
                        "contentType": "application/json"
                    }
                },
                {
                    "type": "keyValues",
                    "name": "[variables('FontColorKey')]",
                    "apiVersion": "2021-10-01-preview",
                    //...
                    "dependsOn": [
                        "[resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))]"

                    ],
                    "properties": {
                        "value": "Blue",
                        "contentType": "application/json"
                    }
                }
            ]
        },
        {
            "scope": "[resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))]",
            "type": "Microsoft.Authorization/roleAssignments",
            "apiVersion": "2020-04-01-preview",
            "name": "[parameters('roleNameGuid')]",
            "properties": {
                "roleDefinitionId": "[variables('App Configuration Data Reader')]",
                "principalId": "[reference(resourceId('Microsoft.Web/sites/', variables('functionAppName')), '2020-12-01', 'Full').identity.principalId]",
                "principalType": "ServicePrincipal"
            }
        }
    ]
}

Not

Bu örnekte, kaynak denetimi dağıtımı uygulama ayarlarına bağlıdır. Çoğu senaryoda, uygulama ayarları zaman uyumsuz olarak güncelleştirildiğinden bu dizi daha az güvenlidir. Ancak örnek uygulama ayarını içerdiğinden WEBSITE_ENABLE_SYNC_UPDATE_SITE güncelleştirme zaman uyumlu olur. Kaynak denetimi dağıtımı ancak uygulama ayarları tamamen güncelleştirildikten sonra başlar. Uygulama ayarları hakkında daha fazla bilgi için bkz. Azure App Service'te ortam değişkenleri ve uygulama ayarları.

Uygulama yapılandırma referanslarıyla ilgili sorunları giderme

Başvuru düzgün çözümlenmezse, bunun yerine başvuru değeri kullanılır. Söz dizimini @Microsoft.AppConfiguration(...) kullanan bir ortam değişkeni oluşturulur. Uygulama bir yapılandırma değeri beklediğinden başvuru hataya neden olabilir.

Bu hata genellikle Uygulama Yapılandırması erişim ilkesinin yanlış yapılandırılmasının sonucudur. Ancak, referansta bir sözdizimi hatası varsa veya mağazada yapılandırma anahtarı/değer çiftleri yoksa da meydana gelebilir.

Uygulama Hizmeti'nden Key Vault gizli anahtarlarına başvurma

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-05-08