SDK de servidor de Configuración de apps para Java

El servicio App Configuration proporciona los SDK para que se integren con las aplicaciones, los microservicios y los entornos distribuidos.

Integración del SDK de servidor para Java

El servicio App Configuration proporciona el SDK para integrarse con las aplicaciones Java. Puede evaluar los valores del distintivo de característica integrando el SDK de App Configuration.

  1. Instale el SDK de una de las maneras siguientes.

    Utilización de Maven

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

    Obtenga el paquete a través de Gradle añadiendo:

    implementation group: 'com.ibm.cloud', name: 'appconfiguration-java-sdk', version: '0.3.3'
    
  2. En el microservicio o aplicación Java, incluya el SDK con:

    import com.ibm.cloud.appconfiguration.sdk.AppConfiguration;
    
  3. Inicialice el SDK para conectarse con la instancia de servicio de 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);
    

    Donde,

    • region: Nombre de la región donde se crea la instancia del servicio App Configuration. Consulte aquí la lista de lugares compatibles. Por ejemplo: us-south, au-syd, etc.
    • guid: GUID del servicio App Configuration. Obténgalo de la sección de credenciales de servicio del panel de control del servicio App Configuration.
    • apiKey: ApiKey del servicio App Configuration. Obténgalo de la sección de credenciales de servicio del panel de control del servicio App Configuration.
    • collectionId: ID de la colección creada en la instancia de servicio App Configuration en la sección Colecciones.
    • environmentId: Id del entorno creado en la instancia de servicio Configuración de apps en la sección Entornos.

init() y setContext() son las clases de inicialización y se deben invocar sólo una vez utilizando appConfigClient. El appConfigClient, una vez inicializado, puede obtenerse a través de las clases mediante AppConfiguration.getInstance(). Para obtener más información, consulte Fetching the appConfigClient a través de otras clases.

Utilización de puntos finales privados

Establezca el SDK para conectarse al servicio App Configuration utilizando un punto final privado al que solo se puede acceder a través de la red privada IBM Cloud.

appConfigClient.usePrivateEndpoint(true);

Esto debe hacerse antes de llamar a la función init en el SDK.

Opción para utilizar una memoria caché persistente para la configuración

Para que su aplicación y el SDK continúen funcionando durante el improbable escenario de una caída del servicio App Configuration, a través del reinicio de su aplicación, puede configurar el SDK para que funcione utilizando una caché persistente. El SDK utiliza la memoria caché persistente para almacenar los datos de App Configuration que están disponibles tras reinicios de la aplicación.

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

Donde:

  • persistentCacheDirectory: Ruta absoluta a un directorio que tiene permisos de lectura y escritura para el usuario. El SDK crea un archivo - appconfiguration.json en el directorio especificado, y se utiliza como caché persistente para almacenar la información del servicio App Configuration.

Cuando la caché persistente está activada, el SDK mantiene la última configuración buena conocida en la caché persistente. Si no se puede acceder al servidor App Configuration, se cargan las últimas configuraciones en la caché persistente para que la aplicación siga funcionando.

Asegúrese de que el archivo de memoria caché no se pierda ni se suprima en ningún caso. Por ejemplo, considere el caso cuando se reinicia un pod de kubernetes y el archivo de memoria caché (appconfiguration.json) se ha almacenado en un volumen efímero del pod. A medida que se reinicia el pod, kubernetes destruye el volumen efermal en el pod, como resultado se suprime el archivo de memoria caché. Por lo tanto, asegúrese de que el archivo de memoria caché creado por el SDK siempre se almacena en el volumen persistente proporcionando la vía de acceso absoluta correcta del directorio persistente.

Opciones fuera de línea

El SDK también está diseñado para servir configuraciones y realizar evaluaciones de propiedades y distintivos de características sin estar conectado al servicio App Configuration.

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

Donde:

  • bootstrapFile: Ruta absoluta del archivo JSON, que contiene detalles de configuración. Asegúrese de proporcionar un archivo JSON adecuado. Puede generar este archivo utilizando el mandato ibmcloud ac export de la CLI IBM Cloud App Configuration.
  • liveConfigUpdateEnabled: Actualización en directo de la configuración desde el servidor. Establezca este valor en false si los nuevos valores de configuración no deben obtenerse del servidor. Por defecto, este valor está fijado en true.

Ejemplos para utilizar las API relacionadas con características y propiedades

Consulte los siguientes ejemplos para utilizar las API relacionadas con características y propiedades.

Obtener una única característica

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

Obtener todas las características

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

Evaluación de características

Puede utilizar el método feature.getCurrentValue(entityId, entityAttributes) para evaluar el valor del distintivo de característica. Debe pasar un entityId exclusivo como parámetro para la evaluación del distintivo de característica. Si el distintivo de característica se configura con segmentos en el servicio App Configuration, puede establecer los valores de atributos como 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 de la entidad. Se trata de un identificador de serie relacionado con la entidad con la que se evalúa la característica. Por ejemplo, una entidad puede ser una instancia de una app que se ejecuta en un dispositivo móvil, un microservicio que se ejecuta en la nube o un componente de infraestructura que ejecuta dicho microservicio. Para que cualquier entidad interactúe con App Configuration, debe proporcionar un ID de entidad exclusivo.

  • entityAttributes: un objeto JSON que consta del nombre de atributo y sus valores que definen la entidad especificada. Este es un parámetro opcional si el distintivo de característica no está configurado con ninguna definición de destino. Si el destino está configurado, se debe proporcionar entityAttributes para la evaluación de regla. Un atributo es un parámetro que se utiliza para definir un segmento. El SDK utiliza los valores de atributo para determinar si la entidad especificada cumple las reglas de destino y devuelve el valor de distintivo de característica adecuado.

Obtener una única propiedad

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

Obtener todas las propiedades

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

Evaluación de propiedades

Puede utilizar el método property.getCurrentValue(entityId, entityAttributes) para evaluar el valor de la propiedad. Este método devuelve el valor de propiedad predeterminado o su valor alterado temporalmente basándose en la evaluación.

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 de la entidad. Se trata de un identificador de serie relacionado con la entidad con la que se evalúa la propiedad. Por ejemplo, una entidad puede ser una instancia de una app que se ejecuta en un dispositivo móvil, un microservicio que se ejecuta en la nube o un componente de infraestructura que ejecuta dicho microservicio. Para que cualquier entidad interactúe con App Configuration, debe proporcionar un ID de entidad exclusivo.

  • entityAttributes: un objeto JSON que consta del nombre de atributo y sus valores que definen la entidad especificada. Este es un parámetro opcional si la propiedad no está configurada con ninguna definición de destino. Si el destino está configurado, se debe proporcionar entityAttributes para la evaluación de regla. Un atributo es un parámetro que se utiliza para definir un segmento. El SDK utiliza los valores de atributo para determinar si la entidad especificada cumple las reglas de destino y devuelve el valor de propiedad adecuado.

Obtención de la appConfigClient a través de otras clases

Cuando se inicializa el SDK, el appConfigClient se puede obtener a través de otras clases como se muestra:

// **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 datos soportados

El servicio App Configuration le permite configurar distintivos y propiedades de características con los siguientes tipos de datos: Booleano, Numérico, Serie. El tipo de datos Serie puede tener el formato de una serie de texto, JSON o YAML. El SDK procesa cada formato como se muestra en la tabla 1.

Ejemplos de resultados
Valor de característica o propiedad Tipo de datos Formato de datos Tipo de datos devueltos por GetCurrentValue() Salida de ejemplo
true BOOLEAN no aplicable bool true
25 NUMERIC no aplicable float64 25
"un texto de serie" STRING TEXT 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"`

Distintivo de característica

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
}

Propiedad

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
}

Establecer escucha para los cambios de características o propiedades

El SDK proporciona un mecanismo para notificarle en tiempo real cuando cambia la configuración de una propiedad o un indicador de función. Puede suscribirse a los cambios de configuración utilizando la misma dirección 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);
   }
});

Captar datos más recientes

appConfigClient.fetchConfigurations();