Condividi tramite

Provider di configurazione JavaScript

configuration-provider-npm-package

Configurazione app di Azure è un servizio gestito che consente agli sviluppatori di centralizzare le configurazioni delle loro applicazioni in modo semplice e sicuro. La libreria dei provider di configurazione JavaScript consente il caricamento della configurazione da un archivio di Configurazione app di Azure in modo gestito. Questa libreria client aggiunge funzionalità aggiuntive sopra Azure SDK per JavaScript.

Carica configurazione della rete

Il metodo load esportato nel pacchetto @azure/app-configuration-provider viene usato per caricare la configurazione dalla Configurazione app di Azure. Il metodo load consente di usare Microsoft Entra ID o stringa di connessione per connettersi all'archivio Configurazione app.

Usare DefaultAzureCredential per eseguire l'autenticazione nell'archivio di Configurazione app. Seguire le istruzioni per assegnare le credenziali al ruolo Lettore dati di Configurazione app.

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();

Il metodo load restituisce un'istanza di tipo AzureAppConfiguration definita come segue:

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

Per altre informazioni sui metodi refresh e onRefresh, vedere la sezione Aggiornamento della configurazione.

Utilizzare la configurazione

Il tipo AzureAppConfiguration estende le interfacce seguenti:

  • IGettable

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

    L'interfaccia IGettable fornisce il metodo get per recuperare il valore di una coppia chiave-valore dalla struttura di dati in stile Mappa.

    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

    Il tipo AzureAppConfiguration estende anche l'interfaccia ReadonlyMap, fornendo l'accesso in sola lettura alle coppie chiave-valore.

  • IConfigurationObject

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

    L'interfaccia IConfigurationObject fornisce il metodo constructConfigurationObject per costruire un oggetto di configurazione basato su una struttura di dati in stile Mappa e chiavi gerarchiche. Il parametro facoltativo ConfigurationObjectConstructionOptions può essere usato per specificare il separatore per la conversione di chiavi gerarchiche in proprietà oggetto. Per impostazione predefinita, il separatore è ".".

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

    In JavaScript, gli oggetti o le mappe vengono comunemente usati come strutture di dati primarie per rappresentare le configurazioni. La libreria dei provider di configurazione JavaScript supporta entrambi gli approcci di configurazione, offrendo agli sviluppatori la flessibilità di scegliere l'opzione più adatta alle proprie esigenze.

    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

Gestione dei tipi di contenuto JSON

È possibile creare valori chiave JSON in Configurazione app. Quando si caricano valori chiave da Configurazione app di Azure, il provider di configurazione convertirà automaticamente i valori chiave del tipo di contenuto JSON valido (ad esempio application/json) in oggetto.

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

Il valore della chiave precedente verrà caricato come { size: 12, color: "red" }.

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

Note

A partire dalla versione 2.2.0 di @azure/app-configuration-provider, il provider di configurazione consente i commenti, come definito in (JSONC), nelle coppie chiave-valore con un tipo di contenuto application/json.

Caricare coppie chiave-valore specifiche usando selettori

Per impostazione predefinita, il metodo load caricherà tutte le configurazioni senza etichetta dall'archivio di configurazione. È possibile configurare il comportamento del metodo load tramite il parametro facoltativo di tipo AzureAppConfigurationOptions.

Per perfezionare o espandere le configurazioni caricate dall'archivio Configurazione app, è possibile specificare i selettori di chiave o etichetta nella proprietà AzureAppConfigurationOptions.selectors.

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"
        }
    ]
});

Note

Le coppie chiave-valore vengono caricate nell'ordine in cui sono elencati i selettori. Se più selettori recuperano le coppie chiave-valore con la stessa chiave, il valore dell'ultima eseguirà l'override di qualsiasi valore caricato in precedenza.

Filtri per i tag

Il parametro dei filtri tag seleziona i valori chiave con tag specifici. Un valore chiave viene caricato solo se contiene tutti i tag e i valori corrispondenti specificati nei filtri.

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"
            ]
        }
    ]
});

Note

L'asterisco (*), la virgola (,) e la barra rovesciata (\) sono caratteri riservati e devono essere preceduti da una barra rovesciata se usati in un filtro tag.

Rimuovere il prefisso dalle chiavi

È possibile rimuovere il prefisso delle chiavi fornendo un elenco di prefissi di chiave rimossi alla proprietà AzureAppConfigurationOptions.trimKeyPrefixes.

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

Aggiornamento della configurazione

L'aggiornamento dinamico per le configurazioni consente di estrarre i valori più recenti dall'archivio Configurazione app senza dover riavviare l'applicazione. È possibile impostare AzureAppConfigurationOptions.refreshOptions per abilitare l'aggiornamento e configurare le opzioni di aggiornamento. La configurazione caricata verrà aggiornata quando viene rilevata una modifica delle coppie valore-chiave selezionate nel server. Per impostazione predefinita, viene usato un intervallo di aggiornamento di 30 secondi, ma è possibile eseguirne l'override con la proprietà refreshIntervalInMs.

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

La configurazione unicamente di refreshOptions non aggiornerà automaticamente la configurazione. È necessario chiamare il metodo refresh sull'istanza AzureAppConfiguration restituita dal metodo load per attivare un aggiornamento.

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

Questa progettazione impedisce richieste non necessarie di Configurazione app quando l'applicazione è inattiva. È necessario includere la chiamata refresh in cui si verifica l'attività dell'applicazione. Questa operazione è nota come aggiornamento della configurazione guidata dall'attività. Ad esempio, è possibile chiamare refresh quando si elabora una richiesta in ingresso o all'interno di un'iterazione in cui si esegue un'attività complessa.

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

Anche se la chiamata di aggiornamento non riesce per qualsiasi motivo, l'applicazione continuerà a usare la configurazione memorizzata nella cache. Verrà eseguito un altro tentativo quando l'intervallo di aggiornamento configurato è passato e la chiamata di aggiornamento viene attivata dall'attività dell'applicazione. La chiamata a refresh è un no-op prima che l'intervallo di aggiornamento configurato sia trascorso, quindi l'impatto sulle prestazioni è minimo, anche se viene effettuata di frequente.

Callback di aggiornamento personalizzato

Il metodo onRefresh consente funzioni di callback personalizzate che saranno richiamate ogni volta che la configurazione locale viene aggiornata correttamente con le modifiche dall'archivio di Configurazione app di Azure. Restituisce un oggetto Eliminabile, che è possibile utilizzare per rimuovere il callback registrato

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();

Aggiornamento della chiave Sentinel

Una chiave Sentinel è una chiave che si aggiorna dopo aver completato la modifica di tutte le altre chiavi. Il provider di configurazione monitorerà la chiave Sentinel anziché tutte le coppie chiave-valore selezionate. Quando viene rilevata una modifica, l'app aggiorna tutti i valori di configurazione.

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

Per altre informazioni sulla configurazione dell'aggiornamento, vedere Usare la configurazione dinamica in JavaScript.

Flag di funzionalità

È possibile creare flag di funzionalità nella Configurazione app di Azure. Per impostazione predefinita, i flag di funzionalità non verranno caricati dal provider di configurazione. È possibile abilitare il caricamento e l'aggiornamento dei flag di funzionalità tramite la proprietà AzureAppConfigurationOptions.featureFlagOptions quando si chiama il metodo 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
        }
    }
});

Note

Se featureFlagOptions è abilitato e non viene specificato alcun selettore, il provider di configurazione caricherà tutti i flag di funzionalità senza etichetta dall'archivio Configurazione app.

Importante

Per utilizzare e gestire efficacemente i flag di funzionalità caricati da Configurazione app di Azure, installare e usare il pacchetto @microsoft/feature-management. Questa libreria offre un modo strutturato per controllare il comportamento delle funzionalità nell'applicazione.

Gestione delle funzionalità

La libreria di gestione delle funzionalità consente di sviluppare ed esporre le funzionalità dell'applicazione in base ai flag di funzionalità. La libreria di gestione delle funzionalità è progettata per funzionare insieme alla libreria dei provider di configurazione. Il provider di configurazione caricherà tutti i flag di funzionalità selezionati nella configurazione sotto l'elenco feature_flags della sezione feature_management. La libreria di gestione delle funzionalità utilizzerà e gestirà i flag di funzionalità caricati per l'applicazione.

L'esempio seguente illustra come integrare la libreria @microsoft/feature-management con il provider di configurazione per controllare dinamicamente l'accessibilità dell'API in un'applicazione Express, basandosi sullo stato del flag di funzionalità Beta.

// 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");
    }
});

Per altre informazioni su come usare la libreria di gestione delle funzionalità JavaScript, vedere la guida introduttiva al flag di funzionalità.

Riferimento Key Vault

Configurazione app di Azure supporta il riferimento ai segreti archiviati in Azure Key Vault. In Configurazione app è possibile creare chiavi mappate ai segreti archiviati in Key Vault. I segreti vengono archiviati in modo sicuro in Key Vault, ma è possibile accedervi come qualsiasi altra configurazione dopo il caricamento.

La libreria dei provider di configurazione recupera i riferimenti a Key Vault, proprio come per qualsiasi altra chiave archiviata in Configurazione app. Poiché il client riconosce le chiavi come riferimenti Key Vault, ha un tipo di contenuto univoco e il client si connetterà a Key Vault per recuperare i valori per l'applicazione. È necessario configurare la proprietà AzureAppConfigurationOptions.KeyVaultOptions con le credenziali appropriate per consentire al provider di configurazione di connettersi a Azure Key Vault.

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

È anche possibile fornire l'istanza SecretClient direttamente a KeyVaultOptions. In questo modo, è possibile personalizzare le opzioni durante la creazione di SecretClient.

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 ]
    }
});

È anche possibile impostare la proprietà secretResolver per risolvere in locale i segreti a cui non è associato un insieme di credenziali delle chiavi.

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

È anche possibile impostare la proprietà clientOptions per configurare SecretClientOptions utilizzata per connettersi ad Azure Key Vault che non ha SecretClient registrati.

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

Risoluzione delle questioni riservate in parallelo

Azure Key Vault non fornisce un'API batch per il recupero di più segreti in una singola richiesta. Quando l'applicazione deve caricare numerosi riferimenti a Key Vault, è possibile migliorare le prestazioni abilitando la risoluzione dei segreti paralleli usando la parallelSecretResolutionEnabled proprietà in KeyVaultOptions. In questo modo il provider può recuperare più segreti in parallelo anziché in sequenza:

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

Note

Quando si risolve il segreto in parallelo, è possibile che si verifichi il limite di servizio di Azure Key Vault. Per gestire in modo efficace la limitazione delle richieste, implementare le procedure consigliate per la limitazione delle richieste lato client configurando le opzioni di ripetizione appropriate per SecretClient. È possibile registrare istanze personalizzate SecretClient o configurare clientOptions tramite .AzureAppConfigurationOptions.keyVaultOptions

Aggiornamento dei segreti di Key Vault

Configurazione app di Azure consente di configurare gli intervalli di aggiornamento dei segreti indipendentemente dal ciclo di aggiornamento della configurazione. Questo è fondamentale per la sicurezza perché, mentre l'URI di riferimento Key Vault in Configurazione app rimane invariato, il segreto sottostante in Key Vault potrebbe essere ruotato come parte delle procedure di sicurezza.

Per assicurarsi che l'applicazione usi sempre i valori segreti più aggiornati, configurare la secretRefreshIntervalInMs proprietà in KeyVaultOptions. In questo modo, il provider deve recuperare nuovi valori segreti da Key Vault quando:

  • L'applicazione chiama AzureAppConfiguration.refresh
  • L'intervallo di aggiornamento configurato per il segreto è trascorso

Questo meccanismo funziona anche quando non vengono rilevate modifiche nell'archivio di Configurazione app, garantendo che l'applicazione rimanga sincronizzata con i segreti aggiornati.

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

Snapshot

Snapshot è un subset non modificabile denominato dei valori chiave di un archivio di Configurazione app. I valori chiave che costituiscono uno snapshot vengono scelti durante la fase di creazione tramite l'utilizzo dei filtri di chiave e etichetta. Una volta creato uno snapshot, è garantito che i valori chiave in esso contenuti rimarranno invariati.

È possibile usare il selettore snapshot per caricare i valori chiave o i flag di funzionalità da uno snapshot:

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" }
        ]
    }
});

Tentativo di avvio

Il caricamento della configurazione è un'operazione di percorso fondamentale durante l'avvio dell'applicazione. Per garantire l'affidabilità, il provider di Configurazione app di Azure implementa un meccanismo di ripetizione affidabile durante il caricamento iniziale della configurazione. Ciò consente di proteggere l'applicazione da problemi di rete temporanei che potrebbero altrimenti impedire l'avvio riuscito.

È possibile personalizzare questo comportamento tramite :AzureAppConfigurationOptions.startupOptions

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

Replica geografica

Per informazioni sull'uso della replica geografica, vedere Abilitare la replica geografica.

Passaggi successivi

Per informazioni su come usare il provider di configurazione JavaScript, continuare con l'esercitazione seguente.

Usare la configurazione dinamica in JavaScript

Per informazioni su come usare la libreria di gestione delle funzionalità JavaScript, continuare con la documentazione seguente.

Gestione delle funzionalità JavaScript

  • Last updated on