次の方法で共有

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

  • [アーティクル]

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

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

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

主要なリンク:

はじめ

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

npm install @azure/app-configuration

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

  • Node.js の LTS バージョンを する
  • Safari、Chrome、Edge、Firefox の最新バージョン。

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

前提 条件

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 の詳細については、こちらをご覧

ソブリン クラウド

ソブリン クラウドのリソースで認証するには、資格情報オプションまたは 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 })
);

@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 は、ConfigurationSettingParam または 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/logger パッケージのドキュメントを参照してください。

React Native のサポート

React Native では、この SDK ライブラリで使用される一部の JavaScript API がサポートされていないため、それらにポリフィルを提供する必要があります。 詳細については、React Native サンプルと Expo を参照してください。

次の手順

次のサンプルは、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.

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

インプレッション