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.
-
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' -
Dans votre microservice ou application Java, incluez le SDK avec :
import com.ibm.cloud.appconfiguration.sdk.AppConfiguration; -
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);Où
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-sydetc.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.apiKeyApiKey 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.environmentIdcorrespond à 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 commandeibmcloud ac exportde 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 surfalsesi 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é,entityAttributesdoit ê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é,entityAttributesdoit ê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.
| 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 Joneswomen:- Mary Smith- Susan Williams |
CHAINE | YAML | java.lang.String |
`"men:
|
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();