App Configuration 服务器 SDK for Python

App Configuration 服务提供 SDK 以与 Python 应用程序集成。

集成服务器 SDK for Python

App Configuration 服务提供 SDK 以与 Python 应用程序集成。您可以通过集成 App Configuration SDK 来评估功能部件标志或属性的值。

使用下列其中一种方法来安装 SDK:

使用 pip

pip install --upgrade ibm-appconfiguration-python-sdk

使用 easy_install

easy_install --upgrade ibm-appconfiguration-python-sdk

在 Python 应用程序代码中，包含具有以下内容的 SDK 模块:

from ibm_appconfiguration import AppConfiguration, Feature, Property, ConfigurationType

初始化 sdk 以与 App Configuration 服务实例连接。
```
appconfig_client = AppConfiguration.get_instance()
appconfig_client.init(region='region', guid='guid', apikey='apikey')
appconfig_client.set_context(collection_id='airlines-webapp', environment_id='dev')
```
其中：
- region:创建 App Configuration 服务实例的区域名称。点击此处查看支持的地点列表。例如：- us-south, au-syd 等。
- guid: App Configuration 服务的 GUID。从 App Configuration 服务仪表板的服务凭证部分获取此信息。
- apikey: App Configuration 服务的 ApiKey。从 App Configuration 服务仪表板的服务凭证部分获取此信息。
- collection_id: 在 App Configuration 服务实例中创建的集合的标识。
- environment_id: 在 App Configuration 服务实例中创建的环境的标识。
init() 和 set_context() 是初始化方法，应该使用 appconfig_client 仅调用一次。初始化时，可使用 AppConfiguration.get_instance() 跨模块获取 appconfig_client。有关更多信息，请参阅跨其他模块访存 appconfig_client。

使用专用端点

通过使用仅可通过 IBM Cloud 专用网络访问的专用端点，设置 SDK 以连接到 App Configuration 服务。

appconfig_client.use_private_endpoint(True);

必须先完成此操作，然后才能在 SDK 上调用 init 函数。

用于将持久高速缓存用于配置的选项

要使应用程序和 SDK 继续操作，即使在 App Configuration 服务停机的不太可能的场景中，在应用程序重新启动期间，您也可以将 SDK 配置为使用持久高速缓存来工作。 SDK 使用持久高速缓存来存储在应用程序重新启动期间可用的 App Configuration 数据。

# 1. default (without persistent cache)
appconfig_client.set_context(collection_id='airlines-webapp', environment_id='dev')

# 2. optional (with persistent cache)
appconfig_client.set_context(collection_id='airlines-webapp', environment_id='dev', options={
   'persistent_cache_dir': '/var/lib/docker/volumes/'
})

其中：

persistent_cache_dir: 用户具有读写许可权的目录的绝对路径。 SDK 在指定目录中创建文件 appconfiguration.json，并将其用作持久高速缓存以存储 App Configuration 服务信息。

启用持久高速缓存时，SDK 会在持久高速缓存中保留最后已知的良好配置。如果无法访问 App Configuration 服务器，那么会将持久高速缓存中的最新配置装入到应用程序以继续工作。

确保在给定目录中创建的高速缓存文件在任何情况下都不会丢失或删除。例如，请考虑重新启动 Kubernetes pod 并且高速缓存文件 (appconfiguration.json) 存储在 pod 的临时卷中的情况。当 pod 重新启动时，kubernetes 会破坏 pod 中的 ephermal 卷，从而删除高速缓存文件。因此，通过提供持久目录的正确绝对路径，确保 SDK 创建的高速缓存文件始终存储在持久卷中。

脱机选项

SDK 还设计为提供配置，并在不连接到 App Configuration 服务的情况下执行功能标志和属性评估。

appconfig_client.set_context(collection_id='collection_id', environment_id='environment_id', options={
  'bootstrap_file': 'saflights/flights.json',
  'live_config_update_enabled': False
})

其中：

bootstrap_file: JSON 文件的绝对路径，其中包含配置详细信息。请确保提供正确的 JSON 文件。您可以使用 IBM Cloud App Configuration CLI 的 ibmcloud ac export 命令生成此文件。
live_config_update_enabled: 从服务器进行实时配置更新。如果不能从服务器访存新配置值，请将此值设置为 False。默认情况下，该值设置为 True。

使用与功能部件和属性相关的 API 的示例

请参阅列出的示例，以了解如何使用与功能部件和属性相关的 API。

获取单一功能

feature = appconfig_client.get_feature('online-check-in')  # feature can be None incase of an invalid feature id

if feature is not None:
   print(f'Feature Name : {0}'.format(feature.get_feature_name()))
   print(f'Feature Id : {0}'.format(feature.get_feature_id()))
   print(f'Feature Data Type : {0}'.format(feature.get_feature_data_type()))
   if feature.is_enabled():
      # feature flag is enabled
   else:
      # feature flag is disabled

获取所有功能

features_dictionary = appconfig_client.get_features()

功能评估

您可以使用 feature.get_current_value(entity_id, entity_attributes) 方法来评估功能标志的值。此方法根据评估返回“已启用”，“已禁用”或“已覆盖”值之一。返回值的数据类型与特征标志的数据类型相匹配。

entity_id = "john_doe"
entity_attributes = {
   'city': 'Bangalore',
   'country': 'India'
}
feature_value = feature.get_current_value(entity_id=entity_id, entity_attributes=entity_attributes)

entity_id: 实体的标识。这是与对功能进行求值的实体相关的字符串标识。例如，实体可能是在移动设备上运行的应用程序实例，在云上运行的微服务或运行该微服务的基础结构组件。对于要与 App Configuration进行交互的任何实体，它必须提供唯一的实体标识。
entity_attributes: 由属性名称及其定义指定实体的值组成的 JSON 对象。如果未使用任何目标定义配置功能标志，那么这是可选参数。如果配置了目标，那么应该为规则评估提供 entity_attributes。属性是用于定义段的参数。 SDK 使用属性值来确定指定的实体是否满足目标规则，并返回相应的功能标志值。

获取单个属性

property = appconfig_client.get_property('check-in-charges')  # property can be None incase of an invalid property id
if property is not None:
   print(f'Property Name : {0}'.format(property.get_property_name()))
   print(f'Property Id : {0}'.format(property.get_property_id()))
   print(f'Property Data Type : {0}'.format(property.get_property_data_type()))

获取所有属性

properties_dictionary = appconfig_client.get_properties()

属性评估

您可以使用 property.get_current_value(entity_id=entity_id, entity_attributes=entity_attributes) 方法来评估属性的值。此方法根据求值返回缺省属性值或其覆盖值。返回值的数据类型与属性的数据类型相匹配。

entity_id = "john_doe"
entity_attributes = {
   'city': 'Bangalore',
   'country': 'India'
}
property_value = property.get_current_value(entity_id=entity_id, entity_attributes=entity_attributes)

entity_id: 实体的标识。这是与针对其对属性求值的实体相关的字符串标识。例如，实体可能是在移动设备上运行的应用程序实例，在云上运行的微服务或运行该微服务的基础结构组件。对于要与 App Configuration进行交互的任何实体，它必须提供唯一的实体标识。
entity_attributes: 由属性名称及其定义指定实体的值组成的 JSON 对象。如果属性未配置任何目标定义，那么这是可选参数。如果配置了目标，那么应该为规则评估提供 entity_attributes。属性是用于定义段的参数。 SDK 使用属性值来确定指定的实体是否满足目标规则，并返回相应的属性值。

跨其他模块访存 appconfig_client

初始化 SDK 时，可以跨其他模块获取 appconfig_client，如下所示:

# **other modules**

from ibm_appconfiguration import AppConfiguration

appconfig_client = AppConfiguration.get_instance()
feature = appconfig_client.get_feature('online-check-in')
enabled = feature.is_enabled()
feature_value = feature.get_current_value(entity_id, entity_attributes)

支持的数据类型

您可以使用 App Configuration 服务配置功能部件标志和属性，支持以下数据类型 :Boolean，Numeric 和 String。字符串数据类型的格式可以是 TEXT 字符串，JSON 或 YAML。 SDK 将处理表中显示的每种格式。

输出示例
功能部件或属性值	数据类型	数据格式	`GetCurrentValue()` 返回的数据类型	示例输出
`true`	BOOLEAN	不适用	`bool`	`true`
`25`	NUMERIC	不适用	`int`	`25`
"a string text"	STRING	TEXT	`string`	`a string text`
`{"firefox": {` `"name": "Firefox",` `"pref_url": "about:config"` }}	字符串	JSON	`Dictionary or List of Dictionary`	`{'firefox': {'name': 'Firefox', 'pref_url': 'about:config'}}`
`men:` `- John Smith` `- Bill Jones` `women:` `- Mary Smith` `- Susan Williams`	STRING	YAML	`Dictionary`	`{'men': ['John Smith', 'Bill Jones'], 'women': ['Mary Smith', 'Susan Williams']}`

功能标志

feature = appconfig_client.get_feature('json-feature')
feature.get_feature_data_type() // STRING
feature.get_feature_data_format() // JSON
feature.get_current_value(entityId, entityAttributes) // returns single dictionary object or list of dictionary object

// Example Below
// input json :- [{"role": "developer", "description": "do coding"},{"role": "tester", "description": "do testing"}]
// expected output :- "do coding"

tar_val = feature.get_current_value(entityId, entityAttributes)
expected_output = tar_val[0]['description']

// input json :- {"role": "tester", "description": "do testing"}
// expected output :- "tester"

tar_val = feature.get_current_value(entityId, entityAttributes)
expected_output = tar_val['role']

feature = appconfig_client.getFeature('yaml-feature')
feature.get_feature_data_type() // STRING
feature.get_feature_data_format() // YAML
feature.get_current_value(entityId, entityAttributes) // returns dictionary object

// Example Below
// input yaml string :- "---\nrole: tester\ndescription: do_testing"
// expected output :- "do_testing"

tar_val = feature.get_current_value(entityId, entityAttributes)
expected_output = tar_val['description']

属性

property = appconfig_client.get_property('json-property')
property.get_property_data_type() // STRING
property.get_property_data_format() // JSON
property.get_current_value(entityId, entityAttributes) // returns single dictionary object or list of dictionary object

// Example Below
// input json :- [{"role": "developer", "description": "do coding"},{"role": "tester", "description": "do testing"}]
// expected output :- "do coding"

tar_val = property.get_current_value(entityId, entityAttributes)
expected_output = tar_val[0]['description']

// input json :- {"role": "tester", "description": "do testing"}
// expected output :- "tester"

tar_val = property.get_current_value(entityId, entityAttributes)
expected_output = tar_val['role']

property = appconfig_client.get_property('yaml-property')
property.get_property_data_type() // STRING
property.get_property_data_format() // YAML
property.get_current_value(entityId, entityAttributes) // returns dictionary object

// Example Below
// input yaml string :- "---\nrole: tester\ndescription: do_testing"
// expected output :- "do_testing"

tar_val = property.get_current_value(entityId, entityAttributes)
expected_output = tar_val['description']

设置功能部件和属性数据更改的侦听器

SDK 提供了在功能部件标志“或属性”配置发生更改时实时通知您的机制。您可以使用相同的 appconfig_client 来预订配置更改。

def configuration_update(self):
   print('Received updates on configurations')
   # **add your code**
   # To find the effect of any configuration changes, you can call the feature or property related methods

   # feature = appconfig_client.getFeature('online-check-in')
   # new_value = feature.get_current_value(entity_id, entity_attributes)

appconfig_client.register_configuration_update_listener(configuration_update)

访存最新数据

appconfig_client.fetch_configurations()