bibliothèque cliente Azure App Configuration pour Java - version 1.4.10

  • Article

Azure App Configuration est un service managé qui permet aux développeurs de centraliser leurs configurations d’application de façon simple et sécurisée.

Les programmes modernes, en particulier les programmes qui s’exécutent dans un cloud, ont généralement de nombreux composants qui sont par nature distribués. La répartition des paramètres de configuration sur tous ces composants peut rendre les erreurs difficiles à corriger pendant le déploiement d’une application. Utilisez App Configuration pour stocker tous les paramètres de votre application et sécuriser leur accès dans un même endroit.

Utilisez la bibliothèque cliente pour App Configuration pour créer et gérer les paramètres de configuration de l’application.

| Code sourcePackage (Maven) | Documentation de référence sur les | API | Documentation produitÉchantillons

Prise en main

Prérequis

Inclure le package

Inclure le fichier de nomenclature

Incluez le kit azure-sdk-bom à votre projet pour qu’il soit dépendant de la version disponibilité générale (GA) de la bibliothèque. Dans l’extrait de code suivant, remplacez l’espace réservé {bom_version_to_target} par le numéro de version. Pour en savoir plus sur la nomenclature, consultez LE FICHIER README DE NOMENCLATURE DU KIT DE DÉVELOPPEMENT LOGICIEL 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>

puis incluez la dépendance directe dans la section dépendances sans la balise de version comme indiqué ci-dessous.

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

Inclure une dépendance directe

Si vous souhaitez prendre la dépendance sur une version particulière de la bibliothèque qui n’est pas présente dans la nomenclature, ajoutez la dépendance directe à votre projet comme suit.

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

Créer un App Configuration Store

Pour créer un magasin de configuration, vous pouvez utiliser le portail Azure ou Azure CLI.

Vous devez d’abord installer l’extension CLI d’Azure App Configuration en exécutant la commande suivante :

az extension add -n appconfig

Après cela, créez le magasin de configuration :

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

Authentifier le client

Pour interagir avec le service App Configuration, vous devez créer un instance de la classe Client de configuration. Pour ce faire, vous aurez besoin de l’chaîne de connexion du magasin de configuration. Vous pouvez également utiliser le jeton AAD pour vous connecter au service.

Utiliser la chaîne de connexion

Récupérer les informations d’identification

Utilisez l’extrait de code Azure CLI ci-dessous pour obtenir les chaîne de connexion à partir du Magasin de configuration.

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

Vous pouvez également obtenir le chaîne de connexion à partir du portail Azure.

Créer un client de configuration

Une fois que vous avez la valeur du chaîne de connexion vous pouvez créer le client de configuration :

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

ou

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

Utiliser un jeton AAD

Ici, nous montrons l’utilisation de DefaultAzureCredential pour l’authentification en tant que principal de service. Toutefois, le client de configuration accepte toutes les informations d’identification azure-identity . Pour plus d’informations sur d’autres informations d’identification, consultez la documentation azure-identity .

Créer un principal de service (facultatif)

Cet extrait de code Azure CLI montre comment créer un principal de service. Avant de l’utiliser, remplacez « your-application-name » par le nom approprié pour votre principal de service.

Créez un principal de service :

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

Sortie :

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

Utilisez la sortie pour définir AZURE_CLIENT_ID (« appId » ci-dessus), AZURE_CLIENT_SECRET (« mot de passe » ci-dessus) et AZURE_TENANT_ID (« locataire » ci-dessus). L’exemple suivant montre comment procéder dans Bash :

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

Attribuez l’un des rôles de App Configuration applicables au principal de service.

Créer un client

Une fois les variables d’environnement AZURE_CLIENT_ID, AZURE_CLIENT_SECRET et AZURE_TENANT_ID définies, DefaultAzureCredential peut authentifier le client de configuration.

La construction du client nécessite également l’URL de votre magasin de configuration, que vous pouvez obtenir à partir d’Azure CLI ou du portail Azure. Dans le portail Azure, l’URL est répertoriée en tant que service « Point de terminaison ».

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

Concepts clés

Paramètre de configuration

Un paramètre de configuration est la ressource fondamentale dans un magasin de configuration. Dans sa forme la plus simple, il s’agit d’une clé et d’une valeur. Toutefois, il existe des propriétés supplémentaires telles que le type de contenu modifiable et les champs d’étiquettes qui permettent d’interpréter ou d’associer la valeur de différentes manières.

La propriété Label d’un paramètre de configuration permet de séparer les paramètres de configuration en différentes dimensions. Ces dimensions sont définies par l’utilisateur et peuvent prendre n’importe quelle forme. Parmi les exemples courants de dimensions à utiliser pour une étiquette, citons les régions, les versions sémantiques ou les environnements. De nombreuses applications disposent d’un ensemble obligatoire de clés de configuration qui ont des valeurs variables en fonction de l’existence de l’application sur différentes dimensions. Par exemple, MaxRequests peut être 100 dans « NorthAmerica » et 200 dans « WestEurope ». En créant un paramètre de configuration nommé MaxRequests avec une étiquette « NorthAmerica » et un autre, uniquement avec une valeur différente, dans l’étiquette « WestEurope », vous pouvez obtenir une solution qui permet à l’application de récupérer en toute transparence les paramètres de configuration au fur et à mesure qu’elle s’exécute dans ces deux dimensions.

Configuration Client

Le client effectue les interactions avec le service App Configuration, l’obtention, la définition, la suppression et la sélection des paramètres de configuration. Un client asynchrone, ConfigurationAsyncClientet synchrone existe ConfigurationClientdans le KIT de développement logiciel (SDK) permettant la sélection d’un client en fonction du cas d’usage d’une application.

Une application qui doit récupérer des configurations de démarrage est mieux adaptée à l’aide du client synchrone, par exemple la configuration d’une connexion 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);
        }
    }
}

Une application qui a un grand ensemble de configurations qu’elle doit mettre à jour régulièrement est mieux adaptée à l’utilisation du client asynchrone, par exemple tous les paramètres avec une étiquette spécifique sont régulièrement mis à jour.

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

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

Exemples

Les sections suivantes fournissent plusieurs extraits de code couvrant certaines des tâches de service de configuration les plus courantes, notamment : Pour les paramètres de configuration « Indicateur de fonctionnalité » et « Référence secrète », consultez les exemples pour plus de détails.

Créer un client de configuration

Créez un client de configuration à l’aide de ConfigurationClientBuilder chaîne de connexion.

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

Créer un paramètre de configuration

Créez un paramètre de configuration à stocker dans le magasin de configuration. Il existe deux façons de stocker un paramètre de configuration :

  • addConfigurationSetting crée un paramètre uniquement si le paramètre n’existe pas déjà dans le magasin.
ConfigurationSetting setting = configurationClient.addConfigurationSetting("new_key", "new_label", "new_value");

ou

  • setConfigurationSetting crée un paramètre s’il n’existe pas ou remplace un paramètre existant.
ConfigurationSetting setting = configurationClient.setConfigurationSetting("some_key", "some_label", "some_value");

Créez un paramètre de configuration d’indicateur de fonctionnalité ou un paramètre de configuration De référence secret à stocker dans le magasin de configuration.

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

Récupérer un paramètre de configuration

Récupérez un paramètre de configuration précédemment stocké en appelant getConfigurationSetting.

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

Pour la demande conditionnelle, si vous souhaitez extraire de manière conditionnelle un paramètre de configuration, définissez sur ifChanged true. Quand ifChanged a la valeur true, le paramètre de configuration n’est récupéré que s’il est différent du donné setting. Cela est déterminé en comparant l’ETag du setting à celui du service pour voir s’ils sont identiques ou non. Si les ETags ne sont pas les mêmes, cela signifie que le paramètre de configuration est différent et que sa valeur est récupérée.

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

Récupérez un paramètre de configuration d’indicateur de fonctionnalité ou un paramètre de configuration De référence secret dans le magasin de configuration.

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

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

Mettre à jour un paramètre de configuration existant

Mettez à jour un paramètre de configuration existant en appelant setConfigurationSetting.

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

Pour la demande conditionnelle, si vous souhaitez mettre à jour de manière conditionnelle un paramètre de configuration, définissez le paramètre sur ifUnchanged true. Quand ifUnchanged a la valeur true, le paramètre de configuration est mis à jour uniquement s’il est identique au donné setting. Cela est déterminé en comparant l’ETag du setting à celui du service pour voir s’ils sont identiques ou non. Si les ETag sont identiques, cela signifie que le paramètre de configuration est le même et que sa valeur est mise à jour.

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

Mettez à jour un paramètre de configuration d’indicateur de fonctionnalité ou un paramètre de configuration De référence du secret dans le magasin de configuration.

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

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

Supprimer un paramètre de configuration

Supprimez un paramètre de configuration existant en appelant deleteConfigurationSetting.

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

Pour la demande conditionnelle, si vous souhaitez supprimer de manière conditionnelle un paramètre de configuration, définissez le paramètre sur ifUnchanged true. Quand ifUnchanged le paramètre a la valeur true. Quand ifUnchanged a la valeur true, le paramètre de configuration n’est supprimé que s’il est identique au donné setting. Cela est déterminé en comparant l’ETag du setting à celui du service pour voir s’ils sont identiques ou non. Si l’ETag est identique, cela signifie que le paramètre de configuration est le même et que sa valeur est supprimée.

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

Supprimez un paramètre de configuration d’indicateur de fonctionnalité ou un paramètre de configuration De référence de secret dans le magasin de configuration.

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

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

Répertorier les paramètres de configuration avec plusieurs clés

Répertoriez plusieurs paramètres de configuration en appelant listConfigurationSettings. Passez une valeur null SettingSelector dans la méthode si vous souhaitez extraire tous les paramètres de configuration et leurs champs.

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

Répertorier les révisions de plusieurs paramètres de configuration

Répertoriez toutes les révisions d’un paramètre de configuration en appelant 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);

Définir un paramètre de configuration pour qu’il soit en lecture seule

Définissez un paramètre de configuration sur status en lecture seule.

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

Effacer la lecture uniquement à partir d’un paramètre de configuration

Effacer la lecture seule d’un paramètre de configuration.

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

Créer un client avec options de proxy

Créez un client de configuration avec des options 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();

Dépannage

Général

Lorsque vous interagissez avec App Configuration à l’aide de cette bibliothèque cliente Java, les erreurs retournées par le service correspondent aux mêmes codes de status HTTP retournés pour les demandes d’API REST. Par exemple, si vous essayez de récupérer un paramètre de configuration qui n’existe pas dans votre magasin de configuration, une 404 erreur est retournée, indiquant Not Found.

App Configuration permet de définir des en-têtes personnalisés via Context un objet dans l’API publique.

// 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.

Pour plus d’informations, case activée addHeadersFromContextPolicy

Client HTTP par défaut

Toutes les bibliothèques de client utilisent par défaut le client HTTP Netty. L’ajout de la dépendance ci-dessus configure automatiquement la bibliothèque de client pour utiliser le client HTTP Netty. La configuration ou la modification du client HTTP sont détaillées dans le wiki pour clients HTTP.

Bibliothèque SSL par défaut

Toutes les bibliothèques de client utilisent par défaut la bibliothèque BoringSSL Tomcat native pour permettre des performances de niveau natif pour les opérations SSL. La bibliothèque BoringSSL est un fichier uber jar contenant des bibliothèques natives pour Linux/macOS/Windows. Elle offre de meilleures performances que l’implémentation SSL par défaut au sein du JDK. Pour plus d’informations, notamment sur la réduction de la taille des dépendances, consultez la section du wiki consacrée à l’optimisation des performances.

Étapes suivantes

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) spécifiant que vous avez le droit de nous accorder les droits d’utiliser votre contribution, et que vous nous les accordez.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Impressions