biblioteca cliente de Azure App Configuration para Java: versión 1.4.10

  • Artículo

Azure App Configuration es un servicio administrado que ayuda a los desarrolladores a centralizar la configuración de sus aplicaciones de forma sencilla y segura.

Los programas actuales, especialmente los que se ejecutan en una nube, tienen por lo general muchos componentes que están distribuidos por naturaleza. La propagación de valores de configuración entre estos componentes puede conducir a errores difíciles de solucionar durante la implementación de una aplicación. Use App Configuration para almacenar toda la configuración de la aplicación y proteger sus accesos en un solo lugar.

Use la biblioteca cliente para App Configuration para crear y administrar las opciones de configuración de la aplicación.

Código | fuentePaquete (Maven) | Documentación | de referencia de APIDocumentación | del productoMuestras

Introducción

Requisitos previos

Inclusión del paquete

Inclusión del archivo BOM

Incluya azure-sdk-bom en el proyecto para depender de la versión de disponibilidad general (GA) de la biblioteca. En el fragmento de código siguiente, reemplace el marcador de posición {bom_version_to_target} por el número de versión. Para más información sobre la lista de materiales, consulte EL ARCHIVO LÉAME BOM del SDK de AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

y, a continuación, incluya la dependencia directa en la sección dependencias sin la etiqueta de versión, como se muestra a continuación.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-data-appconfiguration</artifactId>
  </dependency>
</dependencies>

Inclusión de dependencias directas

Si quiere depender de una versión determinada de la biblioteca que no está presente en la lista de materiales, agregue la dependencia directa al proyecto como se indica a continuación.

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-data-appconfiguration</artifactId>
  <version>1.4.10</version>
</dependency>

Crear una tienda de App Configuration

Para crear un almacén de configuración, puede usar Azure Portal o la CLI de Azure.

Para instalar la extensión de la CLI de Azure App Configuration primero debe ejecutar el comando siguiente:

az extension add -n appconfig

Después, cree el almacén de configuración:

az appconfig create --name <config-store-name> --resource-group <resource-group-name> --location eastus

Autenticar el cliente

Para interactuar con el servicio App Configuration, deberá crear una instancia de la clase Configuration Client. Para que esto sea posible, necesitará el cadena de conexión del almacén de configuración. Como alternativa, use el token de AAD para conectarse al servicio.

Usar cadena de conexión

Obtener credenciales

Use el fragmento de código de la CLI de Azure siguiente para obtener el cadena de conexión del Almacén de configuración.

az appconfig credential list --name <config-store-name>

Como alternativa, obtenga el cadena de conexión de Azure Portal.

Creación de un cliente de configuración

Una vez que tenga el valor del cadena de conexión puede crear el cliente de configuración:

ConfigurationClient configurationClient = new ConfigurationClientBuilder()
    .connectionString(connectionString)
    .buildClient();

o

ConfigurationAsyncClient configurationClient = new ConfigurationClientBuilder()
    .connectionString(connectionString)
    .buildAsyncClient();

Uso del token de AAD

Aquí se muestra cómo usar DefaultAzureCredential para autenticarse como entidad de servicio. Sin embargo, el cliente de configuración acepta cualquier credencial de azure-identity . Consulte la documentación de azure-identity para más información sobre otras credenciales.

Creación de una entidad de servicio (opcional)

Este fragmento de código de la CLI de Azure muestra cómo crear una nueva entidad de servicio. Antes de usarlo, reemplace "your-application-name" por el nombre adecuado para la entidad de servicio.

Cree una entidad de servicio:

az ad sp create-for-rbac --name http://my-application --skip-assignment

Salida:

 {
     "appId": "generated app id",
     "displayName": "my-application",
     "name": "http://my-application",
     "password": "random password",
     "tenant": "tenant id"
 }

Use la salida para establecer AZURE_CLIENT_ID ("appId" anterior), AZURE_CLIENT_SECRET ("contraseña" anterior) y AZURE_TENANT_ID ("inquilino" anterior) variables de entorno. En el ejemplo siguiente se muestra una manera de hacerlo en Bash:

export AZURE_CLIENT_ID="generated app id"
export AZURE_CLIENT_SECRET="random password"
export AZURE_TENANT_ID="tenant id"

Asigne uno de los roles de App Configuration aplicables a la entidad de servicio.

Creación de un cliente

Una vez establecida la AZURE_CLIENT_ID, AZURE_CLIENT_SECRET y AZURE_TENANT_ID variables de entorno, DefaultAzureCredential podrá autenticar el cliente de configuración.

La construcción del cliente también requiere la dirección URL del almacén de configuración, que puede obtener desde la CLI de Azure o Azure Portal. En Azure Portal, la dirección URL se puede encontrar como el servicio "Punto de conexión".

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
ConfigurationClient configurationClient = new ConfigurationClientBuilder()
    .credential(credential)
    .endpoint(endpoint)
    .buildClient();

Conceptos clave

Opción de configuración

Un valor de configuración es el recurso fundamental dentro de un almacén de configuración. En su forma más sencilla, es una clave y un valor. Sin embargo, hay propiedades adicionales, como el tipo de contenido modificable y los campos de etiquetas que permiten interpretar o asociar el valor de maneras diferentes.

La propiedad Label de un valor de configuración proporciona una manera de separar las opciones de configuración en diferentes dimensiones. Estas dimensiones se definen por el usuario y pueden adoptar cualquier forma. Algunos ejemplos comunes de dimensiones que se usarán para una etiqueta incluyen regiones, versiones semánticas o entornos. Muchas aplicaciones tienen un conjunto necesario de claves de configuración que tienen valores diferentes, ya que la aplicación existe en diferentes dimensiones. Por ejemplo, MaxRequests puede ser 100 en "NorthAmerica" y 200 en "WestEurope". Al crear una configuración denominada MaxRequests con una etiqueta de "NorthAmerica" y otra, solo con un valor diferente, en la etiqueta "WestEurope", se puede lograr una solución que permita a la aplicación recuperar sin problemas los valores de configuración a medida que se ejecuta en estas dos dimensiones.

Cliente de configuración

El cliente realiza las interacciones con el servicio App Configuration, obtener, establecer, eliminar y seleccionar opciones de configuración. Existe un cliente asincrónico, ConfigurationAsyncClient, y sincrónico ConfigurationClienten el SDK, lo que permite la selección de un cliente en función del caso de uso de una aplicación.

Una aplicación que necesita recuperar configuraciones de inicio es más adecuada mediante el cliente sincrónico, por ejemplo, la configuración de una conexión SQL.

ConfigurationClient configurationClient = new ConfigurationClientBuilder()
    .connectionString(connectionString)
    .buildClient();

// urlLabel is optional
String url = configurationClient.getConfigurationSetting(urlKey, urlLabel).getValue();
Connection conn = null;
try {
    conn = DriverManager.getConnection(url);
} catch (SQLException ex) {
    System.out.printf("Failed to get connection using url %s", url);
} finally {
    if (conn != null) {
        try {
            conn.close();
        } catch (SQLException ex) {
            System.out.printf("Failed to close connection, url %s", url);
        }
    }
}

Una aplicación que tiene un gran conjunto de configuraciones que necesita actualizar periódicamente es más adecuada mediante el cliente asincrónico, por ejemplo, todas las configuraciones con una etiqueta específica se actualizan periódicamente.

ConfigurationAsyncClient configurationClient = new ConfigurationClientBuilder()
    .connectionString(connectionString)
    .buildAsyncClient();

configurationClient.listConfigurationSettings(new SettingSelector().setLabelFilter(periodicUpdateLabel))
    .subscribe(setting -> updateConfiguration(setting));

Ejemplos

En las secciones siguientes se proporcionan varios fragmentos de código que abarcan algunas de las tareas del servicio de configuración más comunes, como: Para la configuración de "Marca de características" y "Referencia secreta", consulte ejemplos para obtener más detalles.

Creación de un cliente de configuración

Cree un cliente de configuración mediante el paso ConfigurationClientBuilder de cadena de conexión.

ConfigurationClient configurationClient = new ConfigurationClientBuilder()
    .connectionString(connectionString)
    .buildClient();

Crear una configuración

Cree una configuración que se almacenará en el almacén de configuración. Hay dos maneras de almacenar una configuración:

  • addConfigurationSetting crea una configuración solo si la configuración aún no existe en el almacén.
ConfigurationSetting setting = configurationClient.addConfigurationSetting("new_key", "new_label", "new_value");

Or

  • setConfigurationSetting crea una configuración si no existe o invalida una configuración existente.
ConfigurationSetting setting = configurationClient.setConfigurationSetting("some_key", "some_label", "some_value");

Cree un valor de configuración de marca de característica o un valor de configuración de referencia de Secrete que se almacenará en el almacén de configuración.

String key = "some_key";
String filterName = "{filter_name}"; // such as "Microsoft.Percentage"
String filterParameterKey = "{filter_parameter_key}"; // "Value"
Object filterParameterValue = 30; // Any value. Could be String, primitive value, or Json Object
FeatureFlagFilter percentageFilter = new FeatureFlagFilter(filterName)
                                         .addParameter(filterParameterKey, filterParameterValue);
FeatureFlagConfigurationSetting featureFlagConfigurationSetting =
    new FeatureFlagConfigurationSetting(key, true)
        .setClientFilters(Arrays.asList(percentageFilter));

FeatureFlagConfigurationSetting setting = (FeatureFlagConfigurationSetting)
    configurationClient.addConfigurationSetting(featureFlagConfigurationSetting);

String key = "{some_key}";
String keyVaultReference = "{key_vault_reference}";

SecretReferenceConfigurationSetting referenceConfigurationSetting =
    new SecretReferenceConfigurationSetting(key, keyVaultReference);

SecretReferenceConfigurationSetting setting = (SecretReferenceConfigurationSetting)
    configurationClient.addConfigurationSetting(referenceConfigurationSetting);

Recuperar un valor de configuración

Recupere una configuración almacenada previamente llamando a getConfigurationSetting.

ConfigurationSetting setting = configurationClient.setConfigurationSetting("some_key", "some_label", "some_value");
ConfigurationSetting retrievedSetting = configurationClient.getConfigurationSetting("some_key", "some_label");

Para la solicitud condicional, si desea capturar condicionalmente una configuración, establezca en ifChanged true. Cuando ifChanged es true, la configuración solo se recupera si es diferente de la especificada setting. Esto se determina comparando la ETag de con la que setting se encuentra en el servicio para ver si son iguales o no. Si las etiquetas ETag no son iguales, significa que la configuración es diferente y su valor se recupera.

ConfigurationSetting setting = configurationClient.setConfigurationSetting("some_key", "some_label", "some_value");
Response<ConfigurationSetting> settingResponse = configurationClient.getConfigurationSettingWithResponse(setting, null, true, Context.NONE);

Recupere un valor de configuración marca de característica o un valor de configuración de referencia de Secrete en el almacén de configuración.

FeatureFlagConfigurationSetting setting = (FeatureFlagConfigurationSetting)
    configurationClient.getConfigurationSetting(featureFlagConfigurationSetting);

SecretReferenceConfigurationSetting setting = (SecretReferenceConfigurationSetting)
    configurationClient.getConfigurationSetting(referenceConfigurationSetting);

Actualizar una configuración existente

Actualice una configuración existente llamando a setConfigurationSetting.

ConfigurationSetting setting = configurationClient.setConfigurationSetting("some_key", "some_label", "some_value");
ConfigurationSetting updatedSetting = configurationClient.setConfigurationSetting("some_key", "some_label", "new_value");

Para la solicitud condicional, si desea actualizar condicionalmente una configuración, establezca el ifUnchanged parámetro en true. Cuando ifUnchanged es true, la configuración solo se actualiza si es la misma que la especificada setting. Esto se determina comparando la ETag de con la que setting se encuentra en el servicio para ver si son iguales o no. Si la ETag es la misma, significa que el valor de configuración es el mismo y se actualiza su valor.

ConfigurationSetting setting = configurationClient.setConfigurationSetting("some_key", "some_label", "some_value");
Response<ConfigurationSetting> settingResponse = configurationClient.setConfigurationSettingWithResponse(setting, true, Context.NONE);

Actualice un valor de configuración de marca de característica o el valor de configuración de referencia de Secrete en el almacén de configuración.

FeatureFlagConfigurationSetting setting = (FeatureFlagConfigurationSetting)
    configurationClient.setConfigurationSetting(featureFlagConfigurationSetting);

SecretReferenceConfigurationSetting setting = (SecretReferenceConfigurationSetting)
    configurationClient.setConfigurationSetting(referenceConfigurationSetting);

Eliminar un valor de configuración

Elimine una configuración existente llamando a deleteConfigurationSetting.

ConfigurationSetting setting = configurationClient.setConfigurationSetting("some_key", "some_label", "some_value");
ConfigurationSetting deletedSetting = configurationClient.deleteConfigurationSetting("some_key", "some_label");

Para la solicitud condicional, si desea eliminar condicionalmente una configuración, establezca el ifUnchanged parámetro en true. Cuando ifUnchanged el parámetro es true. Cuando ifUnchanged es true, la configuración solo se elimina si es igual que la especificada setting. Esto se determina comparando la ETag de con la que setting se encuentra en el servicio para ver si son iguales o no. Si la etiqueta ETag es la misma, significa que el valor de configuración es el mismo y se elimina su valor.

ConfigurationSetting setting = configurationClient.setConfigurationSetting("some_key", "some_label", "some_value");
Response<ConfigurationSetting> settingResponse = configurationClient.deleteConfigurationSettingWithResponse(setting, true, Context.NONE);

Elimine un valor de configuración de marca de característica o el valor de configuración de referencia de Secrete en el almacén de configuración.

FeatureFlagConfigurationSetting setting = (FeatureFlagConfigurationSetting)
    configurationClient.deleteConfigurationSetting(featureFlagConfigurationSetting);

SecretReferenceConfigurationSetting setting = (SecretReferenceConfigurationSetting)
    configurationClient.deleteConfigurationSetting(referenceConfigurationSetting);

Enumerar las opciones de configuración con varias claves

Enumere varias opciones de configuración mediante una llamada a listConfigurationSettings. Pase un valor NULL SettingSelector al método si desea capturar todas las opciones de configuración y sus campos.

String key = "some_key";
String key2 = "new_key";
configurationClient.setConfigurationSetting(key, "some_label", "some_value");
configurationClient.setConfigurationSetting(key2, "new_label", "new_value");
SettingSelector selector = new SettingSelector().setKeyFilter(key + "," + key2);
PagedIterable<ConfigurationSetting> settings = configurationClient.listConfigurationSettings(selector);

Enumeración de revisiones de varias opciones de configuración

Enumere todas las revisiones de una configuración llamando a listRevisions.

String key = "revisionKey";
configurationClient.setConfigurationSetting(key, "some_label", "some_value");
configurationClient.setConfigurationSetting(key, "new_label", "new_value");
SettingSelector selector = new SettingSelector().setKeyFilter(key);
PagedIterable<ConfigurationSetting> settings = configurationClient.listRevisions(selector);

Establecer un valor de configuración en solo lectura

Establezca un valor de configuración en estado de solo lectura.

configurationClient.setConfigurationSetting("some_key", "some_label", "some_value");
ConfigurationSetting setting = configurationClient.setReadOnly("some_key", "some_label", true);

Borrar solo lectura de una configuración

Desactive la opción de solo lectura de una configuración.

ConfigurationSetting setting = configurationClient.setReadOnly("some_key", "some_label", false);

Creación de un cliente con opciones de proxy

Cree un cliente de configuración con opciones de proxy.

// Proxy options
final String hostname = "{your-host-name}";
final int port = 447; // your port number

ProxyOptions proxyOptions = new ProxyOptions(ProxyOptions.Type.HTTP,
    new InetSocketAddress(hostname, port));
HttpClient httpClient = new NettyAsyncHttpClientBuilder()
    .proxy(proxyOptions)
    .build();
ConfigurationAsyncClient configurationAsyncClient = new ConfigurationClientBuilder()
    .connectionString("{your_connection_string}")
    .httpClient(httpClient)
    .buildAsyncClient();

Solución de problemas

General

Al interactuar con App Configuration mediante esta biblioteca cliente de Java, los errores devueltos por el servicio corresponden a los mismos códigos de estado HTTP devueltos para las solicitudes de LA API REST. Por ejemplo, si intenta recuperar una configuración que no existe en el almacén de configuración, se devuelve un 404 error, que indica Not Found.

App Configuration proporciona una manera de definir encabezados personalizados a través Context del objeto en la API pública.

// Add your headers
HttpHeaders headers = new HttpHeaders();
headers.set("my-header1", "my-header1-value");
headers.set("my-header2", "my-header2-value");
headers.set("my-header3", "my-header3-value");
// Call API by passing headers in Context.
configurationClient.addConfigurationSettingWithResponse(
    new ConfigurationSetting().setKey("key").setValue("value"),
    new Context(AddHeadersFromContextPolicy.AZURE_REQUEST_HTTP_HEADERS_KEY, headers));
// Above three HttpHeader will be added in outgoing HttpRequest.

Para obtener más información, consulte AddHeadersFromContextPolicy.

Cliente HTTP predeterminado

Todas las bibliotecas cliente usan de forma predeterminada el cliente HTTP de Netty. Al agregar la dependencia anterior, se configurará automáticamente la biblioteca cliente para usar el cliente HTTP de Netty. La configuración o el cambio del cliente HTTP se detalla en la wiki de clientes HTTP.

Biblioteca SSL predeterminada

De forma predeterminada, todas las bibliotecas cliente usan la biblioteca Boring SSL nativa de Tomcat para habilitar el rendimiento de nivel nativo para las operaciones SSL. La biblioteca Boring SSL es un archivo uber-jar que contiene bibliotecas nativas para Linux, macOS o Windows, que proporciona un mejor rendimiento en comparación con la implementación SSL predeterminada del JDK. Para obtener más información, incluido cómo reducir el tamaño de las dependencias, consulte la sección optimización del rendimiento de la wiki.

Pasos siguientes

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Impresiones