App Configuration server SDK per Java

Il servizio App Configuration fornisce gli SDK da integrare con le tue applicazioni, i tuoi microservizi e gli ambienti distribuiti.

Integrazione di SDK server per Java

Il servizio App Configuration fornisce l'SDK per l'integrazione con le tue applicazioni Java. Puoi valutare i valori del tuo indicatore della funzione integrando l'SDK App Configuration.

  1. Installare l'SDK in uno dei seguenti modi.

    Utilizzo di Maven

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

    Scarica il pacchetto tramite Gradle aggiungendo:

    implementation group: 'com.ibm.cloud', name: 'appconfiguration-java-sdk', version: '0.3.3'
    
  2. Nel tuo microservizio o applicazione Java, includi l'SDK con:

    import com.ibm.cloud.appconfiguration.sdk.AppConfiguration;
    
  3. Inizializza l'SDK per connetterti con la tua istanza del servizio 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);
    

    Dove,

    • region: Nome della regione in cui viene creata l'istanza del servizio App Configuration. Vedere l'elenco delle località supportate qui. Ad esempio: us-south, au-syd ecc.
    • guid: GUID del servizio App Configuration. Ottieni la sezione delle credenziali del servizio del dashboard del servizio App Configuration.
    • apiKey: ApiKey del servizio App Configuration. Ottieni la sezione delle credenziali del servizio del dashboard del servizio App Configuration.
    • collectionId: ID della raccolta creata nell'istanza del servizio App Configuration nella sezione Raccolte.
    • environmentId: ID dell'ambiente creato nell'istanza del servizio App Configuration nella sezione Ambienti.

init() e setContext() sono le classi di inizializzazione e devono essere richiamate una volta sola utilizzando appConfigClient. L'appConfigClient, una volta inizializzato, può essere ottenuto tra le classi usando AppConfiguration.getInstance(). Per ulteriori informazioni, vedere Raccolta del appConfigClient in altre classi.

Utilizzo degli endpoint privati

Imposta l'SDK per la connessione al servizio App Configuration utilizzando un endpoint privato accessibile solo tramite la rete privata IBM Cloud.

appConfigClient.usePrivateEndpoint(true);

Ciò deve essere fatto prima di richiamare la funzione init sull'SDK.

Opzione per utilizzare una cache persistente per la configurazione

Per la tua applicazione e l'SDK per continuare le operazioni durante lo scenario improbabile di un tempo di inattività del servizio App Configuration, tra i riavvii della tua applicazione, puoi configurare l'SDK per funzionare utilizzando una cache persistente. L'SDK utilizza la cache persistente per memorizzare i dati App Configuration disponibili durante i riavvii dell'applicazione.

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

Dove:

  • persistentCacheDirectory: percorso assoluto di una directory che dispone dell'autorizzazione di lettura e scrittura per l'utente. L'SDK crea un file - appconfiguration.json nella directory specificata e viene utilizzato come cache persistente per memorizzare informazioni sul servizio App Configuration.

Quando la cache persistente è abilitata, l'SDK conserva l'ultima configurazione valida nota nella cache persistente. Se il server App Configuration non è raggiungibile, le ultime configurazioni nella cache persistente vengono caricate nell'applicazione per continuare a funzionare.

Assicurarsi che il file della cache non venga perso o eliminato in alcun caso. Ad esempio, si consideri il caso in cui un pod kubernetes viene riavviato e il file di cache (appconfiguration.json) è stato memorizzato in un volume temporaneo del pod. Quando il pod viene riavviato, kubernetes distrugge il volume ephermal nel pod, di conseguenza il file della cache viene eliminato. Quindi, assicurati che il file di cache creato dall'SDK sia sempre memorizzato nel volume persistente fornendo il percorso assoluto corretto della directory persistente.

Opzioni offline

L'SDK è anche progettato per servire le configurazioni ed eseguire valutazioni di proprietà e indicatori di funzione senza essere connesso al servizio App Configuration.

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

Dove:

  • bootstrapFile: percorso assoluto del file JSON, che contiene dettagli di configurazione. Assicurarsi di fornire un corretto file JSON. Puoi creare questo file utilizzando il comando ibmcloud ac export della CLI IBM Cloud App Configuration.
  • liveConfigUpdateEnabled: Aggiornamento della configurazione dal server. Impostare questo valore su false se i nuovi valori di configurazione non devono essere recuperati dal server. Per impostazione predefinita, questo valore è impostato su true.

Esempi per l'uso di API correlate a funzioni e proprietà

Consultare i seguenti esempi per l'utilizzo delle API correlate alla funzione e alla proprietà.

Ottieni funzione singola

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

Ottieni tutte le funzioni

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

Valutazione funzione

È possibile utilizzare il metodo feature.getCurrentValue(entityId, entityAttributes) per valutare il valore dell'indicatore di funzione. È necessario passare un entityId univoco come parametro per la valutazione dell'indicatore di funzione. Se l'indicatore della funzione è configurato con i segmenti nel servizio App Configuration, puoi impostare i valori degli attributi come un 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 dell'entità. Si tratta di un identificativo stringa correlato all'entità rispetto alla quale viene valutata la funzione. Ad esempio, un'entità potrebbe essere un'istanza di un'applicazione che viene eseguita su un dispositivo mobile, un microservizio che viene eseguito sul Cloud o un componente dell'infrastruttura che esegue tale microservizio. Affinché qualsiasi entità interagisca con App Configuration, deve fornire un ID entità univoco.

  • entityAttributes: un oggetto JSON costituito dal nome dell'attributo e dai relativi valori che definiscono l'entità specificata. Questo è un parametro facoltativo se l'indicatore della funzione non è configurato con alcuna definizione di destinazione. Se la destinazione è configurata, entityAttributes deve essere fornito per la valutazione della regola. Un attributo è un parametro utilizzato per definire un segmento. L'SDK utilizza i valori degli attributi per stabilire se l'entità specificata soddisfa le regole di destinazione e restituisce il valore dell'indicatore della funzione appropriato.

Ottieni singola propriet ...

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

Ottieni tutte le proprietà

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

Valutazione proprietà

È possibile utilizzare il metodo property.getCurrentValue(entityId, entityAttributes) per valutare il valore della proprietà. Questo metodo restituisce il valore della proprietà predefinito o il relativo valore sovrascritto in base alla valutazione.

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 dell'entità. Si tratta di un identificativo stringa relativo all'entità rispetto alla quale viene valutata la proprietà. Ad esempio, un'entità potrebbe essere un'istanza di un'applicazione che viene eseguita su un dispositivo mobile, un microservizio che viene eseguito sul Cloud o un componente dell'infrastruttura che esegue tale microservizio. Affinché qualsiasi entità interagisca con App Configuration, deve fornire un ID entità univoco.

  • entityAttributes: un oggetto JSON costituito dal nome dell'attributo e dai relativi valori che definiscono l'entità specificata. Questo è un parametro facoltativo se la proprietà non è configurata con alcuna definizione di destinazione. Se la destinazione è configurata, entityAttributes deve essere fornito per la valutazione della regola. Un attributo è un parametro utilizzato per definire un segmento. L'SDK utilizza i valori degli attributi per stabilire se l'entità specificata soddisfa le regole di destinazione e restituisce il valore della proprietà appropriato.

Recupero di appConfigClient tra altre classi

Quando l'SDK viene inizializzato, l' appConfigClient può essere ottenuto attraverso altre classi come mostrato:

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

Tipi di dati supportati

Il servizio App Configuration ti permette di configurare gli indicatori e le proprietà della funzione con i seguenti tipi di dati: Boolean, Numeric, String. Il tipo di dati String può avere il formato di una stringa TEXT, JSON o YAML. L'SDK elabora ogni formato come mostrato nella tabella 1.

Esempi di uscite
Valore della funzione o della proprietà Tipo di dati Formato dati Tipo di dati restituiti da GetCurrentValue() Output di esempio
true BOOLEAN non applicabile bool true
25 NUMERIC non applicabile float64 25
"a string text" 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"`

Indicatore di funzione

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
}

Proprietà

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
}

Imposta listener per modifiche di funzioni o proprietà

L'SDK fornisce un meccanismo per notificare in tempo reale le modifiche di configurazione dell'indicatore della funzione o della proprietà. È possibile sottoscrivere le modifiche alla configurazione utilizzando lo stesso 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);
   }
});

Recupera i dati più recenti

appConfigClient.fetchConfigurations();