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.
-
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' -
Em seu microsserviço ou aplicativo Java, inclua o SDK com:
import com.ibm.cloud.appconfiguration.sdk.AppConfiguration; -
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-sydetc.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.jsonno 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 comandoibmcloud ac exportdo comando IBM Cloud App Configuration CLI.liveConfigUpdateEnabled: Atualização da configuração em tempo real a partir do servidor. Defina esse valor comofalsese os novos valores de configuração não precisarem ser obtidos do servidor. Por padrão, esse valor é definido comotrue.
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ãoentityAttributesdeverá 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ãoentityAttributesdeverá 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.
| 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 Joneswomen:- Mary Smith- Susan Williams |
STRING | YAML | java.lang.String |
`"men:
|
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();