次の方法で共有

JavaScript 用App Configuration クライアント ライブラリ

  • [アーティクル]

Azure App Configurationは、開発者がアプリケーションと機能の設定を簡単かつ安全に一元化するのに役立つマネージド サービスです。

クライアント ライブラリを使用して、次のApp Configurationを行います。

  • 柔軟なキー表現とマッピングを作成する
  • ラベルを使用してキーにタグを付けます
  • 任意の時点から設定を再生する
  • アプリの構成のスナップショットを管理する

主要リンク:

作業の開始

パッケージをインストールする

npm install @azure/app-configuration

現在サポートされている環境

詳細については、Microsoft のサポート ポリシーを参照してください。

前提条件

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/identity、こちらを参照してください。

ソブリン クラウド

ソブリン クラウドのリソースで認証するには、資格情報オプションまたは環境変数を使用して を設定authorityHostするAZURE_AUTHORITY_HOST必要があります。

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

詳細については@azure/identity、こちらを参照してください。

接続文字列を使用した認証

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 表されます
  • 設定のロックとロック解除は フィールドで isReadOnly 表され、 を使用して setReadOnly切り替えることができます。
  • スナップショットはオブジェクトとして ConfigurationSnapshot 表されます。

クライアントは、単純な設計手法に従います。ConfigurationSettingまたは ConfigurationSettingIdを受け取るConfigurationSettingParam任意のメソッドに渡すことができます。

これは、このパターンが機能することを意味します。

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

API バージョンでは 2022-11-01-preview 、構成スナップショット (変更できない、構成ストアのポイントインタイム コピー) がサポートされています。 スナップショットは、スナップショット内に含まれるキーと値のペアを決定するフィルターを使用して作成でき、構成ストアの不変の構成済みビューを作成します。 この機能により、アプリケーションは構成の一貫したビューを保持し、更新が行われた時点での読み取りによる個々の設定に対するバージョンの不一致がないことを確認できます。 たとえば、この機能を使用して、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"
  });

  let 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スナップショットの を一覧表示する

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

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

サービスからのすべてのスナップショットを一覧表示する

let snapshots = await client.listSnapshots();

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

スナップショットを回復してアーカイブする

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

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

トラブルシューティング

ログ記録

ログの記録を有効にすると、エラーに関する有用な情報を明らかにするのに役立つ場合があります。 HTTP 要求と応答のログを表示するには、環境変数 AZURE_LOG_LEVEL を info に設定します。 または、@azure/logger で setLogLevel を呼び出して、実行時にログ記録を有効にすることもできます。

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

setLogLevel("info");

ログを有効にする方法の詳細については、@azure/logger パッケージに関するドキュメントを参照してください。

React Nativeサポート

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 の samples フォルダーを参照してください。

共同作成

このライブラリに投稿する場合、コードをビルドしてテストする方法の詳細については、投稿ガイドを参照してください。

このモジュールのテストは、ライブ テストと単体テストの組み合わせであり、Azure App Configuration インスタンスが必要です。 テストを実行するには、次を実行する必要があります。

  1. rush update
  2. rush build -t @azure/app-configuration
  3. フォルダーに次の内容を含む .env ファイルを sdk\appconfiguration\app-configuration 作成します。 APPCONFIG_CONNECTION_STRING=connection string for your App Configuration instance
  4. cd sdk\appconfiguration\app-configuration
  5. npm run test.

詳細については、 テスト フォルダーを参照してください。

インプレッション数