Partilhar via

Provedor de configuração JavaScript

pacote-npm-do-fornecedor-de-configuração

A Configuração da Aplicação Azure é um serviço gerido que ajuda os programadores a centralizar as respetivas configurações de aplicações de forma simples e segura. A biblioteca do provedor de configuração JavaScript permite carregar a configuração de um repositório de Configuração de Aplicativo do Azure de forma gerenciada. Esta biblioteca de cliente adiciona funcionalidade adicional acima do SDK do Azure para JavaScript.

Configuração de carga

O load método exportado no pacote é usado para carregar a @azure/app-configuration-provider configuração da Configuração do Aplicativo do Azure. O load método permite que você use o ID do Microsoft Entra ou a cadeia de conexão para se conectar à loja de configuração de aplicativos.

Você usa o para autenticar em DefaultAzureCredential sua loja de configuração de aplicativos. Siga as instruções para atribuir à sua credencial a função de Leitor de Dados de Configuração do Aplicativo.

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

O load método retorna uma instância do AzureAppConfiguration tipo que é definida da seguinte maneira:

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

Para obter mais informações sobre refresh e onRefresh métodos, consulte a seção Atualização de configuração .

Configuração de consumo

O AzureAppConfiguration tipo estende as seguintes interfaces:

  • IGettable

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

    A IGettable interface fornece get método para recuperar o valor de um valor-chave da estrutura de dados com estilo de mapa.

    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

    O AzureAppConfiguration tipo também estende a ReadonlyMap interface, fornecendo acesso somente leitura a pares chave-valor.

  • IConfigurationObject

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

    A IConfigurationObject interface fornece constructConfigurationObject método para construir um objeto de configuração com base em uma estrutura de dados no estilo de mapa e chaves hierárquicas. O parâmetro opcional ConfigurationObjectConstructionOptions pode ser usado para especificar o separador para converter chaves hierárquicas em propriedades de objeto. Por padrão, o separador é ".".

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

    Em JavaScript, objetos ou mapas são comumente usados como estruturas de dados primárias para representar configurações. A biblioteca do provedor de configuração JavaScript suporta ambas as abordagens de configuração, fornecendo aos desenvolvedores a flexibilidade de escolher a opção que melhor atende às suas necessidades.

    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

Tratamento de tipo de conteúdo JSON

Você pode criar valores-chave JSON na Configuração do aplicativo. Ao carregar valores-chave da Configuração de Aplicativo do Azure, o provedor de configuração converterá automaticamente os valores-chave do tipo de conteúdo JSON válido (por exemplo, application/json) em objeto.

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

O valor-chave acima será carregado como { size: 12, color: "red" }.

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

Nota

A partir da versão 2.2.0 do @azure/app-configuration-provider, o fornecedor de configuração permite comentários, conforme definido em (JSONC), em pares chave-valor com um tipo de conteúdo application/json.

Carregue valores-chave específicos usando seletores

Por padrão, o load método carregará todas as configurações sem rótulo do repositório de configuração. Você pode configurar o load comportamento do método através do parâmetro opcional do AzureAppConfigurationOptions tipo.

Para refinar ou expandir as configurações carregadas a partir da App Configuration store, você pode especificar os seletores de chave ou rótulo na AzureAppConfigurationOptions.selectors propriedade.

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

Nota

Os valores-chave são carregados na ordem em que os seletores são listados. Se vários seletores recuperarem valores-chave com a mesma chave, o valor do último substituirá qualquer valor carregado anteriormente.

Filtros de tags

O parâmetro tag filters seleciona valores-chave com tags específicas. Um valor-chave só é carregado se tiver todas as tags e valores correspondentes especificados nos filtros.

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

Nota

Os caracteres asterisco (*), vírgula (,) e barra inversa (\) são reservados e devem ser escapados com uma barra inversa quando usados num filtro de etiqueta.

Cortar prefixo das teclas

Você pode cortar o prefixo das chaves fornecendo uma lista de prefixos de chave cortados para a AzureAppConfigurationOptions.trimKeyPrefixes propriedade.

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

Atualização de configuração

A atualização dinâmica para as configurações permite que você extraia seus valores mais recentes da App Configuration Store sem ter que reiniciar o aplicativo. Você pode definir AzureAppConfigurationOptions.refreshOptions para habilitar as opções de atualização e configurar a atualização. A configuração carregada será atualizada quando qualquer alteração de valores-chave selecionados for detetada no servidor. Por padrão, um intervalo de atualização de 30 segundos é usado, mas você pode substituí-lo pela refreshIntervalInMs propriedade.

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

A configuração refreshOptions sozinha não atualizará automaticamente a configuração. Você precisa chamar o refresh método na AzureAppConfiguration instância retornada load pelo método para disparar uma atualização.

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

Esse design evita solicitações desnecessárias à Configuração do Aplicativo quando seu aplicativo está ocioso. Você deve incluir a chamada onde a atividade do refresh aplicativo ocorre. Isso é conhecido como atualização de configuração orientada por atividade. Por exemplo, você pode chamar refresh ao processar uma solicitação de entrada ou dentro de uma iteração onde você executa uma tarefa complexa.

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

Mesmo se a chamada de atualização falhar por qualquer motivo, seu aplicativo continuará a usar a configuração em cache. Outra tentativa será feita quando o intervalo de atualização configurado tiver passado e a chamada de atualização for acionada pela atividade do aplicativo. A chamada refresh é um no-op antes do intervalo de atualização configurado passar, portanto, seu impacto no desempenho é mínimo, mesmo que seja chamado com frequência.

Retorno de chamada de atualização personalizado

O onRefresh método permite personalizar funções de retorno de chamada que serão invocadas sempre que a configuração local for atualizada com êxito com alterações do repositório de Configuração de Aplicativos do Azure. Ele retorna um objeto Descartável, que você pode usar para remover o retorno de chamada registrado

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

Atualizar a chave sentinela

Uma chave sentinela é uma chave que você atualiza depois de concluir a alteração de todas as outras chaves. O provedor de configuração monitorará a chave sentinela em vez de todos os valores-chave selecionados. Quando uma alteração é detetada, seu aplicativo atualiza todos os valores de configuração.

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

Para obter mais informações sobre a configuração de atualização, vá para Usar configuração dinâmica em JavaScript.

Sinalizador de recurso

Você pode criar sinalizadores de recursos na Configuração do Aplicativo do Azure. Por padrão, os sinalizadores de recursos não serão carregados pelo provedor de configuração. Você pode habilitar o carregamento e a atualização de sinalizadores de recursos através AzureAppConfigurationOptions.featureFlagOptions da propriedade ao chamar o load método.

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

Nota

Se featureFlagOptions estiver ativado e nenhum seletor for especificado, o provedor de configuração carregará todos os sinalizadores de recursos sem rótulo da App Configuration Store.

Importante

Para consumir e gerir eficazmente os flags de funcionalidades carregados da Configuração do Aplicativo do Azure, instale e use o pacote @microsoft/feature-management. Essa biblioteca fornece uma maneira estruturada de controlar o comportamento do recurso em seu aplicativo.

Gestão de funcionalidades

A biblioteca de gerenciamento de recursos fornece uma maneira de desenvolver e expor a funcionalidade do aplicativo com base em sinalizadores de recursos. A biblioteca de gerenciamento de recursos foi projetada para funcionar em conjunto com a biblioteca do provedor de configuração. O provedor de configuração carregará todos os sinalizadores de recursos selecionados na configuração na feature_flags lista da feature_management seção. A biblioteca de gerenciamento de recursos consumirá e gerenciará os sinalizadores de recursos carregados para seu aplicativo.

O exemplo a seguir demonstra como integrar a biblioteca @microsoft/feature-management com o provedor de configuração para gerir dinamicamente a acessibilidade da API numa aplicação Express, dependendo do estado do sinalizador de funcionalidade 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");
    }
});

Para obter mais informações sobre como usar a biblioteca de gerenciamento de recursos JavaScript, vá para o início rápido do sinalizador de recursos.

Referência do Cofre da Chave

A Configuração de Aplicativo do Azure dá suporte à referência de segredos armazenados no Cofre da Chave do Azure. Na Configuração do Aplicativo, você pode criar chaves que mapeiam para segredos armazenados no Cofre da Chave. Os segredos são armazenados com segurança no Cofre da Chave, mas podem ser acessados como qualquer outra configuração uma vez carregados.

A biblioteca do provedor de configuração recupera referências do Cofre da Chave, assim como faz para quaisquer outras chaves armazenadas na Configuração do aplicativo. Como o cliente reconhece as chaves como referências do Cofre da Chave, elas têm um tipo de conteúdo exclusivo e o cliente se conectará ao Cofre da Chave para recuperar seus valores para seu aplicativo. Você precisa configurar AzureAppConfigurationOptions.KeyVaultOptions a propriedade com a credencial adequada para permitir que o provedor de configuração se conecte ao Cofre da Chave do Azure.

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

Você também pode fornecer SecretClient instância diretamente para KeyVaultOptions. Desta forma, você pode personalizar as opções ao criar SecretCliento .

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

Você também pode definir secretResolver a propriedade para resolver localmente segredos que não têm um Cofre de Chaves associado a eles.

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

Você também pode definir a propriedade clientOptions para configurar o SecretClientOptions usado para se conectar ao Azure Key Vault que não tem SecretClient registrado.

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

Resolução secreta paralela

O Azure Key Vault não fornece uma API em lote para recuperar vários segredos em uma única solicitação. Quando a sua aplicação precisa carregar várias referências do Cofre de Chaves, pode melhorar o desempenho ativando a resolução paralela de segredos usando a parallelSecretResolutionEnabled propriedade em KeyVaultOptions. Isso permite que o provedor busque vários segredos em paralelo em vez de sequencialmente:

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

Nota

Ao resolver segredos em paralelo, você pode encontrar o limite de serviço do Cofre de Chaves do Azure. Para lidar com a limitação de forma eficaz, implemente as práticas recomendadas de limitação do lado do cliente configurando as opções de repetição apropriadas para o SecretClient. Você pode registrar instâncias personalizadas SecretClient ou configurar clientOptions por meio do AzureAppConfigurationOptions.keyVaultOptions.

Atualização de segredos do Cofre de Chaves

A Configuração de Aplicativo do Azure permite configurar intervalos de atualização secretos independentemente do seu ciclo de atualização de configuração. Isso é crucial para a segurança porque, embora o URI de referência do Cofre da Chave na Configuração do Aplicativo permaneça inalterado, o segredo subjacente no Cofre da Chave pode ser girado como parte de suas práticas de segurança.

Para garantir que seu aplicativo sempre use os valores secretos mais atuais, configure a secretRefreshIntervalInMs propriedade em KeyVaultOptions. Isso força o provedor a recuperar novos valores secretos do Cofre de Chaves quando:

  • A sua aplicação chama AzureAppConfiguration.refresh
  • O intervalo de atualização configurado para o segredo decorreu

Esse mecanismo funciona mesmo quando nenhuma alteração é detetada na sua loja de configuração de aplicações, garantindo que a sua aplicação permaneça sincronizada com segredos rodados.

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

Instantâneo

Snapshot é um subconjunto nomeado e imutável dos valores-chave de uma App Configuration Store. Os valores-chave que compõem um instantâneo são escolhidos durante o tempo de criação através do uso de filtros de chave e rótulo. Depois que um snapshot é criado, os valores-chave dentro têm a garantia de permanecer inalterados.

Você pode usar o seletor de instantâneo para carregar valores-chave ou sinalizadores de recursos de um instantâneo:

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

Repetição de inicialização

O carregamento de configuração é uma operação de caminho crítico durante a inicialização do aplicativo. Para garantir a confiabilidade, o provedor de Configuração de Aplicativo do Azure implementa um mecanismo de repetição robusto durante a carga de configuração inicial. Isso ajuda a proteger seu aplicativo contra problemas de rede transitórios que, de outra forma, poderiam impedir a inicialização bem-sucedida.

Você pode personalizar esse comportamento por meio do AzureAppConfigurationOptions.startupOptions:

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

Georreplicação

Para obter informações sobre como usar a replicação geográfica, vá para Habilitar replicação geográfica.

Próximos passos

Para saber como usar o provedor de configuração JavaScript, continue para o tutorial a seguir.

Usar configuração dinâmica em JavaScript

Para saber como usar a biblioteca de gerenciamento de recursos JavaScript, continue com a documentação a seguir.

Gerenciamento de recursos JavaScript

  • Last updated on