Megosztás a következőn keresztül:

JavaScript-konfigurációszolgáltató

configuration-provider-npm-package

Az Azure App Configuration egy olyan szolgáltatás, amellyel a fejlesztők egyszerűen és biztonságosan központosíthatják az alkalmazáskonfigurációikat. A JavaScript konfigurációszolgáltatói kódtár lehetővé teszi a konfiguráció felügyelt módon való betöltését egy Azure-alkalmazás konfigurációs tárból. Ez az ügyfélkódtár további funkciókat ad hozzá a JavaScripthez készült Azure SDK felett.

Konfiguráció betöltése

A load csomagban exportált metódus a @azure/app-configuration-provider konfiguráció betöltésére szolgál a Azure-alkalmazás Konfigurációból. A load módszer lehetővé teszi a Microsoft Entra ID vagy kapcsolati sztring használatát az Alkalmazáskonfigurációs áruházhoz való csatlakozáshoz.

Ezzel hitelesítheti magát DefaultAzureCredential az Alkalmazáskonfigurációs áruházban. Kövesse az utasításokat a hitelesítő adatod Alkalmazás-konfigurációs Adatolvasó szerepkörrel való hozzárendeléséhez.

const { load } = require("@azure/app-configuration-provider");
const { DefaultAzureCredential } = require("@azure/identity");
const endpoint = process.env.AZURE_APPCONFIG_ENDPOINT;
const credential = new DefaultAzureCredential(); // For more information, see https://learn.microsoft.com/azure/developer/javascript/sdk/credential-chains#use-defaultazurecredential-for-flexibility

async function run() {
    // Connect to Azure App Configuration using a token credential and load all key-values with no label.
    const appConfig = await load(endpoint, credential);
    console.log('appConfig.get("message"):', appConfig.get("message"));
}

run();

A load metódus a következőképpen definiált típuspéldányt AzureAppConfiguration ad vissza:

type AzureAppConfiguration = {
    refresh(): Promise<void>;
    onRefresh(listener: () => any, thisArg?: any): Disposable;
} & IGettable & ReadonlyMap<string, any> & IConfigurationObject;

További információ refresh és onRefresh metódusok a Konfiguráció frissítése című szakaszban találhatók.

Konfiguráció felhasználása

A AzureAppConfiguration típus a következő interfészeket bővíti ki:

  • IGettable

    interface IGettable {
    get<T>(key: string): T | undefined;
}

    Az IGettable interfész metódust biztosít get egy kulcs-érték értékének lekéréséhez a térképstílusú adatstruktúrából.

    const appConfig = await load(endpoint, credential);
const fontSize = appConfig.get("app:font:size"); // value of the key "app:font:size" from the App Configuration store

  • ReadonlyMap

    A AzureAppConfiguration típus kiterjeszti az ReadonlyMap interfészt is, és csak olvasható hozzáférést biztosít a kulcs-érték párokhoz.

  • IConfigurationObject

    interface IConfigurationObject {
    constructConfigurationObject(options?: ConfigurationObjectConstructionOptions): Record<string, any>;
}

    Az IConfigurationObject interfész metódust biztosít constructConfigurationObject egy konfigurációs objektum létrehozásához térképstílusú adatstruktúra és hierarchikus kulcsok alapján. Az opcionális ConfigurationObjectConstructionOptions paraméter segítségével megadhatja a hierarchikus kulcsok objektumtulajdonságokká alakításához használt elválasztót. Alapértelmezés szerint az elválasztó az ".".

    interface ConfigurationObjectConstructionOptions {
    separator?: "." | "," | ";" | "-" | "_" | "__" | "/" | ":"; // supported separators
}

    A JavaScriptben az objektumokat vagy térképeket gyakran használják elsődleges adatstruktúrákként a konfigurációk megjelenítéséhez. A JavaScript konfigurációszolgáltatói kódtár mindkét konfigurációs módszert támogatja, így a fejlesztők rugalmasan választhatják ki az igényeiknek leginkább megfelelő lehetőséget.

    const appConfig = await load(endpoint, credential);
const settingsObj = appConfig.constructConfigurationObject({separator: ":"});
const fontSize1 = appConfig.get("app:font:size"); // map-style configuration representation
const fontSize2 = settingsObj.app.font.size; // object-style configuration representation

JSON-tartalomtípus kezelése

JSON-kulcsértékeket az Alkalmazáskonfigurációban hozhat létre. Amikor kulcsértékeket tölt be az Azure App Configurationból, a konfigurációszolgáltató automatikusan objektummá alakítja az érvényes JSON-tartalomtípus (például application/json) kulcsértékeit.

{
    "key": "font",
    "label": null,
    "value": "{\r\n\t\"size\": 12,\r\n\t\"color\": \"red\"\r\n}",
    "content_type": "application/json"
}

A fenti kulcs-érték a következőként { size: 12, color: "red" }lesz betöltve: .

const appConfig = await load(endpoint, credential);
const { size, color } = appConfig.get("font");

Feljegyzés

A konfigurációszolgáltató a (JSONC) @azure/app-configuration-providerverziójától kezdve lehetővé teszi a tartalomtípusú kulcsértékek megjegyzéseitapplication/json.

Adott kulcsértékek betöltése választókkal

Alapértelmezés szerint a metódus az load összes konfigurációt betölti címkével a konfigurációs tárból. A metódus viselkedését a load választható típusparaméter AzureAppConfigurationOptions használatával konfigurálhatja.

Az Alkalmazáskonfigurációs áruházból betöltött konfigurációk pontosításához vagy kibontásához megadhatja a tulajdonság alatti AzureAppConfigurationOptions.selectors kulcs- vagy címkeválasztókat.

const appConfig = await load(endpoint, credential, {
    selectors: [
        { // load the subset of keys starting with "app1." prefix and "test" label
            keyFilter: "app1.*",
            labelFilter: "test"
        },
        { // load the subset of keys with "dev" label"
            keyFilter: "*",
            labelFilter: "dev"
        }
    ]
});

Feljegyzés

A kulcsértékek betöltése abban a sorrendben van, amelyben a választók szerepelnek. Ha több választó is lekéri az azonos kulccsal rendelkező kulcsértékeket, az utolsó érték felülírja a korábban betöltött értékeket.

Címkeszűrők

A címkeszűrő paraméter kiválasztja az adott címkékkel rendelkező kulcsértékeket. A kulcsértékek csak akkor töltődnek be, ha a szűrőkben megadott összes címke és megfelelő érték szerepel benne.

const appConfig = await load(endpoint, credential, {
    selectors: [
        { // load the subset of keys with "test" label" and three tags
            keyFilter: "*",
            labelFilter: "test",
            tagFilters: [
                "emptyTag=",
                "nullTag=\0",
                "tag1=value1"
            ]
        }
    ]
});

Feljegyzés

A csillag (*), vessző (,) és a fordított perjel (\) karakterek fenntartottak, és a címkeszűrőben használt esetben fordított perjellel kell kimenekülniük.

Előtag vágása a kulcsokból

Az előtagot levághatja a kulcsokról, ha megadja a levágott kulcs előtagjainak listáját a AzureAppConfigurationOptions.trimKeyPrefixes tulajdonságnak.

const appConfig = await load(endpoint, credential, {
    selectors: [{
        keyFilter: "app.*"
    }],
    trimKeyPrefixes: ["app."]
});

Konfiguráció frissítése

A konfigurációk dinamikus frissítése lehetővé teszi, hogy az alkalmazás újraindítása nélkül lekérje a legújabb értékeket az Alkalmazáskonfigurációs áruházból. AzureAppConfigurationOptions.refreshOptions Beállíthatja a frissítés engedélyezését és a frissítési beállítások konfigurálását. A betöltött konfiguráció frissül, ha a rendszer a kiválasztott kulcsértékek módosítását észleli a kiszolgálón. Alapértelmezés szerint 30 másodperces frissítési időközt használ, de felülbírálhatja a refreshIntervalInMs tulajdonsággal.

const appConfig = await load(endpoint, credential, {
    refreshOptions: {
        enabled: true,
        refreshIntervalInMs: 15_000
    }
});

A beállítás refreshOptions önmagában nem frissíti automatikusan a konfigurációt. A frissítés indításához meg kell hívnia a refresh metódus AzureAppConfiguration által load visszaadott példány metódusát.

// this call is not blocking, the configuration will be updated asynchronously
appConfig.refresh();

Ez a kialakítás megakadályozza az alkalmazáskonfigurációra irányuló szükségtelen kéréseket, ha az alkalmazás tétlen. Adja meg azt a hívást, refresh amelyben az alkalmazástevékenység történik. Ezt tevékenységalapú konfigurációfrissítésnek nevezzük. Meghívhat refresh például egy bejövő kérés feldolgozásakor, vagy egy olyan iterációban, ahol összetett feladatot hajt végre.

const server = express();
// Use an express middleware to refresh configuration whenever a request comes in
server.use((req, res, next) => {
    appConfig.refresh();
    next();
})

Még akkor is, ha a frissítési hívás bármilyen okból meghiúsul, az alkalmazás továbbra is a gyorsítótárazott konfigurációt fogja használni. Egy másik kísérlet akkor történik, amikor a konfigurált frissítési időköz lejárt, és a frissítési hívást az alkalmazástevékenység aktiválja. A hívás refresh nem működik, mielőtt a konfigurált frissítési időköz eltelik, így a teljesítményre gyakorolt hatása minimális, még akkor is, ha gyakran hívják.

Egyéni frissítési visszahívás

A onRefresh metódus lehetővé teszi az egyéni visszahívási függvények használatát, amelyeket a rendszer minden alkalommal meghív, amikor a helyi konfiguráció sikeresen frissül a Azure-alkalmazás Konfigurációs tár módosításaival. Eldobható objektumot ad vissza, amellyel eltávolíthatja a regisztrált visszahívást

const appConfig = await load(endpoint, credential, {
    refreshOptions: {
        enabled: true
    }
});
const disposer = appConfig.onRefresh(() => {
    console.log("Config refreshed.");
});

appConfig.refresh();
// Once the refresh is successful, the callback function you registered will be executed.
// In this example, the message "Config refreshed" will be printed.

disposer.dispose();

Frissítés a sentinel kulccsal

A sentinel kulcs az a kulcs, amelyet az összes többi kulcs módosítása után frissít. A konfigurációszolgáltató az összes kijelölt kulcsérték helyett a sentinel kulcsot fogja figyelni. Ha változás észlelhető, az alkalmazás frissíti az összes konfigurációs értéket.

const appConfig = await load(endpoint, credential, {
    refreshOptions: {
        enabled: true,
        watchedSettings: [
            { key: "sentinel" }
        ]
    }
});

A frissítés konfigurálásáról további információt a Dinamikus konfiguráció használata JavaScriptben című témakörben talál.

Funkciójelző

Az Azure App Configuration funkciójelzőket hozhat létre. Alapértelmezés szerint a szolgáltatásjelzőket nem tölti be a konfigurációszolgáltató. A metódus meghívásakor a tulajdonságon keresztül AzureAppConfigurationOptions.featureFlagOptions engedélyezheti a funkciójelzők betöltését és frissítését load .

const appConfig = await load(endpoint, credential, {
    featureFlagOptions: {
        enabled: true, // enable loading feature flags
        selectors: [ { keyFilter: "*", labelFilter: "Prod" } ],
        refresh: {
            enabled: true, // enable refreshing feature flags
            refreshIntervalInMs: 60_000
        }
    }
});

Feljegyzés

Ha featureFlagOptions engedélyezve van, és nincs megadva választó, a konfigurációszolgáltató az alkalmazáskonfigurációs áruház címkéje nélkül tölti be az összes funkciójelzőt.

Fontos

Az Azure App Configuration szolgáltatásjelzőinek hatékony használatához és kezeléséhez telepítse és használja a @microsoft/feature-management csomagot. Ez a kódtár strukturált módon szabályozza az alkalmazás funkcióinak viselkedését.

Funkciókezelés

A szolgáltatásfelügyeleti kódtár lehetővé teszi az alkalmazásfunkciók funkciójelzők alapján történő fejlesztését és elérhetővé cióját. A szolgáltatásfelügyeleti kódtár úgy lett kialakítva, hogy a konfigurációszolgáltatói kódtárral együtt működjön. A konfigurációszolgáltató betölti az összes kijelölt funkciójelzőt a szakasz listájában feature_flags lévő feature_management konfigurációba. A szolgáltatásfelügyeleti kódtár az alkalmazás betöltött funkciójelzőit fogja használni és kezelni.

Az alábbi példa bemutatja, hogyan integrálható a kódtár a @microsoft/feature-management konfigurációszolgáltatóval az API akadálymentességének dinamikus vezérléséhez egy Express-alkalmazásban a Beta funkciójelző állapota alapján.

// Load feature flags from Azure App Configuration
import { load } from "@azure/app-configuration-provider";
const appConfig = await load(endpoint, credential, {
    featureFlagOptions: {
        enabled: true, // enable loading feature flags
        refresh: {
            enabled: true // enable refreshing feature flags
        }
    }
});

import { ConfigurationMapFeatureFlagProvider, FeatureManager } from "@microsoft/feature-management";
// Create a feature flag provider which uses the configuration provider as feature flag source
const ffProvider = new ConfigurationMapFeatureFlagProvider(appConfig);
// Create a feature manager which will evaluate the feature flag
const fm = new FeatureManager(ffProvider);

import express from "express";
const server = express();

// Use a middleware to achieve request-driven configuration refresh
server.use((req, res, next) => {
    // this call is not blocking, the configuration will be updated asynchronously
    appConfig.refresh();
    next();
});

server.get("/Beta", async (req, res) => {
    if (await featureManager.isEnabled("Beta")) {
        res.send("Welcome to the Beta page!");
    } else {
        res.status(404).send("Page not found");
    }
});

A JavaScript szolgáltatásfelügyeleti kódtár használatával kapcsolatos további információkért tekintse meg a funkciójelölő rövid útmutatóját.

Key Vault-referencia

Azure-alkalmazás Konfiguráció támogatja az Azure Key Vaultban tárolt titkos kulcsokra való hivatkozásokat. Az Alkalmazáskonfigurációban olyan kulcsokat hozhat létre, amelyek a Key Vaultban tárolt titkos kulcsokhoz vannak megfeleltetve. A titkos kulcsok biztonságosan tárolhatók a Key Vaultban, de a betöltést követően bármely más konfigurációhoz hasonlóan elérhetők.

A konfigurációszolgáltatói kódtár ugyanúgy kéri le a Key Vault-hivatkozásokat, mint az Alkalmazáskonfigurációban tárolt többi kulcs esetében. Mivel az ügyfél Key Vault-hivatkozásként ismeri fel a kulcsokat, egyedi tartalomtípussal rendelkezik, és az ügyfél a Key Vaulthoz csatlakozva lekéri az alkalmazás értékeit. A tulajdonságot a megfelelő hitelesítő adatokkal kell konfigurálnia AzureAppConfigurationOptions.KeyVaultOptions , hogy a konfigurációszolgáltató kapcsolódhasson az Azure Key Vaulthoz.

const credential = new DefaultAzureCredential();
const appConfig = await load(endpoint, credential, {
    keyVaultOptions: {
        credential: credential
    }
});

A példányt közvetlenül is megadhatjaSecretClient.KeyVaultOptions Ily módon testre szabhatja a beállításokat a létrehozás SecretClientsorán.

import { SecretClient } from "@azure/keyvault-secrets";

const credential = new DefaultAzureCredential();
const secretClient = new SecretClient(keyVaultUrl, credential, {
    serviceVersion: "7.0",
});
const appConfig = await load(endpoint, credential, {
    keyVaultOptions: {
        secretClients: [ secretClient ]
    }
});

A tulajdonságot úgy is beállíthatja secretResolver , hogy helyileg oldja fel azokat a titkos kulcsokat, amelyekhez nincs kulcstartó társítva.

const resolveSecret = (url) => "From Secret Resolver";
const appConfig = await load(endpoint, credential, {
    keyVaultOptions: {
        secretResolver: resolveSecret
    }
});

A clientOptions tulajdonságot úgy is beállíthatja, hogy konfigurálja a SecretClientOptions az Azure Key Vault csatlakozáshoz, amelyhez nincs regisztrált SecretClient.

const credential = new DefaultAzureCredential();
const appConfig = await load(endpoint, credential, {
    keyVaultOptions: {
        credential: credential,
        clientOptions: { // configure a custom SecretClientOptions
            retryOptions: { 
                maxRetries: 3, 
                maxRetryDelayInMs: 1000 
            }
        }
    }
});

Párhuzamos titkos kódfeloldás

Az Azure Key Vault nem biztosít csomag API-t több titok egyetlen kérelemben való lekéréséhez. Ha az alkalmazásnak számos Key Vault-referenciát kell betöltenie, javíthatja a teljesítményt azáltal, hogy engedélyezi a párhuzamos titkos kódfeloldást a tulajdonság parallelSecretResolutionEnabledhasználatával.KeyVaultOptions Ez lehetővé teszi, hogy a szolgáltató több titkos kódot is lekérjen párhuzamosan, és ne egymás után:

const credential = new DefaultAzureCredential();
const appConfig = await load(endpoint, credential, {
    keyVaultOptions: {
        credential: credential,
        parallelSecretResolutionEnabled: true
    }
});

Feljegyzés

Ha a titkos kulcsokat párhuzamosan oldja fel, előfordulhat, hogy az Azure Key Vault szolgáltatási korlátja jelenik meg. A terheléskorlátozás hatékony kezeléséhez implementálja az ügyféloldali terheléskorlátozás legjobb gyakorlatait a megfelelő újrapróbálkozási beállítások konfigurálásával.SecretClient Regisztrálhat egyéni SecretClient példányokat, vagy konfigurálhatja clientOptions a AzureAppConfigurationOptions.keyVaultOptions.

Key Vault titkos kód frissítése

Az Azure App Configuration lehetővé teszi titkos frissítési időközök konfigurálását a konfigurációfrissítési ciklustól függetlenül. Ez azért fontos a biztonság szempontjából, mert bár az Alkalmazáskonfiguráció Key Vault-referencia URI-ja változatlan marad, a Key Vault mögöttes titkos kódja a biztonsági eljárások részeként elforgatható.

Annak érdekében, hogy az alkalmazás mindig a legfrissebb titkos értékeket használja, konfigurálja a tulajdonságot a secretRefreshIntervalInMs következőben KeyVaultOptions: . Ez arra kényszeríti a szolgáltatót, hogy friss titkos kulcsértékeket kérjen le a Key Vaultból a következő esetekben:

  • Az alkalmazásod hívásokat kezdeményez AzureAppConfiguration.refresh
  • A titkos kód konfigurált frissítési időköze lejárt

Ez a mechanizmus akkor is működik, ha nem észlelhető módosítás az Alkalmazáskonfigurációs áruházban, biztosítva, hogy az alkalmazás szinkronban maradjon az elforgatott titkos kódokkal.

const credential = new DefaultAzureCredential();
const appConfig = await load(endpoint, credential, {
    keyVaultOptions: {
        credential: credential,
        secretRefreshIntervalInMs: 7200_000 // 2 hours
    }
});

Pillanatfelvétel

A pillanatkép egy alkalmazáskonfigurációs áruház kulcsértékeinek elnevezett, nem módosítható részhalmaza. A pillanatképet alkotó kulcsértékek a létrehozás során a kulcs- és címkeszűrők használatával lesznek kiválasztva. A pillanatkép létrehozása után a benne lévő kulcsértékek garantáltan változatlanok maradnak.

Pillanatkép-választóval betöltheti a kulcsértékeket vagy a funkciójelzőket egy pillanatképből:

const appConfig = await load(endpoint, credential, {
    selectors: [
        { snapshotName: "MySnapshot" }, // load key-values from snapshot
        { keyFilter: "test*", labelFilter: "test" }
    ],
    featureFlagOptions: {
        enabled: true,
        selectors: [
            { snapshotName: "MySnapshot" }, // load feature flags from snapshot
            { keyFilter: "*", labelFilter: "test" }
        ]
    }
});

Újrapróbálkozás indítása

A konfiguráció betöltése kritikus útvonalművelet az alkalmazás indításakor. A megbízhatóság biztosítása érdekében az Azure App Configuration szolgáltató egy robusztus újrapróbálkozási mechanizmust implementál a kezdeti konfigurációs terhelés során. Ez segít megvédeni az alkalmazást az olyan átmeneti hálózati problémáktól, amelyek egyébként megakadályozhatják a sikeres indítást.

Ezt a viselkedést a következő módon AzureAppConfigurationOptions.startupOptionsszabhatja testre:

const appConfig = await load(endpoint, credential, { 
    startupOptions: { 
        timeoutInMs: 300_000
    }
});

Georeplikáció

A georeplikációs szolgáltatással kapcsolatos információkért tekintse meg a georeplikációs szolgáltatás engedélyezését ismertető témakört.

Következő lépések

A JavaScript-konfigurációszolgáltató használatának megismeréséhez folytassa az alábbi oktatóanyagkal.

Dinamikus konfiguráció használata JavaScriptben

A JavaScript szolgáltatásfelügyeleti kódtár használatának megismeréséhez tekintse meg az alábbi dokumentációt.

JavaScript-szolgáltatáskezelés

  • Last updated on