SDK do servidor App Configuration para Java

O serviço App Configuration fornece SDKs para a integração com seus aplicativos, microsserviços e ambientes distribuídos.

Integrando o SDK do servidor para Java

O serviço App Configuration fornece SDK para a integração com seus aplicativos Java. É possível avaliar os valores de seu sinalizador de recurso integrando o SDK do App Configuration.

  1. Instale o SDK de uma das formas a seguir.

    Usando Maven

    <dependency>
       <groupId>com.ibm.cloud</groupId>
       <artifactId>appconfiguration-java-sdk</artifactId>
       <version>0.3.3</version>
    </dependency>
    

    Obtenha o pacote por meio de Gradle incluindo:

    implementation group: 'com.ibm.cloud', name: 'appconfiguration-java-sdk', version: '0.3.3'
    
  2. Em seu microsserviço ou aplicativo Java, inclua o SDK com:

    import com.ibm.cloud.appconfiguration.sdk.AppConfiguration;
    
  3. Inicialize o SDK para se conectar à sua instância de serviço do App Configuration.

    String region = AppConfiguration.REGION_US_SOUTH;
    String guid = "guid";
    String apikey = "apikey";
    
    String collectionId = "airlines-webapp";
    String environmentId = "dev";
    
    AppConfiguration appConfigClient = AppConfiguration.getInstance();
    appConfigClient.init(region, guid, apikey);
    appConfigClient.setContext(collectionId, environmentId);
    

    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-o por meio da seção de credenciais de serviço do painel de serviço do App Configuration.
    • apiKey: ApiKey do serviço App Configuration. Obtenha-o por meio da seção de credenciais de serviço do painel de serviço do App Configuration.
    • collectionId: ID da coleção criada na instância de serviço App Configuration na seção Collections (Coleções).
    • environmentId: ID do ambiente criado na instância de serviço do App Configuration sob a seção Ambientes.

Os init() e setContext() são as classes de inicialização e devem ser chamadas apenas uma vez usando appConfigClient. O appConfigClient, quando inicializado, pode ser obtido em todas as classes usando AppConfiguration.getInstance(). Para obter mais informações, consulte Buscando o appConfigClient em outras classes.

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.

appConfigClient.usePrivateEndpoint(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 durante o cenário improvável de um tempo de inatividade do serviço App Configuration, ao longo da reinicialização do 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)
    appConfigClient.setContext(collectionId, environmentId);

// 2. optional (with persistent cache)
    ConfigurationOptions configOptions = new ConfigurationOptions();
    configOptions.setPersistentCacheDirectory("/var/lib/docker/volumes/");
    appConfigClient.setContext(collectionId, environmentId, configOptions);

Em que:

  • persistentCacheDirectory: 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 não esteja 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.

ConfigurationOptions configOptions = new ConfigurationOptions();
configOptions.setBootstrapFile("saflights/flights.json");
configOptions.setLiveConfigUpdateEnabled(false);
appConfigClient.setContext(collectionId, environmentId, configOptions);

Em que:

  • bootstrapFile: Caminho absoluto do arquivo JSON, que contém detalhes de configuração. Certifique-se de fornecer um arquivo JSON adequado. Você pode gerar este arquivo usando o comando ibmcloud ac export do comando IBM Cloud App Configuration CLI.
  • liveConfigUpdateEnabled: 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 é definido como true.

Exemplos para uso de APIs relacionadas ao recurso e à propriedade

Veja os exemplos a seguir para usar as APIs relacionadas a recursos e propriedades.

Obter recurso único

Feature feature = appConfigClient.getFeature("online-check-in");

if (feature != null) {
    System.out.println("Feature Name : " + feature.getFeatureName());
    System.out.println("Feature Id : " + feature.getFeatureId());
    System.out.println("Feature Type : " + feature.getFeatureDataType());
    System.out.println("Is feature enabled? : " + feature.isEnabled());
}

Obter todos os recursos

HashMap<String, Feature> features = appConfigClient.getFeatures();

Avaliação do recurso

É possível usar o método feature.getCurrentValue(entityId, entityAttributes) para avaliar o valor da sinalização do recurso. Deve-se passar um entityId exclusivo como o parâmetro para a avaliação do sinalizador de recurso. Se a sinalização de recurso estiver configurada com os segmentos no serviço App Configuration, será possível configurar os valores de atributo como um JSONObject.

String entityId = "john_doe";
JSONObject entityAttributes = new JSONObject();
entityAttributes.put("city", "Bangalore");
entityAttributes.put("country", "India");

String value = (String) feature.getCurrentValue(entityId, entityAttributes);
  • entityId: 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.

  • entityAttributes: 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 entityAttributes 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 property = appConfigClient.getProperty("check-in-charges");

if (property != null) {
    System.out.println("Property Name : " + property.getPropertyName());
    System.out.println("Property Id : " + property.getPropertyId());
    System.out.println("Property Type : " + property.getPropertyDataType());
}

Obter todas as propriedades

HashMap<String, Property> property = appConfigClient.getProperties();

Avaliação de propriedade

É possível usar o método property.getCurrentValue(entityId, entityAttributes) 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.

String entityId = "john_doe";
JSONObject entityAttributes = new JSONObject();
entityAttributes.put("city", "Bangalore");
entityAttributes.put("country", "India");

String value = (String) property.getCurrentValue(entityId, entityAttributes);
  • entityId: 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.

  • entityAttributes: 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 entityAttributes 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 appConfigClient em outras classes

Quando o SDK é inicializado, o appConfigClient pode ser obtido em outras classes, conforme mostrado:

// **other classes**

import com.ibm.cloud.appconfiguration.sdk.AppConfiguration;
AppConfiguration appConfigClient = AppConfiguration.getInstance();

Feature feature = appConfigClient.getFeature("string-feature");
boolean enabled = feature.isEnabled();
String featureValue = (String) feature.getCurrentValue(entityId, entityAttributes);

Tipos de dados suportados

O serviço App Configuration permite configurar sinalizadores e propriedades de recursos com os tipos de dados a seguir: Booleano, Numérico, 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 formato, conforme mostrado na tabela 1.

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 float64 25
"um texto string" STRING TEXTO string a string text
{"firefox": {
"name": "Firefox",
"pref_url": "about:config"
}}
STRING JSON map[string]interface{} map[browsers:map[firefox:map[name:Firefox pref_url:about:config]]]
men:
- John Smith
- Bill Jones
women:
- Mary Smith
- Susan Williams
STRING YAML java.lang.String

`"men:

  • John Smith
  • Bill Jones\women:
  • Mary Smith
  • Susan Williams"`

Sinalizador do recurso

Feature feature = appConfigClient.getFeature("json-feature");
if (feature != null) {
   feature.getFeatureDataType();       // STRING
   feature.getFeatureDataFormat();     // JSON
   feature.getCurrentValue(entityId, entityAttributes); // JSONObject or JSONArray is returned
}

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

JSONArray tar_val = (JSONArray) feature.get_current_value(entityId, entityAttributes);
String expected_output = (String) ((JSONObject) tar_val.get(0)).get('description');

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

JSONObject tar_val = (JSONObject) feature.get_current_value(entityId, entityAttributes);
String expected_output = (String) tar_val.get('role');

Feature feature = appConfigClient.getFeature("yaml-feature");
if (feature != null) {
   feature.getFeatureDataType();       // STRING
   feature.getFeatureDataFormat();     // YAML
   feature.getCurrentValue(entityId, entityAttributes); // Yaml String is returned
}

Propriedade

Property property = appConfigClient.getProperty("json-property");
if (property != null) {
   property.getPropertyDataType();     // STRING
   property.getPropertyDataFormat();   // JSON
   property.getCurrentValue(entityId, entityAttributes); // JSONObject or JSONArray is returned
}

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

JSONArray tar_val = (JSONArray) property.get_current_value(entityId, entityAttributes);
String expected_output = (String) ((JSONObject) tar_val.get(0)).get('description');

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

JSONObject tar_val = (JSONObject) property.get_current_value(entityId, entityAttributes);
String expected_output = (String) tar_val.get('role');

Property property = appConfigClient.getProperty("yaml-property");
if (property != null) {
   property.getPropertyDataType();     // STRING
   property.getPropertyDataFormat();   // YAML
   property.getCurrentValue(entityId, entityAttributes); // Yaml String is returned
}

Configurar listener para mudanças no recurso ou na propriedade

O SDK fornece um mecanismo para notificá-lo em tempo real quando a configuração do sinalizador de recurso ou da propriedade for alterada. Você pode assinar as alterações de configuração usando o mesmo endereço appConfigClient.

appConfigClient.registerConfigurationUpdateListener(new ConfigurationUpdateListener() {
   @Override
   public void onConfigurationUpdate() {
      System.out.println("Received updated configurations");
      // **add your code**
      // To find the effect of any configuration changes, you can call the feature or property related methods

      // Feature feature = appConfigClient.getFeature("numeric-feature");
      // Integer newValue = (Integer) feature.getCurrentValue(entityId, entityAttributes);
   }
});

Buscar dados mais recentes

appConfigClient.fetchConfigurations();