SDK du serveur App Configuration pour Java

Le service App Configuration fournit des SDK à intégrer à vos applications, microservices et environnements distribués.

Intégration du SDK du serveur pour Java

Le service App Configuration fournit un SDK à intégrer à vos applications Java. Vous pouvez évaluer les valeurs de votre indicateur de fonctionnalité en intégrant le SDK App Configuration.

  1. Installez le kit de développement de logiciels de l'une des manières suivantes.

    Utilisation de Maven

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

    Récupérez le package via Gradle en ajoutant :

    implementation group: 'com.ibm.cloud', name: 'appconfiguration-java-sdk', version: '0.3.3'
    
  2. Dans votre microservice ou application Java, incluez le SDK avec :

    import com.ibm.cloud.appconfiguration.sdk.AppConfiguration;
    
  3. Initialisez le SDK pour vous connecter à votre instance de service 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);
    

    • region: Nom de la région où l'instance de service App Configuration est créée. Voir la liste des lieux pris en charge ici. Par exemple : us-south, au-syd etc.
    • guid: GUID du service App Configuration. Obtenez-la à partir de la section des données d'identification du service du tableau de bord des services App Configuration.
    • apiKey ApiKey le service App Configuration est un service d'information et de conseil sur la santé et la sécurité au travail. Obtenez-la à partir de la section des données d'identification du service du tableau de bord des services App Configuration.
    • collectionId: ID de la collection créée dans l'instance de service App Configuration dans la section Collections.
    • environmentId correspond à l'ID de l'environnement créé dans l'instance de service App Configuration sous la section Environnements.

init() et setContext() sont les classes d'initialisation et doivent être appelées une seule fois à l'aide de appConfigClient. Le appConfigClient, une fois initialisé, peut être obtenu à travers les classes en utilisant AppConfiguration.getInstance(). Pour plus d'informations, voir La récupération du appConfigClient dans d'autres classes.

Utilisation de noeuds finaux privés

Définissez le SDK pour qu'il se connecte au service App Configuration en utilisant un noeud final privé accessible uniquement via le réseau privé IBM Cloud.

appConfigClient.usePrivateEndpoint(true);

Cette opération doit être effectuée avant d'appeler la fonction init sur le SDK.

Option permettant d'utiliser une mémoire cache persistante pour la configuration

Pour que votre application et votre SDK puissent continuer à fonctionner dans le cas improbable d'une interruption du service App Configuration, à travers le redémarrage de votre application, vous pouvez configurer le SDK de manière à ce qu'il utilise un cache persistant. Le kit de développement de logiciels utilise le cache persistant pour stocker les données App Configuration disponibles lors du redémarrage de votre application.

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

Où :

  • persistentCacheDirectory: Chemin absolu vers un répertoire pour lequel l'utilisateur dispose d'une autorisation de lecture et d'écriture. Le SDK crée un fichier - appconfiguration.json- dans le répertoire spécifié, et l'utilise comme cache persistant pour stocker les informations du service App Configuration.

Lorsque le cache persistant est activé, le SDK conserve la dernière bonne configuration connue dans le cache persistant. Si le serveur App Configuration est inaccessible, les dernières configurations du cache persistant sont chargées dans l'application pour qu'elle puisse continuer à fonctionner.

Vérifiez que le fichier cache n'est pas perdu ou supprimé dans tous les cas. Par exemple, prenez en compte le cas où un pod kubernetes est redémarré et que le fichier cache (appconfiguration.json) a été stocké dans un volume éphémère du pod. Lorsque le pod est redémarré, kubernetes détruit le volume ephermal dans le pod, ce qui entraîne la suppression du fichier cache. Par conséquent, assurez-vous que le fichier cache créé par le SDK est toujours stocké dans le volume persistant en fournissant le chemin absolu correct du répertoire persistant.

Options hors ligne

Le kit de développement de logiciels est également conçu pour servir des configurations et effectuer des évaluations de propriété et d'indicateur de fonction sans être connecté au service App Configuration.

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

Où :

  • bootstrapFile: Chemin absolu du fichier JSON, qui contient les détails de la configuration. Veillez à fournir un fichier JSON approprié. Vous pouvez générer ce fichier à l'aide de la commande ibmcloud ac export de l'interface de ligne de commande IBM Cloud App Configuration.
  • liveConfigUpdateEnabled: Mise à jour en direct de la configuration à partir du serveur. Définissez cette valeur sur false si les nouvelles valeurs de configuration ne doivent pas être récupérées sur le serveur. Par défaut, cette valeur est fixée à true.

Exemples d'utilisation d'API liées aux fonctionnalités et aux propriétés

Les exemples suivants illustrent l'utilisation des API relatives aux caractéristiques et aux propriétés.

Extraction d'une fonctionnalité

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

Extraction de toutes les fonctionnalités

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

Evaluation des fonctionnalités

Vous pouvez utiliser la méthode feature.getCurrentValue(entityId, entityAttributes) pour évaluer la valeur de l'indicateur de fonctionnalité. Vous devez transmettre un entityId unique en tant que paramètre pour l'évaluation de l'indicateur de fonction. Si cet indicateur est configuré avec des segments dans le service App Configuration, vous pouvez définir les valeurs des attributs sous forme d'objet JSON.

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 l'entité. Il s'agit d'un identificateur de chaîne lié à l'entité par rapport à laquelle la fonction est évaluée. Par exemple, une entité peut être une instance d'une application qui s'exécute sur un appareil mobile, un microservice qui s'exécute sur le cloud ou un composant d'infrastructure qui exécute ce microservice. Pour qu'une entité interagisse avec App Configuration, elle doit fournir un ID d'entité unique.

  • entityAttributes: objet JSON composé du nom d'attribut et de ses valeurs qui définissent l'entité spécifiée. Il s'agit d'un paramètre facultatif si l'indicateur de fonction n'est pas configuré avec une définition de ciblage. Si le ciblage est configuré, entityAttributes doit être fourni pour l'évaluation de la règle. Un attribut est un paramètre utilisé pour définir un segment. Le SDK utilise les valeurs d'attribut pour déterminer si l'entité spécifiée satisfait aux règles de ciblage et renvoie la valeur d'indicateur de fonction appropriée.

Extraction d'une propriété

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

Extraction de toutes les propriétés

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

Evaluation des propriétés

Vous pouvez utiliser la méthode property.getCurrentValue(entityId, entityAttributes) pour évaluer la valeur de la propriété. Cette méthode renvoie la valeur de propriété par défaut ou sa valeur remplacée en fonction de l'évaluation.

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 l'entité. Il s'agit d'un identificateur de chaîne lié à l'entité par rapport à laquelle la propriété est évaluée. Par exemple, une entité peut être une instance d'une application qui s'exécute sur un appareil mobile, un microservice qui s'exécute sur le cloud ou un composant d'infrastructure qui exécute ce microservice. Pour qu'une entité interagisse avec App Configuration, elle doit fournir un ID d'entité unique.

  • entityAttributes: objet JSON composé du nom d'attribut et de ses valeurs qui définissent l'entité spécifiée. Il s'agit d'un paramètre facultatif si la propriété n'est configurée avec aucune définition de ciblage. Si le ciblage est configuré, entityAttributes doit être fourni pour l'évaluation de la règle. Un attribut est un paramètre utilisé pour définir un segment. Le SDK utilise les valeurs d'attribut pour déterminer si l'entité spécifiée satisfait aux règles de ciblage et renvoie la valeur de propriété appropriée.

Récupérer le site appConfigClient dans d'autres classes

Lorsque le SDK est initialisé, le site appConfigClient peut être obtenu à travers d'autres classes comme indiqué :

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

Types de données pris en charge

Le service App Configuration vous permet de configurer des options et des indicateurs de fonction avec les types de données suivants : Booléen, Numérique, Chaîne. Le type de données Chaîne peut être le format d'une chaîne TEXT, JSON ou YAML. Le SDK traite chaque format comme indiqué dans le tableau 1.

Exemples de résultats
Valeur de la fonction ou de la propriété Type de données Format de données Type de données renvoyées par GetCurrentValue() Exemple de sortie
true BOOLEAN non applicable bool true
25 NUMERIC non applicable float64 25
"a string text" CHAINE TEXT string a string text
{"firefox": {
"name": "Firefox",
"pref_url": "about:config"
} }
CHAINE 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
CHAINE YAML java.lang.String

`"men:

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

Indicateur de fonction

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
}

Propriété

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
}

Définition d'un programme d'écoute des modifications apportées aux fonctionnalités ou aux propriétés

Le SDK fournit un mécanisme de notification en temps réel lorsque la configuration d'un indicateur ou d'une propriété change. Vous pouvez vous abonner aux changements de configuration en utilisant la même adresse 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);
   }
});

Extraire les données les plus récentes

appConfigClient.fetchConfigurations();