Provedor de configuração JavaScript

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.

Microsoft Entra ID

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 settings = await load(endpoint, credential);
    console.log('settings.get("message"):', settings.get("message"));
}

run();

Cadeia de ligação

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 settings = await load(connectionString);
    console.log('settings.get("message"):', settings.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 settings = await load(endpoint, credential);
  const fontSize = settings.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 settings = await load(endpoint, credential);
  const settingsObj = settings.constructConfigurationObject({separator: ":"});
  const fontSize1 = settings.get("app:font:size"); // map-style configuration representation
  const fontSize2 = settingsObj.app.font.size; // object-style configuration representation
  

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 settings = 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 starting with "dev" label"
            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.

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 settings = await load(endpoint, credential, {
    selectors: [{
        keyFilter: "app.*"
    }],
    trimKeyPrefixes: ["app."]
});

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 settings = 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 .

const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();
const secretClient = new SecretClient(keyVaultUrl, credential, {
    serviceVersion: "7.0",
});
const settings = 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 settings = await load(endpoint, credential, {
    keyVaultOptions: {
        secretResolver: resolveSecret
    }
});

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 settings = 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
settings.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) => {
    settings.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 settings = await load(endpoint, credential, {
    refreshOptions: {
        enabled: true
    }
});
const disposer = settings.onRefresh(() => {
    console.log("Config refreshed.");
});

settings.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 (Legado)

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 settings = 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 settings = await load(endpoint, credential, {
    featureFlagOptions: {
        enabled: true,
        selectors: [ { keyFilter: "*", labelFilter: "Prod" } ],
        refresh: {
            enabled: true, // the refresh for feature flags need to be enbaled in addition to key-values
            refreshIntervalInMs: 10_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.

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.

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.

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