IBM Cloud Docs
App Configuration JavaScript 客户机 SDK

App Configuration JavaScript 客户机 SDK

为提高使用 "ibm-appconfiguration-js-client-sdk 的应用程序的安全性,强烈建议在 init 方法中使用加密 APIKey,而不是普通 APIKey。 这一更改对于防止用户在检查网络应用程序时暴露敏感凭据至关重要。 如果您已经在使用普通 APIKey,请更新您的应用程序,按照 此处 提到的步骤生成和使用加密 APIKey。

概述

IBM Cloud App Configuration JavaScriptClient SDK 用于在网络应用程序中执行功能标志和属性评估,并根据IBM Cloud上的配置跟踪用于实验的自定义指标。App Configuration服务。

IBM Cloud App Configuration是集中式功能管理和配置服务 IBM Cloud 上的集中式功能管理和配置服务,适用于网络和移动应用程序、微服务以及分布式环境。 环境中使用。

使用App Configuration对网络应用程序进行仪表化。JavaScriptClient SDK,并使用App Configuration仪表板、CLI 或 API 来定义功能标志或属性,将其组织成集合并定向到细分市场。 在云中切换功能标志状态 在云中切换功能标志状态,以便在需要时激活或停用应用程序或环境中的功能。 运行实验,并通过跟踪自定义指标来衡量功能标志对最终用户的影响。 您还可以集中管理分布式应用程序的属性。

浏览器兼容性:所有主流浏览器都支持 SDK。 浏览器应支持 "fetch() 应用程序接口。

集成客户机 SDK for JavaScript

安装植入

安装 SDK。 使用以下代码从软件包管理器安装模块。

npm install ibm-appconfiguration-js-client-sdk

您可以通过从后台托管网站或 CDN 引用 SDK,将其导入脚本标签,具体方法如下:

示例:

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

初始化 SDK

初始化 sdk 以与 App Configuration 服务实例连接。

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

其中,

  • 区域:创建 App Configuration 服务实例的区域名称。 点击此处 查看支持的地点列表。 例如:- us-south, au-syd 等。
  • 指南:"App Configuration服务的实例 ID。 从App Configuration面板的服务凭据部分获取。
  • apikey: 如上所述生成的加密 APIKey '这里.
  • collectionId:在“集”部分下的App Configuration服务实例中创建的集合的 ID。
  • 环境标识:在“环境部分下的”App Configuration服务实例中创建的环境 ID。

请始终使用加密的 APIKey,以避免暴露敏感信息。
确保使用 "Client SDK 角色创建服务凭证,因为该角色具有适合在基于浏览器的应用程序中使用的最低访问权限。

使用与功能部件和属性相关的 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: 实体的标识。 这将是与对功能进行求值的实体相关的字符串标识。 例如,实体可以是移动设备上运行的应用程序实例,也可以是访问网络应用程序的用户。 对于要与 App Configuration交互的任何实体,它必须提供唯一的实体标识。
  • 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: 实体的标识。 这将是与对属性求值的实体相关的字符串标识。 例如,实体可以是移动设备上运行的应用程序实例,也可以是访问网络应用程序的用户。 对于要与 App Configuration交互的任何实体,它必须提供唯一的实体标识。
  • entityAttributes: 由属性名称及其用于定义指定实体的值组成的 JSON 对象。 如果属性未配置任何目标定义,那么这是可选参数。 如果配置了目标,那么应该为规则评估提供 entityAttributes。 属性是用于定义段的参数。 SDK 使用属性值来确定指定的实体是否满足目标规则,并返回相应的属性值。

日志记录

将日志记录级别设置为“调试”|“信息”|“警告”|“错误”。 默认日志级别为 info

appConfigClient.setLogLevel('debug');

支持的数据类型

App Configuration服务允许在以下数据类型中配置功能标志和属性:布尔 数字、字符串。 字符串数据类型可以是文本字符串、JSON 或 YAML 格式。 软件开发工具包(SDK)会 对每种格式进行处理,如下表所示。

查看表
功能或属性值 DataType DataFormat Type of data returned
by getCurrentValue()
示例输出
true BOOLEAN 不适用 boolean true
25 NUMERIC 不适用 number 25
“字符串文本” 字符串 文本 string a string text
{
"firefox":{
"name":Firefox",
"pref_url":"about:config"
}
}
字符串 JSON JSON object {"firefox":{"name":"Firefox","pref_url":"about:config"}}
男:
--约翰-史密斯
--比尔-琼斯
女:"
--玛丽-史密斯
--苏珊-威廉姆斯
字符串 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);
});

示例

尝试示例文件夹中的 " 示例应用程序,了解更多关于特征和属性评估的信息。 文件夹中的 "code1 "示例应用程序,了解有关特征和属性评估的更多信息。

许可证

本项目根据Apache 2.0许可发布。 许可证全文可在 许可证