JavaScript용 App Configuration 클라이언트 라이브러리

Azure App Configuration 개발자가 애플리케이션 및 기능 설정을 간단하고 안전하게 중앙 집중화하는 데 도움이 되는 관리형 서비스입니다.

App Configuration용 클라이언트 라이브러리를 사용하여 다음을 수행합니다.

• 유연한 키 표현 및 매핑 만들기
• 레이블을 사용하여 키 태그 지정
• 특정 시점의 설정 재생
• 앱 구성의 스냅샷 관리

키 링크:

• 소스 코드
• NPM(패키지)
• API 참조 설명서
• 제품 설명서
• 샘플

시작

패키지 설치

npm install @azure/app-configuration

현재 지원되는 환경

• Node.js의 LTS 버전
• Safari, Chrome, Edge 및 Firefox의 최신 버전입니다.

자세한 내용은 지원 정책 참조하세요.

필수 구성 요소

• Azure 구독
• App Configuration 리소스

App Configuration 리소스 만들기

Azure Portal 또는 Azure CLI 사용하여 Azure App Configuration 리소스를 만들 수 있습니다.

예제(Azure CLI):

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

클라이언트 인증

AppConfigurationClient는 서비스 주체 사용하거나 연결 문자열사용하여 인증할 수 있습니다.

서비스 주체를 사용하여 인증

서비스 주체를 통한 인증은 다음을 통해 수행됩니다.

• @azure/identity 패키지를 사용하여 자격 증명 만들기
• AppConfiguration 리소스에 적절한 RBAC 규칙 설정 App Configuration 역할에 대한 자세한 내용은여기에서 찾을 수 있습니다.

DefaultAzureCredential 사용

const azureIdentity = require("@azure/identity");
const appConfig = require("@azure/app-configuration");

const credential = new azureIdentity.DefaultAzureCredential();
const client = new appConfig.AppConfigurationClient(
  endpoint, // ex: <https://<your appconfig resource>.azconfig.io>
  credential
);

대한 자세한 내용은 여기에서 찾을 수 있습니다.

소버린 클라우드

소버린 클라우드리소스로 인증하려면 자격 증명 옵션 또는 AZURE_AUTHORITY_HOST 환경 변수를 통해 authorityHost 설정해야 합니다.

const { AppConfigurationClient } = require("@azure/app-configuration");
const { DefaultAzureCredential, AzureAuthorityHosts } = require("@azure/identity");

// Create an AppConfigurationClient that will authenticate through AAD in the China cloud
const client = new AppConfigurationClient(
  endpoint, // ex: <https://<your appconfig resource>.azconfig.azure.cn>
  new DefaultAzureCredential({ authorityHost: AzureAuthorityHosts.AzureChina })
);

대한 자세한 내용은 여기에서 찾을 수 있습니다.

연결 문자열을 사용하여 인증

App Configuration 리소스에 대한 기본 연결 문자열 얻으려면 다음 Azure CLI 명령을 사용할 수 있습니다.

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

이제 코드에서 Azure CLI에서 얻은 연결 문자열을 사용하여 App Configuration 클라이언트를 만들 수 있습니다.

const client = new AppConfigurationClient("<connection string>");

주요 개념

AppConfigurationClient 포털의 App Configuration에서 몇 가지 용어를 변경합니다.

• 키/값 쌍은 ConfigurationSetting 개체로 표시됩니다.
• 설정 잠금 및 잠금 해제는 setReadOnly사용하여 전환할 수 있는 isReadOnly 필드에 표시됩니다.
• 스냅샷은 ConfigurationSnapshot 개체로 표시됩니다.

클라이언트는 간단한 디자인 방법론을 따릅니다. ConfigurationSettingConfigurationSettingParam 사용하거나 ConfigurationSettingId모든 메서드에 전달할 수 있습니다.

즉, 이 패턴은 다음과 같이 작동합니다.

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

또는, 예를 들어 설정을 다시 가져오는 경우:

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

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

2022-11-01-preview API 버전은 구성 스냅샷을 지원합니다. 변경 불가능한 구성 저장소의 지정 시간 복사본입니다. 스냅샷에 포함된 키-값 쌍을 결정하는 필터를 사용하여 스냅샷을 만들 수 있으며, 구성 저장소의 변경할 수 없는 구성 보기를 만들 수 있습니다. 이 기능을 사용하면 애플리케이션이 일관된 구성 보기를 유지할 수 있으므로 업데이트가 수행된 대로 읽기 때문에 개별 설정에 대한 버전 불일치가 없도록 할 수 있습니다. 예를 들어 이 기능을 사용하여 App Configuration 내에서 "릴리스 구성 스냅샷"을 만들 수 있습니다. 아래 예제에서 스냅샷 섹션 만들고 가져오는 참조하세요.

예제

설정 만들기 및 가져오기

const appConfig = require("@azure/app-configuration");

const client = new appConfig.AppConfigurationClient(
  "<App Configuration connection string goes here>"
);

async function run() {
  const newSetting = 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.
    // /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);
}

run().catch((err) => console.log("ERROR:", err));

스냅샷 만들기

beginCreateSnapshot 스냅샷 생성을 폴링할 수 있는 폴러를 제공합니다.

const { AppConfigurationClient } = require("@azure/app-configuration");

const client = new AppConfigurationClient(
  "<App Configuration connection string goes here>"
);


async function run() {
  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();
}

run().catch((err) => console.log("ERROR:", err));

beginCreateSnapshotAndWait 사용하여 폴링이 완료된 직후 생성 결과를 가져올 수도 있습니다.

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

스냅샷 가져오기

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

스냅샷의 ConfigurationSetting 나열

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

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

서비스의 모든 스냅샷 나열

const snapshots = await client.listSnapshots();

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

스냅샷 복구 및 보관

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

문제 해결

로깅

로깅을 사용하도록 설정하면 오류에 대한 유용한 정보를 파악하는 데 도움이 될 수 있습니다. HTTP 요청 및 응답 로그를 보려면 AZURE_LOG_LEVEL 환경 변수를 info설정합니다. 또는 setLogLevel@azure/logger 호출하여 런타임에 로깅을 사용하도록 설정할 수 있습니다.

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

로그를 사용하도록 설정하는 방법에 대한 자세한 지침은 @azure/로거 패키지 문서확인할 수 있습니다.

React 네이티브 지원

React Native는 이 SDK 라이브러리에서 사용하는 일부 JavaScript API를 지원하지 않으므로 폴리필을 제공해야 합니다. 자세한 내용은 Expo React Native 샘플을 참조하세요.

다음 단계

다음 샘플에서는 App Configuration과 상호 작용할 수 있는 다양한 방법을 보여줍니다.

• helloworld.ts - 구성 값을 가져오기, 설정 및 삭제합니다.
• helloworldWithLabels.ts - 레이블을 사용하여 베타 및 프로덕션과 같은 시나리오의 설정에 차원을 더 추가합니다.
• optimisticConcurrencyViaEtag.ts - 실수로 덮어쓰지 않도록 etag를 사용하여 값을 설정합니다.
• setReadOnlySample.ts - 수정을 방지하기 위해 설정을 읽기 전용으로 표시합니다.
• getSettingOnlyIfChanged.ts - 마지막으로 설정한 시점부터 변경된 경우에만 설정을 가져옵니다.
• listRevisions.ts - 키의 수정 버전을 나열하여 이전 값과 설정 시기를 볼 수 있도록 합니다.
• secretReference.ts - SecretReference는 KeyVault 비밀로 참조하는 구성 설정을 나타냅니다.
• snapshot.ts - 만들기, 구성 설정 나열 및 스냅샷 보관
• featureFlag.ts - 기능 플래그는 값에 대한 특정 JSON 스키마를 따르는 설정입니다.

자세한 예제는 GitHub의 샘플 폴더에서 찾을 수 있습니다.

기여

이 라이브러리에 기여하려면 기여 가이드 읽어 코드를 빌드하고 테스트하는 방법에 대해 자세히 알아보세요.

이 모듈의 테스트는 라이브 및 단위 테스트가 혼합되어 있으므로 Azure App Configuration 인스턴스가 있어야 합니다. 테스트를 실행하려면 다음을 실행해야 합니다.

1. rush update
2. rush build -t @azure/app-configuration
3. sdk\appconfiguration\app-configuration 폴더에 다음 내용을 사용하여 .env 파일을 만듭니다. APPCONFIG_CONNECTION_STRING=connection string for your App Configuration instance
4. cd sdk\appconfiguration\app-configuration
5. npm run test.

자세한 내용은 테스트 폴더를 참조하세요.

관련 프로젝트

• JavaScript용 Microsoft Azure SDK
• Azure App Configuration