Provedor de configuração javaScript

A Configuração de Aplicativos do Azure é um serviço gerenciado que ajuda os desenvolvedores a centralizarem as configurações de seus aplicativos de maneira simples e segura. A biblioteca do provedor de configuração JavaScript permite carregar a configuração de um repositório de Configuração de Aplicativos do Azure de maneira gerenciada. Essa biblioteca de clientes adiciona funcionalidades adicionais acima do SDK do Azure para JavaScript.

Configuração de carregamento

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

Microsoft Entra ID
Cadeia de conexão

Use a autenticação DefaultAzureCredential no repositório da Configuração de Aplicativos. Siga as instruções para atribuir à credencial a função Leitor de Dados de Configuração de 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();

const { load } = require("@azure/app-configuration-provider");
const connectionString = process.env.AZURE_APPCONFIG_CONNECTION_STRING;

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

run();

O método load retorna uma instância do tipo AzureAppConfiguration 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.

Consumir configuração

O tipo AzureAppConfiguration estende as seguintes interfaces:

IGettable

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

A interface IGettable fornece o método get para recuperar o valor de um valor-chave da estrutura de dados estilo 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 tipo AzureAppConfiguration também estende a interface ReadonlyMap, fornecendo acesso somente leitura a pares chave-valor.
IConfigurationObject
```
interface IConfigurationObject {
    constructConfigurationObject(options?: ConfigurationObjectConstructionOptions): Record<string, any>;
}
```
A interface IConfigurationObject fornece o método constructConfigurationObject para construir um objeto de configuração com base em uma estrutura de dados com estilo 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 geralmente são usados como estruturas de dados primárias para representar configurações. A biblioteca do provedor de configuração JavaScript dá suporte a ambas as abordagens de configuração, fornecendo aos desenvolvedores a flexibilidade para escolher a opção que melhor atenda à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 de chave JSON na Configuração de Aplicativos. Ao carregar valores-chave da Configuração de Aplicativos 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 da chave acima será carregado como { size: 12, color: "red" }.

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

Observação

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

Carregar valores de chave específicos usando seletores

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

Para refinar ou expandir as configurações carregadas do repositório de Configuração de Aplicativos, você pode especificar os seletores de chave ou rótulo na propriedade 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"
        }
    ]
});

Observação

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

Filtros de etiqueta

O parâmetro de filtros de rótulo seleciona pares chave-valor com rótulos específicos. Um valor-chave só será carregado se ele tiver todas as marcas 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"
            ]
        }
    ]
});

Observação

Os caracteres asterisco (*), vírgula (,) e barra invertida (\) são reservados e devem ser precedidos por barra invertida quando usados em um filtro de rótulo.

Cortar prefixo de chaves

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

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 do repositório de Configuração de Aplicativos sem precisar reiniciar o aplicativo. Você pode definir AzureAppConfigurationOptions.refreshOptions para habilitar a atualização e configurar as opções de atualização. A configuração carregada será atualizada quando qualquer alteração dos valores-chave selecionados for detectada no servidor. Por padrão, um intervalo de atualização de 30 segundos é usado, mas você pode substituí-lo com a propriedade refreshIntervalInMs.

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

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

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

Esse design impede solicitações desnecessárias para a Configuração de Aplicativos quando o aplicativo está ocioso. Você deve incluir a chamada refresh onde ocorre a atividade do aplicativo. Isso é conhecido como atualização de configuração controlada por atividade. Por exemplo, você pode chamar refresh ao processar uma solicitação de entrada ou dentro de uma iteração em que 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 que a chamada de atualização falhe por qualquer motivo, seu aplicativo continuará a usar a configuração armazenada em cache. Outra tentativa será feita quando o intervalo de atualização configurado tiver passado e a chamada de atualização for disparada pela atividade do aplicativo. Chamar refresh é uma não operação antes que o intervalo de atualização configurado decorra, portanto, seu impacto no desempenho é mínimo, mesmo se essa chamada é realizada com frequência.

Retorno de chamada de atualização personalizado

O método onRefresh permite que você use funções de retorno de chamada personalizadas que serão invocadas sempre que a configuração local for atualizada com êxito com as 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 na 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 de chave selecionados. Quando uma alteração é detectada, o 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, acesse Usar a configuração dinâmica no JavaScript.

Sinalizador de recurso

Você pode criar sinalizadores de recursos na Configuração de Aplicativos 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 atualização de sinalizadores de recursos por meio da propriedade AzureAppConfigurationOptions.featureFlagOptions ao chamar o método 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
        }
    }
});

Observação

Se featureFlagOptions estiver habilitado e nenhum seletor for especificado, o provedor de configuração carregará todos os sinalizadores de recursos sem rótulo do repositório de Configuração de Aplicativos.

Importante

Para consumir e gerenciar com eficiência os sinalizadores de recurso carregados da Configuração de Aplicativos 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.

Gerenciamento de recursos

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 lista feature_flags da seção feature_management. 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 controlar dinamicamente a acessibilidade da API em uma aplicação Express com base no status do flag de recurso 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, acesse o início rápido do sinalizador de recursos.

Referência do Key Vault

A Configuração de Aplicativos do Azure dá suporte à referência a segredos armazenados no Azure Key Vault. Na Configuração de Aplicativos, você pode criar chaves que mapeiam para segredos armazenados no Key Vault. Os segredos são armazenados com segurança no Key Vault, mas podem ser acessados como qualquer outra configuração depois de carregadas.

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

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

Você também pode fornecer a instância SecretClient diretamente para KeyVaultOptions. Dessa forma, você pode personalizar as opções durante a criação 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 ]
    }
});

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

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

Você também pode definir clientOptions propriedade para configurar SecretClientOptions usados para se conectar ao Azure Key Vault que não tem nenhum 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 do segredo paralelo

O Azure Key Vault não fornece uma API em lote para recuperar vários segredos em uma única solicitação. Quando seu aplicativo precisa carregar várias referências do Key Vault, você pode melhorar o desempenho habilitando a resolução de segredo paralela usando a propriedade parallelSecretResolutionEnabled 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
    }
});

Observação

Ao resolver o segredo em paralelo, você pode encontrar o limite de serviço do Azure Key Vault. Para lidar com a limitação com eficiência, 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 Key Vault

A Configuração de Aplicativos do Azure permite que você configure intervalos de atualização secretos independentemente do ciclo de atualização de configuração. Isso é crucial para a segurança porque, embora o URI de referência do Key Vault na Configuração de Aplicativos permaneça inalterado, o segredo subjacente no Key Vault poderá ser girado como parte de suas práticas de segurança.

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

Seu aplicativo chama AzureAppConfiguration.refresh
O intervalo de atualização configurado para o segredo já transcorreu.

Esse mecanismo funciona mesmo quando nenhuma alteração é detectada no repositório da Configuração de Aplicativos, garantindo que seu aplicativo permaneça sincronizado com segredos girados.

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

Instantâneo

O instantâneo é um subconjunto nomeado e imutável dos valores-chave de um repositório da Configuração de Aplicativos. Os pares chave-valor que compõem um instantâneo são escolhidos no momento da criação por meio do uso de filtros de chave e rótulo. Depois que um instantâneo é criado, os pares chave-valor nele contidos têm a garantia de permanecer inalterados.

Você pode usar o seletor de instantâneo para carregar chave-valor 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" }
        ]
    }
});

Tentar novamente a 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 Aplicativos do Azure implementa um mecanismo de repetição robusto durante a carga de configuração inicial. Isso ajuda a proteger seu aplicativo contra problemas transitórios de rede que, de outra forma, podem 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
    }
});

Replicação geográfica

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

Próximas etapas

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

Usar a configuração dinâmica no JavaScript

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

Gerenciamento de recursos javaScript

Comentários

Esta página foi útil?

Last updated on 2025-08-20

Compartilhar via

Provedor de configuração javaScript

Configuração de carregamento

Consumir configuração

Tratamento de tipo de conteúdo JSON

Carregar valores de chave específicos usando seletores

Filtros de etiqueta

Cortar prefixo de chaves

Atualização de configuração

Retorno de chamada de atualização personalizado

Atualizar na chave sentinela

Sinalizador de recurso

Gerenciamento de recursos

Referência do Key Vault

Resolução do segredo paralelo

Atualização de segredos do Key Vault

Instantâneo

Tentar novamente a inicialização

Replicação geográfica

Próximas etapas

Comentários

Recursos adicionais