App Configuration JavaScript Client SDK

ibm-appconfiguration-js-client-sdk 使用するアプリケーションのセキュリティを強化するために、initメソッドではプレーンなAPIKeyの代わりに暗号化されたAPIKey を使用することを強く推奨します。 この変更は、ユーザがウェブ・アプリケーションを検査する際に、機密性の高い認証情報の漏洩を防ぐために不可欠です。 すでにプレーンAPIKeyを使用している場合は、ここ に記載されている手順に従って、暗号化APIKeyを生成して使用するようにアプリケーションを更新してください。

概要

IBM Cloud App Configuration JavaScriptクライアントSDKは、IBM Cloud上の設定に基づいて、Webアプリケーションで機能フラグとプロパティ評価を実行し、Experimentationのカスタムメトリクスを追跡するために使用されます。{サービスに基づいて、実験用のカスタムメトリクスのトラッキングを行いますApp Configuration

IBM Cloud App Configuration は、一元化された機能管理とコンフィギュレーション・サービスです。 サービスです。 IBM Cloud Webアプリケーションやモバイル・アプリケーション、マイクロサービス、分散環境で使用される で使用されます。

Web アプリケーションをApp Configurationでインスツルメンテーションします。JavaScriptクライアントSDKを使用し、App Configurationダッシュボード、CLI、またはAPIを使用して、コレクションに整理され、セグメントにターゲット化された機能フラグやプロパティを定義します。 クラウドで機能フラグの状態を切り替え クラウドの機能フラグの状態を切り替えて、必要に応じてアプリケーションや環境の機能を有効または無効にします。 カスタムメトリクスを追跡することで、実験を行い、機能フラグがエンドユーザーに与える影響を測定します。 また、分散アプリケーションのプロパティーを一元的に管理することもできます。

ブラウザの互換性:SDKはすべての主要ブラウザでサポートされています。 ブラウザは「fetch() APIをサポートすべきである。

Client SDK for JavaScript の統合

インストール

SDK をインストールします。 パッケージ・マネージャーからモジュールとしてインストールするには、以下のコードを使用する。

npm install ibm-appconfiguration-js-client-sdk

SDKをscriptタグにインポートするには、バックエンドのホストされているサイトから参照するか、次のようにCDNから参照します:

例:

<script type="text/javascript" src="https://unpkg.com/ibm-appconfiguration-js-client-sdk/dist/appconfiguration.js"></script>

SDK の初期化

App Configuration サービス・インスタンスと接続するように SDK を初期化します。

const region = AppConfiguration.REGION_US_SOUTH;
const guid = '<guid>';
const apikey = '<encrypted_apikey>';

const collectionId = 'airlines-webapp';
const environmentId = 'dev';

const appConfigClient = AppConfiguration.getInstance();

async function initialiseAppConfig() {
    appConfigClient.init(region, guid, apikey);
    await appConfigClient.setContext(collectionId, environmentId);
}

try {
    await initialiseAppConfig();
    console.log("app configuration sdk init successful");
} catch (e) {
    console.error("failed to initialise app configuration sdk", e);
}

前のコードでは、非同期関数 initialiseAppConfig() が、設定が正常に取得されたときに解決する Promise<void> を返します。 失敗した場合はエラーを投げる。

初期化は一度だけ行うことが期待されている。

SDKが正常に初期化された後、次のコードスニペットで示されているように、 appConfigClient を使用して機能フラグとプロパティを取得できます。

スニペット例を表示するには拡大する
// other-file.js
const appConfigClient = AppConfiguration.getInstance();

const feature = appConfigClient.getFeature('online-check-in');
const result = feature.getCurrentValue(entityId, entityAttributes);
console.log(result);

const property = appConfigClient.getProperty('check-in-charges');
const result = property.getCurrentValue(entityId, entityAttributes);
console.log(result);

各部の意味は以下のとおりです。

  • region : App Configuration サービスインスタンスが作成されるリージョン名。 対応拠点のリストは こちら。 例: us-southau-syd など。
  • guid: App Configuration サービスのインスタンス ID。 App Configuration ダッシュボードのサービス資格情報セクションから取得する。
  • apikey:ここ で説明されているように生成された暗号化されたAPIKey。
  • collectionIdCollections セクションの App Configuration サービスインスタンスで作成されたコレクションのID。
  • environmentId : App Configuration サービスインスタンスの「 環境」 セクションで作成された環境の ID。

機密情報の漏洩を避けるため、常に暗号化されたAPIKeyを使用してください。
ブラウザベースのアプリケーションで使用するのに適した最小限のアクセス権限を持っているので、「 Client SDK ロールでサービス資格情報を作成するようにしてください。

機能関連 API およびプロパティー関連 API の使用例

フィーチャー関連 API の使用については、以下の例を参照してください。

単一の機能を取得する

const feature = appConfigClient.getFeature('featureId'); // throws error incase the featureId is invalid or doesn't exist
console.log(`Feature Name ${feature.getFeatureName()} `);
console.log(`Feature Id ${feature.getFeatureId()} `);
console.log(`Feature Type ${feature.getFeatureDataType()} `);

すべての機能を取得する

const features = appConfigClient.getFeatures();
const feature = features['featureId'];

if (feature !== undefined) {
  console.log(`Feature Name ${feature.getFeatureName()} `);
  console.log(`Feature Id ${feature.getFeatureId()} `);
  console.log(`Feature Type ${feature.getFeatureDataType()} `);
  console.log(`Is feature enabled? ${feature.isEnabled()} `);
}

フィーチャーの評価

feature.getCurrentValue(entityId, entityAttributes) メソッドを使用して、特徴フラグの値を評価する。 このメソッドは、評価に基づいて、有効/無効/オーバーライドされた値のいずれかを返します。 戻り値のデータ・タイプは、フィーチャー・フラグのデータ・タイプと一致します。

const entityId = 'john_doe';
const entityAttributes = {
  city: 'Bangalore',
  country: 'India',
};

const feature = appConfigClient.getFeature('featureId');
const featureValue = feature.getCurrentValue(entityId, entityAttributes);
  • entityId: エンティティーの ID。 これは、フィーチャーが評価されるエンティティーに関連するストリング ID になります。 例えば、エンティティはモバイルデバイス上で実行されるアプリのインスタンスかもしれないし、ウェブアプリケーションにアクセスするユーザーかもしれない。 どのエンティティも、 App Configuration と相互作用するためには、一意のエンティティIDを提供しなければならない。
  • entityAttributes: 指定されたエンティティーを定義する属性名とその値で構成される JSON オブジェクト。 フィーチャー・フラグがターゲット定義で構成されていない場合、これはオプション・パラメーターです。 ターゲットが構成されている場合は、ルール評価のために entityAttributes を指定する必要があります。 属性は、セグメントを定義するために使用されるパラメーターです。 SDK は、属性値を使用して、指定されたエンティティーがターゲット・ルールを満たしているかどうかを判別し、適切なフィーチャー・フラグ値を返します。

カスタムメトリクスの送信

トラック機能を使用して、実験に使用するカスタムメトリクスを記録します。

appConfigClient.track(eventKey, entityId)

ここで

  • eventKey: 走行中の実験に関連するメトリックのイベントキー。 メトリックのイベント・キーとコードのイベント・キーは正確に一致しなければならない。

単一のプロパティーを取得する

const property = appConfigClient.getProperty('propertyId'); // throws error incase the propertyId is invalid or doesn't exist
console.log(`Property Name ${property.getPropertyName()} `);
console.log(`Property Id ${property.getPropertyId()} `);
console.log(`Property Type ${property.getPropertyDataType()} `);

すべてのプロパティーを取得する

const properties = appConfigClient.getProperties();
const property = properties['propertyId'];

if (property !== undefined) {
  console.log(`Property Name ${property.getPropertyName()} `);
  console.log(`Property Id ${property.getPropertyId()} `);
  console.log(`Property Type ${property.getPropertyDataType()} `);
}

プロパティーの評価

不動産の価値を評価するには、 property.getCurrentValue(entityId, entityAttributes) メソッドを使用する。 このメソッドは、評価に基づいて、デフォルトのプロパティー値またはオーバーライドされた値を返します。 戻り値のデータ・タイプは、プロパティーのデータ・タイプと一致します。

const entityId = 'john_doe';
const entityAttributes = {
  city: 'Bangalore',
  country: 'India',
};

const property = appConfigClient.getProperty('propertyId');
const propertyValue = property.getCurrentValue(entityId, entityAttributes);
  • entityId: エンティティーの ID。 これは、プロパティーの評価対象となるエンティティーに関連するストリング ID になります。 例えば、エンティティはモバイルデバイス上で実行されるアプリのインスタンスかもしれないし、ウェブアプリケーションにアクセスするユーザーかもしれない。 どのエンティティも、 App Configuration と相互作用するためには、一意のエンティティIDを提供しなければならない。
  • entityAttributes: 指定されたエンティティーを定義する属性名とその値で構成される JSON オブジェクト。 ターゲット定義でプロパティーが構成されていない場合、これはオプション・パラメーターです。 ターゲットが構成されている場合は、ルール評価のために entityAttributes を指定する必要があります。 属性は、セグメントを定義するために使用されるパラメーターです。 SDK は、属性値を使用して、指定されたエンティティーがターゲティング・ルールを満たしているかどうかを判別し、適切なプロパティー値を返します。

ロギング

ロギング・レベルを「debug」|「info」|「warning」|「error」のいずれかに設定する。 デフォルトのログレベルは info です。

appConfigClient.setLogLevel('debug');

サポート対象データ・タイプ

App Configuration サービスでは、「ブール値」、「数値」、「文字列」の各データ・タイプで機能フラグとプロパティーを構成できます。 「文字列」データ・タイプは、テキスト文字列、JSON、YAML のフォーマットにできます。 SDKは各 SDKは各フォーマットを次の表のように処理します。

テーブルの表示
機能またはプロパティーの値 DataType DataFormat
getCurrentValue() によって返されるデータのタイプ
出力例
true BOOLEAN 適用外 boolean true
25 数値 適用外 number 25
「文字列テキスト」 STRING テキスト string a string text
{
"firefox": {
"name": "Firefox",
"pref_url": "about:config"
}
}
STRING JSON JSON object {"firefox":{"name":"Firefox","pref_url":"about:config"}}
men:
- John Smith
- Bill Jones
women:
- Mary Smith
- Susan Williams
STRING YAML string

`"men:

  • John Smith
  • Bill Jones
    women:
  • Mary Smith
  • Susan Williams"`
機能フラグの使用例
const feature = appConfigClient.getFeature('json-feature');
feature.getFeatureDataType(); // STRING
feature.getFeatureDataFormat(); // JSON

// Example (traversing the returned JSON)
let result = feature.getCurrentValue(entityId, entityAttributes);
console.log(result.key) // prints the value of the key

const feature = appConfigClient.getFeature('yaml-feature');
feature.getFeatureDataType(); // STRING
feature.getFeatureDataFormat(); // YAML
feature.getCurrentValue(entityId, entityAttributes); // returns the stringified yaml (check the table)
プロパティーの使用例
const property = appConfigClient.getProperty('json-property');
property.getPropertyDataType(); // STRING
property.getPropertyDataFormat(); // JSON

// Example (traversing the returned JSON)
let result = property.getCurrentValue(entityId, entityAttributes);
console.log(result.key) // prints the value of the key

const property = appConfigClient.getProperty('yaml-property');
property.getPropertyDataType(); // STRING
property.getPropertyDataFormat(); // YAML
property.getCurrentValue(entityId, entityAttributes); // returns the stringified yaml (check the table)

フィーチャーとプロパティのデータ変更のリスナーを設定する

SDKは、機能フラグやプロパティの設定が変更されたときにリアルタイムで通知するイベントベースのメカニズムを提供します。 同じappConfigClientて、「configurationUpdate イベントをリッスンできる。

appConfigClient.emitter.on('configurationUpdate', () => {
  // **add your code**
  // To find the effect of any configuration changes, you can call the feature or property related methods

  // feature = appConfigClient.getFeature('online-check-in');
  // newValue = feature.getCurrentValue(entityId, entityAttributes);
});

examplesフォルダにあるサンプル・ アプリケーション をお試しください。 フォルダにあるサンプル・アプリケーションを試してみてください。

ライセンス

このプロジェクトはApache 2.0ライセンスでリリースされています。 ライセンスの全文は でご覧いただけます