Używanie odwołań do konfiguracji aplikacji dla usług Azure App Service i Azure Functions

W tym artykule pokazano, jak pracować z danymi konfiguracji w aplikacjach usługi Azure App Service lub usługi Azure Functions bez wprowadzania żadnych zmian w kodzie. Azure App Configuration to usługa platformy Azure, której można użyć do centralnego zarządzania konfiguracją aplikacji. Jest to również skuteczne narzędzie do przeprowadzania inspekcji wartości konfiguracji w czasie lub między wersjami.

Udzielanie aplikacji dostępu do usługi App Configuration

Aby rozpocząć korzystanie z odwołań do App Configuration w usłudze App Service, należy najpierw utworzyć rejestr App Configuration. Następnie przyznasz aplikacji uprawnienia dostępu do par klucz/wartość konfiguracji, które znajdują się w sklepie.

1. Aby utworzyć sklep App Configuration, ukończ przewodnik Szybki start dotyczący usługi App Configuration.

2. Utwórz tożsamość zarządzaną dla aplikacji.

   Odwołania do usługi App Configuration domyślnie używają tożsamości przypisanej przez system aplikacji, ale można określić tożsamość przypisaną przez użytkownika.

3. Przyznaj tożsamości prawidłowy zestaw uprawnień dostępu do repozytorium App Configuration. Zaktualizuj przypisania ról dla sklepu. Przypisz rolę Czytelnik danych konfiguracji aplikacji do tej tożsamości dla określonego zasobu.

Uzyskaj dostęp do magazynu App Configuration za pomocą tożsamości przypisanej przez użytkownika

W niektórych przypadkach aplikacje mogą wymagać odwołania do konfiguracji podczas ich tworzenia, ale tożsamość przypisana przez system nie jest jeszcze dostępna. W tym scenariuszu można utworzyć tożsamość przypisaną przez użytkownika dla magazynu App Configuration z wyprzedzeniem.

Po udzieleniu uprawnień przypisanej użytkownikowi tożsamości wykonaj następujące kroki:

1. Przypisz tożsamość do aplikacji.

2. Skonfiguruj aplikację tak, aby korzystała z tej tożsamości dla operacji referencyjnych usługi App Configuration, ustawiając właściwość keyVaultReferenceIdentity jako identyfikator zasobu użytkownika przypisanej tożsamości. Mimo że właściwość ma w nazwie keyVault, tożsamość ma również zastosowanie do odwołań do App Configuration. Oto kod:

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

Ta konfiguracja ma zastosowanie do wszystkich odwołań w aplikacji.

Udziel aplikacji dostępu do wspomnianych magazynów kluczy

Oprócz przechowywania nieprzetworzonych wartości konfiguracji usługa App Configuration ma własny format przechowywania odwołań usługi Azure Key Vault. Jeśli wartość referencji w App Configuration jest referencją do Key Vault w sklepie App Configuration, aplikacja musi mieć również uprawnienia do dostępu do Key Vault określonego w referencji.

Aby udzielić aplikacji dostępu do magazynu kluczy:

1. Zidentyfikuj tożsamość, której użyłeś do referencji App Configuration. Musisz przyznać magazynowi dostęp do tej samej tożsamości.

2. Utwórz zasady dostępu w usłudze Key Vault dla tej tożsamości. Włącz uprawnienie Pobierz wpis tajny dla tych zasad. Nie konfiguruj autoryzowanej aplikacji ani applicationId ustawień, ponieważ nie są one zgodne z tożsamością zarządzaną.

Składnia referencyjna

Odwołanie do usługi App Configuration ma postać @Microsoft.AppConfiguration({referenceString}), gdzie {referenceString} jest zastępowana wartością zgodnie z opisem w poniższej tabeli:

Oto przykład kompletnego odwołania obejmującego Label:

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

Oto przykład, który nie zawiera Labelelementu :

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

Każda zmiana konfiguracji w aplikacji, która powoduje ponowne uruchomienie strony, prowadzi do natychmiastowego ponownego pobrania wszystkich odwołanych par klucz/wartość z magazynu App Configuration.

Ustawienia aplikacji źródłowej z usługi App Configuration

Możesz użyć odwołań App Configuration jako wartości ustawień aplikacji, dzięki czemu możesz przechowywać dane konfiguracji w App Configuration zamiast w ustawieniach konfiguracji witryny. Ustawienia aplikacji i pary klucz/wartość usługi App Configuration są bezpiecznie szyfrowane w spoczynku. Jeśli potrzebujesz scentralizowanych możliwości zarządzania konfiguracją, dodaj dane konfiguracji do usługi App Configuration.

Aby użyć odwołania do usługi App Configuration dla ustawienia aplikacji, ustaw odwołanie jako wartość ustawienia. Aplikacja, jak zwykle, może odwoływać się do wartości konfiguracji za pomocą klucza. Nie są wymagane żadne zmiany kodu.

Zagadnienia dotyczące instalowania usługi Azure Files

Aplikacje mogą używać WEBSITE_CONTENTAZUREFILECONNECTIONSTRING ustawienia aplikacji do instalowania usługi Azure Files jako systemu plików. To ustawienie ma dodatkowe kontrole poprawności, aby upewnić się, że aplikacja może działać prawidłowo. Platforma korzysta z zasobu udostępnionej zawartości w usłudze Azure Files i przyjmuje domyślną nazwę, chyba że zostanie ona określona w ustawieniu WEBSITE_CONTENTSHARE. W przypadku żądań modyfikujących te ustawienia platforma próbuje sprawdzić, czy udostępnianie treści istnieje. Jeśli udział nie istnieje, platforma próbuje utworzyć udział. Jeśli nie można zlokalizować ani utworzyć udziału zawartości, wówczas żądanie zostanie zablokowane.

Jeśli używasz odwołań do usługi App Configuration dla tego ustawienia, weryfikacja domyślnie się nie powiedzie, ponieważ połączenie samo w sobie nie może być rozpoznane, gdy platforma przetwarza przychodzące żądanie. Aby uniknąć tego problemu, możesz pominąć walidację, ustawiając wartość WEBSITE_SKIP_CONTENTSHARE_VALIDATION .1 To ustawienie pomija wszystkie kontrole, a udostępnianie treści nie jest tworzone automatycznie. Musisz upewnić się, że udział został utworzony z wyprzedzeniem.

Podczas tworzenia strony może dojść do niepowodzenia zamontowania udziału zawartości, jeśli uprawnienia tożsamości zarządzanej nie są propagowane lub integracja z siecią wirtualną nie jest skonfigurowana. Konfigurowanie usługi Azure Files można odroczyć do późniejszego użycia w szablonie wdrożenia, aby dostosować je do wymaganej konfiguracji. Aby uzyskać więcej informacji, zobacz wdrożenie usługi Azure Resource Manager w następnej sekcji. Usługa App Service używa tylko domyślnego systemu plików, dopóki usługa Azure Files nie zostanie skonfigurowana, a pliki nie zostaną skopiowane. Upewnij się, że w okresie przejściowym nie ma żadnych prób wdrożenia przed zainstalowaniem usługi Azure Files.

Wdrożenie usługi Azure Resource Manager

W przypadku automatyzowania wdrożeń zasobów przy użyciu szablonów usługi Azure Resource Manager (ARM) może być konieczne sekwencjonowanie zależności w określonej kolejności, aby odwołania do usługi App Configuration działały. W tym scenariuszu należy zdefiniować ustawienia aplikacji jako własny zasób, zamiast używać właściwości siteConfig w definicji witryny. Witryna musi być najpierw zdefiniowana, aby tożsamość przypisana przez system została z nią utworzona. Tożsamość zarządzana jest następnie używana w zasadach dostępu.

Oto przykładowy szablon dla aplikacji funkcji, która zawiera odwołania do usługi App Configuration:

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

Rozwiązywanie problemów z odwołaniami do konfiguracji aplikacji

Jeśli odwołanie nie zostanie poprawnie rozpoznane, zamiast tego zostanie użyta wartość odwołania. Tworzona jest zmienna środowiskowa używająca składni @Microsoft.AppConfiguration(...) . Odwołanie może spowodować błąd, ponieważ aplikacja oczekiwała wartości konfiguracji.

Ten błąd jest najczęściej wynikiem błędnej konfiguracji zasad dostępu do konfiguracji aplikacji. Jednak może się zdarzyć, jeśli wystąpi błąd składniowy w odwołaniu lub jeśli para klucz/wartość konfiguracji nie istnieje w magazynie.

Powiązana zawartość

• Odwołuj się do wpisów tajnych usługi Key Vault z usługi App Service