Compartilhar via

Biblioteca de clientes da Configuração de Aplicativos do Azure para JavaScript – versão 1.10.0

a Configuração de Aplicativos do Azure é um serviço gerenciado que ajuda os desenvolvedores a centralizar suas configurações de aplicativos e recursos de forma simples e segura.

Links de chave:

Escolha o pacote certo

Use @azure/app-configuration (esta biblioteca) para:

  • Gerenciar definições de configuração e instantâneos na Configuração de Aplicativos do Azure
  • Executar leituras granulares que operam fora do domínio do consumo normal de configuração

A maioria dos aplicativos deve começar com a biblioteca @azure/app-configuration-provider , que se baseia nessa biblioteca de cliente de baixo nível e é a maneira recomendada de consumir a configuração em runtime. Acrescenta:

  • Padrões de acesso flexíveis usando a configuração como um mapa de chave/valor ou um objeto JSON estruturado
  • Mecanismo de consulta para compor declarativamente a configuração do aplicativo
  • Atualização de configuração durante o tempo de execução
  • Alta confiabilidade com armazenamento em cache, descoberta de réplicas, failover e balanceamento de carga
  • Resolução de referência do cofre de chaves e atualização automática
  • Integração de sinalizador de recurso para @microsoft/biblioteca de gerenciamento de recursos

Para obter mais informações, acesse a visão geral do provedor de configuração.

Introdução

Instalar o pacote

npm install @azure/app-configuration

Nota: Para aplicativos que precisam apenas ler valores de configuração, sugerimos usar a biblioteca @azure/app-configuration-provider .

Ambientes com suporte no momento

Consulte nossa política de suporte para obter mais detalhes.

Pré-requisitos

  • Uma assinatura do Azure
  • Um recurso de Configuração de Aplicativo

Criar um recurso de Configuração de Aplicativo

Você pode usar a do Portal do Azure ou a CLI do Azure para criar um recurso de Configuração de Aplicativo do Azure.

Exemplo (CLI do Azure):

az appconfig create --name <app-configuration-resource-name> --resource-group <resource-group-name> --location eastus

Autenticar o cliente

AppConfigurationClient pode autenticar usando uma entidade de serviço ou usando uma cadeia de conexão .

Autenticação com uma entidade de serviço

A autenticação por meio da entidade de serviço é feita por:

  • Criando uma credencial usando o pacote @azure/identity.
  • Definindo regras RBAC apropriadas em seu recurso AppConfiguration. Mais informações sobre as funções de Configuração de Aplicativo podem ser encontradas aqui.

Usando DefaultAzureCredential

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

Mais informações sobre @azure/identity podem ser encontradas aqui

Nuvens soberanas

Para autenticar com um recurso em uma Nuvem Soberana, você precisará definir as audienceAppConfigurationClient opções do construtor.

import { AppConfigurationClient, KnownAppConfigAudience } from "@azure/app-configuration";
import { DefaultAzureCredential } from "@azure/identity";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.azure.cn";
// Create an AppConfigurationClient that will authenticate through AAD in the China cloud
const client = new AppConfigurationClient(endpoint, new DefaultAzureCredential(), {
  audience: KnownAppConfigAudience.AzureChina,
});

Observação: quando audience a propriedade não for definida, o SDK será padronizado para a Nuvem Pública do Azure.

Autenticação com uma cadeia de conexão

Para obter a cadeia de conexão de primária para um recurso de Configuração de Aplicativo, você pode usar este comando da CLI do Azure:

az appconfig credential list -g <resource-group-name> -n <app-configuration-resource-name> --query "([?name=='Primary'].connectionString)[0]"

No código, agora você pode criar seu cliente de Configuração de Aplicativo com a cadeia de conexão você obteve da CLI do Azure:

import { AppConfigurationClient } from "@azure/app-configuration";

const connectionString = "Endpoint=https://example.azconfig.io;XXX=YYYY;YYY=ZZZZ";
const client = new AppConfigurationClient(connectionString);

Principais conceitos

O AppConfigurationClient tem algumas alterações de terminologia da Configuração de Aplicativos no portal.

  • Pares chave/valor são representados como objetos ConfigurationSetting
  • O bloqueio e o desbloqueio de uma configuração são representados no campo isReadOnly, que você pode alternar usando setReadOnly.
  • Instantâneos são representados como objetos ConfigurationSnapshot.

O cliente segue uma metodologia de design simples – ConfigurationSetting pode ser passado para qualquer método que usa um ConfigurationSettingParam ou ConfigurationSettingId.

Isso significa que esse padrão funciona:

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const setting = await client.getConfigurationSetting({
  key: "hello",
});

setting.value = "new value!";
await client.setConfigurationSetting(setting);

// fields unrelated to just identifying the setting are simply
// ignored (for instance, the `value` field)
await client.setReadOnly(setting, true);

// delete just needs to identify the setting so other fields are
// just ignored
await client.deleteConfigurationSetting(setting);

ou, por exemplo, obter novamente uma configuração:

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

let setting = await client.getConfigurationSetting({
  key: "hello",
});

// re-get the setting
setting = await client.getConfigurationSetting(setting);

A versão da API 2022-11-01-preview dá suporte a instantâneos de configuração: cópias pontuais e imutáveis de um repositório de configuração. Instantâneos podem ser criados com filtros que determinam quais pares chave-valor estão contidos no instantâneo, criando uma exibição imutável e composta do repositório de configuração. Esse recurso permite que os aplicativos mantenham uma exibição consistente da configuração, garantindo que não haja incompatibilidades de versão nas configurações individuais devido à leitura à medida que as atualizações foram feitas. Por exemplo, esse recurso pode ser usado para criar "instantâneos de configuração de versão" em uma Configuração de Aplicativo. Consulte o criar e obter um instantâneo seção no exemplo abaixo.

Exemplos

Nota: Se o aplicativo precisar apenas recuperar valores de configuração e não exigir a execução de operações de criação, atualização ou exclusão nas definições de configuração, considere usar a biblioteca @azure/app-configuration-provider . A biblioteca de provedores oferece uma experiência simplificada para carregar dados de configuração em tempo de execução e recursos adicionais. Você pode encontrar muitos exemplos de código na documentação da Configuração de Aplicativos do Azure no Microsoft Learn.

Criar e obter uma configuração

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

await client.setConfigurationSetting({
  key: "testkey",
  value: "testvalue",
  // Labels allow you to create variants of a key tailored
  // for specific use-cases like supporting multiple environments.
  // https://learn.microsoft.com/azure/azure-app-configuration/concept-key-value#label-keys
  label: "optional-label",
});

const retrievedSetting = await client.getConfigurationSetting({
  key: "testkey",
  label: "optional-label",
});

console.log("Retrieved value:", retrievedSetting.value);

Criar um instantâneo

beginCreateSnapshot fornece o sondador para sondar a criação do instantâneo.

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const key = "testkey";
const value = "testvalue";
const label = "optional-label";

await client.addConfigurationSetting({
  key,
  value,
  label,
});

const poller = await client.beginCreateSnapshot({
  name: "testsnapshot",
  retentionPeriod: 2592000,
  filters: [{ keyFilter: key, labelFilter: label }],
});
const snapshot = await poller.pollUntilDone();

Você também pode usar beginCreateSnapshotAndWait para ter o resultado da criação diretamente após a conclusão da sondagem.

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const key = "testkey";
const value = "testvalue";
const label = "optional-label";

const snapshot = await client.beginCreateSnapshotAndWait({
  name: "testsnapshot",
  retentionPeriod: 2592000,
  filters: [{ keyFilter: key, labelFilter: label }],
});

Obter um instantâneo

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const retrievedSnapshot = await client.getSnapshot("testsnapshot");
console.log("Retrieved snapshot:", retrievedSnapshot);

Listar o ConfigurationSetting no instantâneo

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const retrievedSnapshotSettings = await client.listConfigurationSettingsForSnapshot("testsnapshot");

for await (const setting of retrievedSnapshotSettings) {
  console.log(`Found key: ${setting.key}, label: ${setting.label}`);
}

Listar todos os instantâneos do serviço

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const snapshots = await client.listSnapshots();

for await (const snapshot of snapshots) {
  console.log(`Found snapshot: ${snapshot.name}`);
}

Recuperar e arquivar o instantâneo

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

// Snapshot is in ready status
const archivedSnapshot = await client.archiveSnapshot("testsnapshot");
console.log("Snapshot updated status is:", archivedSnapshot.status);

// Snapshot is in archive status
const recoverSnapshot = await client.recoverSnapshot("testsnapshot");
console.log("Snapshot updated status is:", recoverSnapshot.status);

Solucionando problemas

Log

Habilitar o registro em log pode ajudar a descobrir informações úteis sobre falhas. Para ver um log de solicitações e respostas HTTP, defina a variável de ambiente AZURE_LOG_LEVEL como info. Como alternativa, o registro em log pode ser habilitado em runtime chamando setLogLevel no @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Para obter instruções mais detalhadas sobre como habilitar logs, você pode examinar os documentos do pacote @azure/agente.

Suporte do React Native

O React Native não dá suporte a alguma API JavaScript usada por essa biblioteca do SDK, portanto, você precisa fornecer polyfills para eles. Confira nosso exemplo do React Native com o Expo para obter mais detalhes.

Próximas etapas

Os exemplos a seguir mostram as várias maneiras de interagir com a Configuração de Aplicativos:

  • helloworld.ts – Obter, definir e excluir valores de configuração.
  • helloworldWithLabels.ts - Use rótulos para adicionar dimensões adicionais às suas configurações para cenários como beta versus produção.
  • optimisticConcurrencyViaEtag.ts – Defina valores usando etags para evitar substituições acidentais.
  • setReadOnlySample.ts - Marcando as configurações como somente leitura para impedir a modificação.
  • getSettingOnlyIfChanged.ts - Obtenha uma configuração somente se ela tiver sido alterada da última vez que você a tiver.
  • listRevisions.ts - Listar as revisões de uma chave, permitindo que você veja os valores anteriores e quando eles foram definidos.
  • secretReference.ts – SecretReference representa uma configuração que faz referência como segredo KeyVault.
  • snapshot.ts – Criar, listar configurações e arquivar instantâneos.
  • featureFlag.ts - Sinalizadores de recurso são configurações que seguem um esquema JSON específico para o valor.

Exemplos mais detalhados podem ser encontrados na pasta exemplos no GitHub.

Contribuindo

Se você quiser contribuir com essa biblioteca, leia o guia de contribuição para saber mais sobre como criar e testar o código.

Os testes deste módulo são uma mistura de testes dinâmicos e de unidade, que exigem que você tenha uma instância de Configuração de Aplicativo do Azure. Para executar os testes, você precisará executar:

  1. pnpm install
  2. pnpm build --filter @azure/app-configuration...
  3. Crie um arquivo .env com este conteúdo na pasta sdk\appconfiguration\app-configuration: APPCONFIG_CONNECTION_STRING=connection string for your App Configuration instance
  4. cd sdk\appconfiguration\app-configuration
  5. npm run test.

Exiba nossos testes de pasta para obter mais detalhes.

  • Last updated on