App Service ve Azure İşlevleri için Uygulama Yapılandırması başvurularını kullanma (önizleme)

Makale
03/30/2023

Bu konu başlığında, herhangi bir kod değişikliğine gerek kalmadan App Service veya Azure İşlevleri uygulamanızdaki yapılandırma verileriyle nasıl çalışabileceğiniz gösterilmektedir. Azure Uygulaması Yapılandırması, uygulama yapılandırmasını merkezi olarak yöneten bir hizmettir. Ayrıca, zaman içindeki yapılandırma değerleriniz veya yayınlarınız için etkili bir denetim aracıdır.

Uygulamanıza Uygulama Yapılandırması erişimi verme

App Service'te Uygulama Yapılandırması başvurularını kullanmaya başlamak için önce bir Uygulama Yapılandırması deposuna ihtiyacınız olacak ve uygulamanıza depodaki yapılandırma anahtar değerlerine erişim izni vermeniz gerekir.

Uygulama Yapılandırması hızlı başlangıcı izleyerek bir Uygulama Yapılandırması deposu oluşturun.

Not

Uygulama Yapılandırması başvuruları henüz ağ kısıtlanmış yapılandırma depolarını desteklemez.
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.
Yeni oluşturulan kimliğin Uygulama Yapılandırması deposunda doğru erişim izinlerine sahip olmasını sağlayın. Mağazanızın rol atamalarını güncelleştirin. Bu kimliğe, kapsamı kaynak üzerinde belirlenmiş bir rol atayacaksınız App Configuration Data Reader .

Kullanıcı tarafından atanan bir kimlikle Uygulama Yapılandırması Store'a erişme

Bazı uygulamaların, sistem tarafından atanan bir kimliğin henüz kullanılamadığı oluşturma zamanında yapılandırmaya başvurması gerekebilir. Böyle durumlarda, önceden kullanıcı tarafından atanan bir kimlik oluşturulabilir ve Uygulama Yapılandırması deposuna erişim verilebilir. Uygulama Yapılandırması deposu için kullanıcı tarafından atanan kimlik oluşturmak için bu adımları izleyin.

Kullanıcı tarafından atanan kimliğe izin verdikten sonra şu adımları izleyin:

Henüz yapmadıysanız kimliği uygulamanıza atayın.

Özelliği kullanıcı tarafından atanan kimliğin kaynak kimliğine ayarlayarak keyVaultReferenceIdentity uygulamayı Uygulama Yapılandırması başvuru işlemleri için bu kimliği kullanacak şekilde yapılandırın. Özelliğin adında keyVault olsa da kimlik, Uygulama Yapılandırması başvurulara da uygulanır.

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, bu Uygulama'dan gelen tüm başvurulara uygulanır.

Uygulamanıza başvuruda bulunduğu anahtar kasalarına erişim verme

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

Not

Azure Uygulaması Yapılandırma Key Vault başvuruları kavramı App Service ve Azure İşlevleri Key Vault başvuruları kavramıyla karıştırılmamalıdır. Uygulamanız bunların herhangi bir bileşimini kullanabilir, ancak dikkat edilmesi gereken bazı önemli farklılıklar vardır. Kasanızın ağ kısıtlaması olması veya uygulamanın düzenli aralıklarla en son sürümlere güncelleştirilmesi gerekiyorsa, Uygulama Yapılandırması başvurusu kullanmak yerine App Service'i ve Azure İşlevleri doğrudan yaklaşımı kullanmayı göz önünde bulundurun.

Uygulama Yapılandırması başvurusu için kullandığınız kimliği belirleyin. Kasaya erişim aynı kimliğe verilmelidir.
Bu kimlik için Key Vault'ta bir erişim ilkesi oluşturun. Bu ilkede "Get" gizli dizi iznini etkinleştirin. Yönetilen kimlikle uyumlu olmadığından "yetkili uygulama" veya applicationId ayarları yapılandırmayın.

Başvuru söz dizimi

Uygulama Yapılandırması başvurusu, aşağıdakiyle değiştirildiği {referenceString} biçimindedir@Microsoft.AppConfiguration({referenceString}):

Başvuru dizesi bölümleri	Açıklama
Endpoint=endpoint;	Uç nokta , başvuru dizesinin gerekli bölümüdür. Uç Nokta değeri, Uygulama Yapılandırması kaynağınızın URL'sine sahip olmalıdır.
Key=keyName;	Anahtar , başvuru dizesinin gerekli bölümünü oluşturur. Anahtar değeri, Uygulama ayarına atamak istediğiniz Anahtarın adı olmalıdır.
Label=label	Etiket bölümü, başvuru dizesinde isteğe bağlıdır. Etiket , Anahtar'da belirtilen Anahtar için Etiket değeri olmalıdır

Örneğin, ile Label tam bir başvuru aşağıdaki gibi görünür:

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

Alternatif olarak, herhangi bir Labelolmadan:

@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, başvurulan tüm anahtar-değerlerin Uygulama Yapılandırması deposundan hemen yeniden alınmasına neden olur.

Not

Anahtar-değerler Uygulama Yapılandırması güncelleştirildiğinde bu değerlerin otomatik olarak yenilenmesi/yeniden getirmesi şu anda desteklenmemektedir.

Uygulama Yapılandırmasından Kaynak Uygulama Ayarlar

Uygulama Yapılandırması başvuruları için değer olarak kullanılabilirUygulama Ayarlar, yapılandırma verilerini site yapılandırması yerine Uygulama Yapılandırması tutmanızı sağlar. Uygulama Ayarlar ve Uygulama Yapılandırması anahtar değerlerinin ikisi de bekleme sırasında güvenli bir şekilde şifrelenir. Merkezi yapılandırma yönetimi özelliklerine ihtiyacınız varsa yapılandırma verilerinin Uygulama Yapılandırması'ne gitmesi gerekir.

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

İpucu

Uygulama Yapılandırması başvurularını kullanan uygulama ayarlarının çoğu yuva ayarları olarak işaretlenmelidir, her ortam için ayrı depolarınız veya etiketleriniz olmalıdır.

Azure Dosyalar bağlama ile ilgili dikkat edilmesi gerekenler

Uygulamalar, dosya sistemi olarak Azure Dosyalar bağlamak için uygulama ayarını kullanabilirWEBSITE_CONTENTAZUREFILECONNECTIONSTRING. Bu ayar, uygulamanın düzgün şekilde başlatılabilmesini sağlamak için ek doğrulama denetimleri sunar. Platform, Azure Dosyalar içinde bir içerik paylaşımına sahip olmayı kullanır ve ayar aracılığıyla WEBSITE_CONTENTSHARE belirtilmemişse varsayılan bir ad kabul eder. Bu ayarları değiştiren tüm istekler için platform, bu içerik paylaşımının mevcut olup olmadığını doğrulamayı dener ve yoksa oluşturmayı dener. İçerik paylaşımını bulamıyor veya oluşturamıyorsa istek engellenir.

Bu ayar için Uygulama Yapılandırması başvuruları kullanırsanız, gelen istek işlenirken bağlantının kendisi çözümlenememesinden bu doğrulama denetimi varsayılan olarak başarısız olur. Bu sorunu önlemek için "1" ayarını yaparak WEBSITE_SKIP_CONTENTSHARE_VALIDATION doğrulamayı atlayabilirsiniz. Bu ayar tüm denetimleri atlar ve içerik paylaşımı sizin için oluşturulmaz. Önceden oluşturulduğuna emin olmanız gerekir.

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ına hizmet eder.

Siteyi oluşturmanın bir parçası olarak, yönetilen kimlik izinlerinin yayılmaması veya sanal ağ tümleştirmesinin ayarlanmaması nedeniyle içerik paylaşımını bağlama girişimi 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 edinmek için bkz . Azure Resource Manager dağıtımı . App Service, Azure Dosyalar ayarlanana kadar varsayılan bir dosya sistemi kullanır ve dosyalar kopyalanmaz, bu nedenle ara dönemde Azure Dosyalar bağlanmadan önce dağıtım girişimi olmadığından emin olun.

Azure Resource Manager dağıtımı

Azure Resource Manager şablonları aracılığıyla kaynak dağıtımlarını otomatikleştirdiğinizde, bu özelliğin çalışması için bağımlılıklarınızı belirli bir sırada sıralamanız gerekebilir. Not: Site tanımında bir siteConfig özellik kullanmak yerine uygulama ayarlarınızı kendi kaynakları olarak tanımlamanız gerekir. Bunun nedeni, sistem tarafından atanan kimliğin kendisiyle oluşturulması ve erişim ilkesinde kullanılabilmesi için önce sitenin tanımlanması gerekir.

Aşağıda, Uygulama Yapılandırması başvuruları olan bir işlev uygulaması için örnek bir sahte şablon 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. Uygulama ayarı güncelleştirmesi zaman uyumsuz davrandıkça bu normalde güvenli olmayan bir davranıştır. Ancak, uygulama ayarını eklediğimiz için WEBSITE_ENABLE_SYNC_UPDATE_SITE güncelleştirme zaman uyumludur. Bu, kaynak denetimi dağıtımının yalnızca uygulama ayarları tamamen güncelleştirildikten sonra başlayacağı anlamına gelir. Daha fazla uygulama ayarı için bkz. Azure Uygulaması Service'te ortam değişkenleri ve uygulama ayarları.

Uygulama Yapılandırması Başvurularında Sorun Giderme

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

En yaygın olarak, bu hata Uygulama Yapılandırması erişim ilkesinin yanlış yapılandırılması nedeniyle olabilir. Ancak, başvurudaki bir söz dizimi hatasından veya yapılandırma anahtarı-değeri depoda mevcut olmadığından da kaynaklanabilir.

Sonraki adımlar

App Service'ten Anahtar kasası gizli dizilerine başvurma