SDK do servidor App Configuration para Python

O serviço App Configuration fornece SDK para integrar com o seu aplicativo Python.

Integrando o SDK do servidor para Python

O serviço App Configuration fornece SDK para integrar com o seu aplicativo Python. É possível avaliar os valores de sua sinalização de recurso ou propriedade integrando o SDK do App Configuration.

  1. Use qualquer um dos métodos a seguir para instalar o SDK:

    Usando pip

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

    Usando easy_install

    easy_install --upgrade ibm-appconfiguration-python-sdk

  2. Em seu código do aplicativo Python, inclua o módulo SDK com:

    from ibm_appconfiguration import AppConfiguration, Feature, Property, ConfigurationType

  3. Inicialize o SDK para se conectar à sua instância de serviço do 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')

    Em que:

    • region: Nome da região em que a instância do serviço App Configuration é criada. Veja a lista de locais com suporte aqui. Por exemplo: - us-south, au-syd etc.
    • guid: GUID do serviço App Configuration. Obtenha-a a partir da seção de credenciais de serviço do painel de serviços do App Configuration.
    • apikey: ApiKey do serviço App Configuration. Obtenha-a a partir da seção de credenciais de serviço do painel de serviços do App Configuration.
    • collection_id: ID da coleção criada na instância de serviço App Configuration.
    • environment_id: ID do ambiente criado na instância de serviço App Configuration.

    O init() e set_context() são os métodos de inicialização e devem ser chamados apenas uma vez usando appconfig_client. O appconfig_client, quando inicializado, pode ser obtido entre os módulos usando AppConfiguration.get_instance(). Para obter mais informações, consulte Buscando o appconfig_client através de outros módulos.

Usando terminais privados

Configure o SDK para se conectar ao serviço App Configuration usando um terminal privado que é acessível somente através da rede privada IBM Cloud.

appconfig_client.use_private_endpoint(True);

Isso deve ser feito antes de ligar para a função init no SDK.

Opção para usar um cache persistente para configuração

Para que seu aplicativo e o SDK continuem operando mesmo durante o cenário improvável de um tempo de inatividade do serviço App Configuration, ao reiniciar o aplicativo, você pode configurar o SDK para funcionar usando um cache persistente. O SDK usa o cache persistente para armazenar dados do App Configuration que estão disponíveis nas reinicializações do seu aplicativo.

# 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/'
})

Em que:

  • persistent_cache_dir: Caminho absoluto para um diretório que tenha permissão de leitura e gravação para o usuário. O SDK cria um arquivo - appconfiguration.json no diretório especificado, que é usado como cache persistente para armazenar as informações do serviço App Configuration.

    Quando o cache persistente está ativado, o SDK mantém a última configuração válida conhecida no cache persistente. Se o servidor App Configuration não puder ser acessado, as configurações mais recentes no cache persistente serão carregadas para que o aplicativo continue funcionando.

Certifica-se de que o arquivo de cache criado no diretório determinado não seja perdido ou excluído em qualquer caso. Por exemplo, considere o caso quando um pod de kubernetes é reiniciado e o arquivo de cache (appconfiguration.json) foi armazenado em volume efêmero do pod. Como pod fica reiniciado, kubernetes destrói o volume efermal no pod, como resultado o arquivo de cache é excluído. Então, certifica-se de que o arquivo de cache criado pelo SDK esteja sempre armazenado em volume persistente, fornecendo o caminho absoluto correto do diretório persistente.

Opções off-line

O SDK também é projetado para atender às configurações, além de executar sinalizador de recurso e as avaliações de propriedade sem estar conectado ao serviço 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
})

Em que:

  • bootstrap_file: Caminho absoluto do arquivo JSON, que contém detalhes de configuração. Certifique-se de fornecer um arquivo JSON adequado. Você pode gerar esse arquivo usando o comando ibmcloud ac export da CLI IBM Cloud App Configuration.
  • live_config_update_enabled: Atualização da configuração em tempo real a partir do servidor. Defina esse valor como False se os novos valores de configuração não precisarem ser obtidos do servidor. Por padrão esse valor é configurado como True.

Exemplos para uso de APIs relacionadas a recurso e propriedade

Consulte os exemplos listados para utilização das APIs relacionadas a propriedade e recurso.

Obter recurso único

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

Obter todos os recursos

features_dictionary = appconfig_client.get_features()

Avaliação do recurso

Você pode usar o método feature.get_current_value(entity_id, entity_attributes) para avaliar o valor do sinalizador de recurso. Este método retorna um do valor Enabled ou Desativado ou Overridden com base na avaliação. O tipo de dado de valor retornado corresponde ao de sinalizador de recurso.

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: Id da entidade. Trata-se de um identificador de cadeia relacionado à entidade contra a qual o recurso é avaliado. Por exemplo, uma entidade pode ser uma instância de um app que é executada em um dispositivo móvel, um microsserviço que é executado na nuvem ou um componente de infraestrutura que executa esse microsserviço. Para que qualquer entidade interaja com o App Configuration, ela deve fornecer um ID de entidade exclusivo.

  • entity_attributes: Um objeto JSON que consiste no nome do atributo e seus valores que definem a entidade especificada. Este é um parâmetro opcional se o flag do recurso não estiver configurado com nenhuma definição de direcionamento. Se o direcionamento estiver configurado, então entity_attributes deverá ser fornecido para a avaliação de regra. Um atributo é um parâmetro que é usado para definir um segmento. O SDK usa os valores de atributo para determinar se a entidade especificada satisfaz as regras de destinação, e retorna o valor de sinalizador de recurso apropriado.

Obter propriedade única

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

Obter todas as propriedades

properties_dictionary = appconfig_client.get_properties()

Avaliação de propriedade

Você pode usar o método property.get_current_value(entity_id=entity_id, entity_attributes=entity_attributes) para avaliar o valor da propriedade. Este método retorna o valor da propriedade padrão ou seu valor substituído baseado na avaliação. O tipo de dado de valor retornado corresponde ao da propriedade.

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: Id da entidade. Trata-se de um identificador de cadeia relacionado à entidade contra a qual a propriedade é avaliada. Por exemplo, uma entidade pode ser uma instância de um app que é executada em um dispositivo móvel, um microsserviço que é executado na nuvem ou um componente de infraestrutura que executa esse microsserviço. Para que qualquer entidade interaja com o App Configuration, ela deve fornecer um ID de entidade exclusivo.

  • entity_attributes: Um objeto JSON que consiste no nome do atributo e seus valores que definem a entidade especificada. Este é um parâmetro opcional se a propriedade não estiver configurada com nenhuma definição de direcionamento. Se o direcionamento estiver configurado, então entity_attributes deverá ser fornecido para a avaliação de regra. Um atributo é um parâmetro que é usado para definir um segmento. O SDK usa os valores de atributo para determinar se a entidade especificada satisfaz as regras de destinação, e retorna o valor de propriedade apropriado.

Buscando o appconfig_client em outros módulos

Quando o SDK é inicializado, o appconfig_client pode ser obtido em outros módulos, conforme mostrado:

# **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)

Tipos de dados suportados

É possível configurar sinalizadores de recursos e propriedades com o serviço App Configuration, suportando os seguintes tipos de dados: Booleano, Numérico e Sequência. O tipo de dados de sequência pode estar no formato de uma sequência de texto, JSON ou YAML. O SDK processa cada formato como mostrado na tabela.

Exemplo de saídas
Recurso ou Valor da Propriedade Tipo de dados Formato de dados Tipo de dados retornados por GetCurrentValue() Saída de exemplo
true BOOLEAN Não aplicável bool true
25 NUMÉRICO Não aplicável int 25
"um texto string" STRING TEXTO string a string text
{"firefox": {
"name": "Firefox",
"pref_url": "about:config"
}} 		STRING 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']}

Sinalizador do recurso

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']

Propriedade

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']

Configurar o listener para as mudanças de dados de recurso e de propriedade

O SDK fornece um mecanismo para notificá-lo em tempo real quando a configuração dos sinalizadores de recursos ou das propriedades for alterada. Você pode se inscrever nas alterações de configuração usando o mesmo 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)

Buscar dados mais recentes

appconfig_client.fetch_configurations()