Prise en charge de la configuration des applications

Cet article décrit la bibliothèque Spring Cloud Azure App Configuration. Cette bibliothèque charge les configurations et les indicateurs de fonctionnalité à partir du service Azure App Configuration. La bibliothèque génère des PropertySource abstractions pour correspondre aux abstractions déjà générées par l’environnement Spring, telles que les variables d’environnement, les configurations de ligne de commande, les fichiers de configuration locaux, etc.

Spring est un framework d’application open source développé par VMware qui fournit une approche simplifiée et modulaire pour créer des applications Java. Azure Spring Cloud est un projet open source qui fournit une intégration de Spring fluide aux services Azure.

Prérequis

• Un abonnement Azure - En créer un gratuitement
• Kit de développement Java (JDK) version 8 ou ultérieure.
• Apache Maven
• Azure CLI

Configurer votre magasin App Configuration

Utilisez la commande suivante pour créer votre magasin Azure App Configuration :

az appconfig create \
    --resource-group <your-resource-group> \
    --name <name-of-your-new-store> \
    --sku Standard

Cette commande crée un magasin de configuration vide. Vous pouvez charger vos configurations à l’aide de la commande d’importation suivante :

az appconfig kv import \
    --name <name-of-your-new-store> \
    --source file \
    --path <location-of-your-properties-file> \
    --format properties \
    --prefix /application/

Vérifiez vos configurations avant de les charger. Vous pouvez charger des fichiers YAML en modifiant le format en YAML. Le champ de préfixe est important, car il s’agit du préfixe par défaut chargé par la bibliothèque cliente.

Utilisation de la bibliothèque

Pour utiliser la fonctionnalité dans une application, vous pouvez la générer en tant qu’application Spring Boot. Le moyen le plus pratique d’ajouter la dépendance est avec le démarrage com.azure.spring:spring-cloud-azure-starter-appconfiguration-configSpring Boot . L’exemple suivant pom.xml fichier utilise Azure App Configuration :

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>{spring-boot-version}</version>
    <relativePath />
</parent>

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.azure.spring</groupId>
      <artifactId>spring-cloud-azure-dependencies</artifactId>
      <version>5.18.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>com.azure.spring</groupId>
        <artifactId>spring-cloud-azure-starter-appconfiguration-config</artifactId>
    </dependency>
</dependencies>
<build>
    <plugins>
           <plugin>
               <groupId>org.springframework.boot</groupId>
               <artifactId>spring-boot-maven-plugin</artifactId>
           </plugin>
    </plugins>
</build>

Remarque

Si vous utilisez Spring Boot 2.x, veillez à définir la spring-cloud-azure-dependencies version 4.19.0sur . Pour plus d’informations sur la version utilisée pour ce boM, consultez La version de Spring Cloud Azure à utiliser.

L’exemple suivant montre une application Spring Boot de base à l’aide d’App Configuration :

@SpringBootApplication
@RestController
public class Application {

    @RequestMapping("/")
    public String home() {
        return "Hello World!";
    }

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

Pour cet exemple, le fichier bootstrap.properties contient la ligne suivante :

spring.cloud.azure.appconfiguration.stores[0].connection-string=${CONFIG_STORE_CONNECTION_STRING}

CONFIG_STORE_CONNECTION_STRINGest une variable d’environnement avec le chaîne de connexion à votre Magasin Azure App Configuration. Vous pouvez accéder à votre chaîne de connexion à l’aide de la commande suivante :

az appconfig credential list --name <name-of-your-store>

Par défaut, si aucune configuration n’est définie, les configurations commençant /application/ par sont chargées avec une étiquette par défaut, (No Label) sauf si un profil Spring est défini, auquel cas l’étiquette par défaut est votre profil Spring. Étant donné que le magasin est vide, aucune configuration n’est chargée, mais la source de propriété Azure App Configuration est toujours générée.

Une source de propriété nommée /application/https://<name-of-your-store>.azconfig.io/ est créée contenant les propriétés de ce magasin. L’étiquette utilisée dans la requête est ajoutée à la fin du nom. Si aucune étiquette n’est définie, le caractère \0 est présent sous la forme d’un espace vide.

Configuration du chargement

La bibliothèque prend en charge le chargement d’un ou plusieurs magasins App Configuration. Dans le cas où une clé est dupliquée sur plusieurs magasins, le chargement de tous les magasins entraîne le chargement de la configuration des magasins de priorité la plus élevée. La dernière victoire. Ce processus est illustré dans l’exemple suivant :

spring.cloud.azure.appconfiguration.stores[0].connection-string=[first-store-connection-string]
spring.cloud.azure.appconfiguration.stores[1].connection-string=[second-store-connection-string]

Dans l’exemple, si les deux magasins ont la même configuration, la configuration du deuxième magasin a la priorité la plus élevée et la dernière gagne.

Remarque

Vous pouvez utiliser les paramètres Azure App Configuration comme n’importe quelle autre configuration Spring. Pour plus d’informations, consultez Les fonctionnalités principales de la documentation Spring Boot ou du guide de démarrage rapide : Créer une application Spring Java avec Azure App Configuration.

Sélection de configurations

Les configurations sont chargées par leur clé et leur étiquette. Par défaut, les configurations qui commencent par la clé /application/ sont chargées. L’étiquette par défaut est ${spring.profiles.active}. Si ${spring.profiles.active} ce n’est pas le cas, les configurations avec l’étiquette null sont chargées. L’étiquette null apparaît comme (No Label) dans la Portail Azure.

Vous pouvez configurer les configurations chargées en sélectionnant différents filtres de clé et d’étiquette, comme illustré dans l’exemple suivant :

spring.cloud.azure.appconfiguration.stores[0].selects[0].key-filter=[my-key]
spring.cloud.azure.appconfiguration.stores[0].selects[0].label-filter=[my-label]

La key-filter propriété prend en charge les filtres suivants :

Filtre de clé	Résultat
*	Correspond à n’importe quelle clé.
abc	Correspond à une clé nommée abc.
abc*	Correspond aux noms de clés qui commencent par abc.
abc,xyz	Correspond aux noms de clés abc ou xyz. Limité à cinq valeurs séparées par des virgules.

La label-filter propriété prend en charge les filtres suivants :

Étiquette	Description
*	Correspond à n’importe quelle étiquette, y compris \0.
\0	Correspond aux null étiquettes, qui apparaissent comme (No Label) dans le Portail Azure.
1.0.0	Correspond exactement à l’étiquette 1.0.0.
1.0.*	Correspond aux étiquettes qui commencent par 1.0.*.
,1.0.0	Correspond aux étiquettes null et 1.0.0. Limité à cinq valeurs séparées par des virgules.

Si vous utilisez YAML avec des filtres d’étiquette et que vous devez commencer nullpar , le filtre d’étiquette doit être entouré de guillemets simples, comme illustré dans l’exemple suivant :

spring:
  cloud:
    azure:
      appconfiguration:
        stores:
        - selects:
          - label-filter: ',1.0.0'

Remarque

Vous ne pouvez pas les combiner * , dans les filtres. Dans ce cas, vous devez utiliser une valeur de sélection supplémentaire.

Profils de Spring

Par défaut, spring.profiles.active est défini comme valeur par défaut label-filter pour toutes les configurations sélectionnées. Vous pouvez remplacer cette fonctionnalité à l’aide label-filterde . Vous pouvez utiliser les profils Spring dans l’utilisation label-filter ${spring.profiles.active}, comme illustré dans l’exemple suivant :

spring.cloud.azure.appconfiguration.stores[0].selects[0].label-filter=,${spring.profiles.active}
spring.cloud.azure.appconfiguration.stores[0].selects[1].label-filter=${spring.profiles.active}_local

Dans le premier label-filter, toutes les configurations avec l’étiquette null sont chargées, suivies de toutes les configurations correspondant aux profils Spring. Les profils Spring ont la priorité sur les null configurations, car ils sont à la fin.

Dans la seconde label-filter, la chaîne _local est ajoutée à la fin des profils Spring, mais uniquement au dernier Spring Profile.

Magasins désactivés

À l’aide de la configuration spring.cloud.azure.appconfiguration.enabled, vous pouvez désactiver le chargement pour tous les magasins de configuration. Avec la spring.cloud.azure.appconfiguration.stores[0].enabled configuration, vous pouvez désactiver un magasin individuel.

Outre la désactivation des magasins, vous pouvez configurer les magasins à désactiver s’ils ne parviennent pas à se charger. Pour cette configuration, utilisez spring.cloud.azure.appconfiguration.stores[0].fail-fast. Lorsqu’il fail-fast falseest désactivé en le définissant sur , un RuntimeException résultat dans le magasin d’applications est désactivé sans aucune configuration de son chargement. Si un magasin de configuration est désactivé au démarrage, il n’est pas vérifié pour les modifications lors de l’actualisation. En outre, il n’existe aucune tentative de chargement des valeurs à partir de celle-ci si les configurations sont mises à jour.

Si une erreur se produit RuntimeException lors d’une vérification de l’actualisation ou lors de la tentative de rechargement des configurations, la tentative d’actualisation se termine et est retentée après la refresh-interval réussite.

Authentification

La bibliothèque prend en charge toutes les formes d’identité prises en charge par la bibliothèque d’identités Azure. Vous pouvez effectuer l’authentification par le biais de la configuration des chaîne de connexion et de l’identité managée.

Chaîne de connexion

L’authentification via chaîne de connexion est le formulaire le plus simple à configurer. Vous pouvez accéder aux chaîne de connexion d’un magasin à l’aide de la commande suivante :

az appconfig credential list --name <name-of-your-store>

Vous pouvez ensuite définir la spring.cloud.azure.appconfiguration.stores[0].connection-string propriété sur la chaîne de connexion. Nous vous recommandons vivement de définir la chaîne de connexion dans le fichier de configuration local sur une valeur d’espace réservé qui est mappée à une variable d’environnement. Cette approche vous permet d’éviter d’ajouter les chaîne de connexion au contrôle de code source.

Configuration d’Azure Spring Cloud

Vous pouvez utiliser la configuration d’Azure Spring Cloud pour configurer la bibliothèque. Vous pouvez utiliser les propriétés suivantes pour configurer la bibliothèque :

spring.cloud.azure.appconfiguration.stores[0].endpoint= <URI-of-your-configuration-store>

Quand seul le point de terminaison est défini, la bibliothèque cliente utilise DefaultAzureCredential pour s’authentifier. Les DefaultAzureCredential méthodes suivantes sont utilisées pour s’authentifier :

• Informations d’identification de l’environnement
• Informations d’identification de l’identité managée
• Informations d’identification de l’interface CLI pour développeurs Azure
• Informations d’identification IntelliJ
• Informations d’identification d’Azure CLI
• Informations d’identification Azure PowerShell

Vous devez attribuer une identité telle qu’une identité affectée par le système pour lire les configurations. Vous pouvez créer cette affectation à l’aide de la commande suivante :

az role assignment create \
    --role "App Configuration Data Reader" \
    --assignee <your-client-ID> \
    --scope /subscriptions/<your-subscription>/resourceGroups/<your-stores-resource-group>/providers/Microsoft.AppConfiguration/configurationStores/<name-of-your-configuration-store>

Remarque

Vous ne pouvez définir qu’une seule méthode d’authentification par point de terminaison : chaîne de connexion, identité affectée par l’utilisateur ou informations d’identification de jeton. Si vous avez besoin de combiner et de faire correspondre, vous pouvez utiliser ConfigurationClientCustomizer pour modifier des magasins qui utilisent une autre méthode.

Géoréplication

La bibliothèque prend en charge la fonctionnalité de géoréplication d’Azure App Configuration. Cette fonctionnalité vous permet de répliquer vos données vers d’autres emplacements. Cette fonctionnalité est utile pour la haute disponibilité et la récupération d’urgence.

Chaque réplica que vous créez a un point de terminaison dédié. Si votre application réside dans plusieurs géolocalisations, vous pouvez mettre à jour chaque déploiement de votre application dans un emplacement pour vous connecter au réplica le plus proche de cet emplacement, ce qui permet de réduire la latence réseau entre votre application et App Configuration. Étant donné que chaque réplica a son quota de requêtes distinct, cette configuration permet également l’extensibilité de votre application alors qu’elle augmente vers un service distribué multirégion.

Le basculement peut se produire si la bibliothèque observe l’une des conditions suivantes :

• Reçoit des réponses avec le code d’état non disponible du service (HTTP 500 ou version ultérieure) à partir d’un point de terminaison.
• Rencontre des problèmes de connectivité réseau.
• Les requêtes sont limitées (code d’état HTTP 429)

Création d’un magasin de configuration avec géoréplication

Pour créer un réplica de votre magasin de configuration, vous pouvez utiliser Azure CLI ou le Portail Azure. L’exemple suivant utilise Azure CLI pour créer un réplica dans la région USA Est 2 :

az appconfig replica create --location --name --store-name [--resource-group]

Utilisation du réplica du magasin de configuration

Une fois que vous avez créé un réplica, vous pouvez l’utiliser dans votre application. Comme le magasin d’origines, vous pouvez vous connecter à votre réplica à l’aide de l’ID Microsoft Entra ou d’un chaîne de connexion.

Microsoft Entra ID

Pour utiliser l’ID Microsoft Entra pour vous connecter à votre réplica, vous devez répertorier les endpoints instances de votre magasin de configuration, comme indiqué dans l’exemple suivant :

spring.cloud.azure.appconfiguration.stores[0].endpoints[0]=[your primary store endpoint]
spring.cloud.azure.appconfiguration.stores[0].endpoints[1]=[your replica store endpoint]

Vous pouvez répertorier autant de points de terminaison que vous avez des réplicas. La bibliothèque tente de se connecter aux points de terminaison dans l’ordre dans lequel elles sont répertoriées. Si la bibliothèque ne parvient pas à se connecter à un réplica, elle essaie la suivante dans la liste. Une fois la période écoulée, la bibliothèque tente de se reconnecter aux points de terminaison préférés.

chaîne de connexion

Pour utiliser un chaîne de connexion pour vous connecter à votre réplica, vous devez répertorier les connectionStrings instances de votre magasin de configuration, comme indiqué dans l’exemple suivant :

spring.cloud.azure.appconfiguration.stores[0].connectionStrings[0]=[your primary store connection string]
spring.cloud.azure.appconfiguration.stores[0].connectionStrings[1]=[your replica store connection string]

Vous pouvez répertorier autant de chaîne de connexion s que vous avez des réplicas. La bibliothèque tente de se connecter aux chaîne de connexion dans l’ordre dans lequel elles sont répertoriées. Si la bibliothèque ne parvient pas à se connecter à un réplica, elle essaie la suivante dans la liste. Une fois la période écoulée, la bibliothèque tente de se reconnecter aux chaîne de connexion préférées.

Valeurs de clé

Azure App Configuration prend en charge plusieurs types de valeurs clés, dont certaines ont des fonctionnalités spéciales intégrées. Azure App Configuration prend en charge le type de contenu JSON, les espaces réservés Spring et les références Key Vault.

Espaces réservés

La bibliothèque prend en charge les configurations avec ${}des espaces réservés d’environnement de style. Lorsque vous référencez une clé Azure App Configuration avec un espace réservé, supprimez les préfixes de la référence. Par exemple, /application/config.message est référencé en tant que ${config.message}.

Remarque

Le préfixe en cours de suppression correspond à la valeur spring.cloud.azure.appconfiguration.stores[0].selects[0].key-filter.

JSON

Les configurations qui ont un type application/json de contenu sont traitées en tant qu’objets JSON. Cette fonctionnalité vous permet de mapper une configuration à un objet complexe à l’intérieur d’un @ConfigurationProperties. Par exemple, considérez la clé /application/config.colors JSON avec la valeur suivante :

{
 "Red": {
  "value": [255, 0, 0]
 },
 "Blue": {
  "value": [0, 255, 0]
 },
 "Green": {
  "value": [0, 0, 255]
 }
}

Cette clé est mappée au code suivant :

@ConfigurationProperties(prefix = "config")
public class MyConfigurations {

    private Map<String, Color> colors;

}

Références Key Vault

Azure App Configuration et ses bibliothèques prennent en charge le référencement des secrets stockés dans Key Vault. Dans App Configuration, vous pouvez créer des clés avec des valeurs qui mappent aux secrets stockés dans un coffre de clés. Les secrets sont stockés en toute sécurité dans Key Vault, mais sont accessibles de la même façon que toute autre configuration après son chargement.

Votre application utilise le fournisseur client pour récupérer les références Key Vault, tout comme pour les autres clés stockées dans App Configuration. Étant donné que le client reconnaît les clés en tant que références Key Vault, ils ont un type de contenu unique et le client se connecte à Key Vault pour récupérer leurs valeurs pour vous.

Remarque

Key Vault autorise uniquement la récupération des secrets un par un, de sorte que chaque référence Key Vault stockée dans App Configuration entraîne une extraction sur Key Vault.

Création de références Key Vault

Vous pouvez créer une référence Key Vault dans le Portail Azure en accédant à l’Explorateur>de configuration pour créer une>référence Key Vault. Vous pouvez ensuite sélectionner un secret à référencer parmi les coffres de clés auquel vous avez accès. Vous pouvez également créer des références De coffre de clés arbitraires à partir de l’onglet Entrée. Dans le Portail Azure, entrez un URI valide.

Vous pouvez également créer une référence Key Vault via Azure CLI à l’aide de la commande suivante :

az appconfig kv set-keyvault \
    --name <name-of-your-store> \
    --key <key-name> \
    --secret-identifier <URI-to-your-secret>

Vous pouvez créer n’importe quel identificateur secret via Azure CLI. Les identificateurs de secret nécessitent simplement le format {vault}/{collection}/{name}/{version?} dans lequel la section de version est facultative.

Utiliser des références Key Vault

Vous pouvez utiliser la configuration d’Azure Spring Cloud pour configurer la bibliothèque. Vous pouvez utiliser les mêmes informations d’identification que celles utilisées pour vous connecter à App Configuration pour vous connecter à Azure Key Vault.

Résoudre les secrets non-Key Vault

La bibliothèque App Configuration fournit une méthode pour résoudre localement les secrets qui n’ont pas de coffre de clés qui leur sont associés. Cette résolution est effectuée par le biais du KeyVaultSecretProvider. L’option KeyVaultSecretProvider est appelée lorsqu’une TokenCredential référence Key Vault n’est pas fournie. L’URI de la référence Key Vault est fourni et la valeur retournée devient la valeur du secret.

Avertissement

L’utilisation d’un KeyVaultSecretProvider remplacement remplace l’utilisation automatique de l’identité managée affectée par le système. Pour utiliser les deux, vous devez utiliser KeyVaultCredentialProvider et retourner null les URI qui ont besoin de résoudre.

public class MySecretProvider implements KeyVaultSecretProvider {

    @Override
    public String getSecret(String uri) {
        ...
    }

}

Gestion des fonctionnalités

La gestion des fonctionnalités permet aux applications Spring Boot d’accéder dynamiquement au contenu. La gestion des fonctionnalités a différentes fonctions, telles que les suivantes :

• Indicateurs de fonctionnalité qui peuvent activer ou désactiver le contenu
• Filtres de fonctionnalités pour le ciblage lorsque le contenu est affiché
• Filtres de fonctionnalités personnalisés
• Portes de fonctionnalité pour activer dynamiquement les points de terminaison

Vous pouvez activer les indicateurs de fonctionnalité via la configuration suivante :

spring.cloud.azure.appconfiguration.stores[0].feature-flags.enabled= true

Les indicateurs de fonctionnalité activés sont chargés dans le système de configuration Spring avec le préfixe feature-management. Vous pouvez également inscrire des indicateurs de fonctionnalité dans le fichier de configuration local. Pour plus d’informations, consultez la section Déclaration de l’indicateur de fonctionnalité.

Le moyen le plus simple d’utiliser la gestion des fonctionnalités consiste à utiliser les bibliothèques et spring-cloud-azure-feature-management-web les spring-cloud-azure-feature-management bibliothèques. La différence entre les deux bibliothèques est qu’il spring-cloud-azure-feature-management-web faut une dépendance aux spring-web bibliothèques pour spring-webmvc ajouter d’autres fonctionnalités, telles que des portes de fonctionnalité.

Vous pouvez activer les indicateurs de fonctionnalité à l’aide de filtres clé/étiquette. Par défaut, une null étiquette, considérée comme (No Label)affectée, est affectée. Vous pouvez configurer les indicateurs de fonctionnalité chargés en définissant un filtre d’étiquette, comme illustré dans l’exemple suivant :

spring.cloud.azure.appconfiguration.stores[0].feature-flags.selects[0].key-filter=A*
spring.cloud.azure.appconfiguration.stores[0].feature-flags.selects[0].label-filter= dev

Principes de base de la gestion des fonctionnalités

Indicateurs de fonctionnalité

Les indicateurs de fonctionnalité sont composés de deux parties : un nom et une liste de filtres de fonctionnalités utilisés pour activer la fonctionnalité. Les indicateurs de fonctionnalité peuvent avoir un état booléen activé/désactivé, ou avoir une liste de filtres de fonctionnalités. Les indicateurs de fonctionnalité évaluent les filtres de fonctionnalités jusqu’à ce qu’un retour soit retourné true. Si aucun filtre de fonctionnalité n’est retourné true, l’indicateur de fonctionnalité retourne false.

Filtres de fonctionnalités

Les filtres de fonctionnalités définissent un scénario pour lequel une fonctionnalité doit être activée. Les filtres de fonctionnalités sont évalués de façon synchrone.

La bibliothèque de gestion des fonctionnalités est fournie avec quatre filtres prédéfinis : AlwaysOnFilter, PercentageFilter, TimeWindowFilter et TargetingFilter.

Vous pouvez créer des filtres de fonctionnalités personnalisés. Par exemple, vous pouvez utiliser un filtre de fonctionnalités pour fournir une expérience personnalisée aux clients qui utilisent un navigateur Microsoft Edge. Vous pouvez personnaliser les fonctionnalités de ce filtre de fonctionnalités, par exemple, pour afficher un en-tête spécifique pour l’audience du navigateur Microsoft Edge.

Déclaration d’indicateur de fonctionnalité

La bibliothèque de gestion des fonctionnalités prend en charge Azure App Configuration avec application.yml ou bootstrap.yml en tant que sources pour les indicateurs de fonctionnalité. Voici un exemple du format utilisé pour configurer des indicateurs de fonctionnalité dans un fichier application.yml :

feature-management:
  feature-t: false
  feature-u:
    enabled-for:
    - name: Random
  feature-v:
    enabled-for:
    - name: TimeWindowFilter
      parameters:
        Start: "Wed, 01 May 2019 13:59:59 GMT"
        End: "Mon, 01 July 2019 00:00:00 GMT"
  feature-w:
    evaluate: false
    enabled-for:
    - name: AlwaysOnFilter

Cet exemple présente les indicateurs de fonctionnalité suivants :

• feature-t est défini sur false. Ce paramètre retourne toujours la valeur de l’indicateur de fonctionnalité.
• feature-u est utilisé avec des filtres de fonctionnalités. Ces filtres sont définis sous la enabled-for propriété. Dans ce cas, feature-u dispose d’un filtre de fonctionnalité appelé Random, qui ne nécessite aucune configuration, de sorte que seule la propriété de nom est requise.
• feature-v spécifie un filtre de fonctionnalités nommé TimeWindowFilter. Ce filtre de fonctionnalités peut être transmis aux paramètres à utiliser comme configuration. Dans cet exemple, un TimeWindowFilter, passe les heures de début et de fin pendant lesquelles la fonctionnalité est active.
• feature-w est utilisé pour le AlwaysOnFilter, qui prend toujours la valeur true. Le evaluate champ est utilisé pour arrêter l’évaluation des filtres de fonctionnalités et génère le retour falsedu filtre de fonctionnalités.

Évaluation des indicateurs de fonctionnalité

La spring-cloud-azure-feature-management bibliothèque fournit FeatureManager pour déterminer si un indicateur de fonctionnalité est activé. FeatureManager fournit un moyen asynchrone de vérifier l’état de l’indicateur.

spring-cloud-azure-feature-management-web, ainsi que fournir FeatureManager, contient FeatureManagerSnapshot, qui met en cache l’état des indicateurs de fonctionnalités précédemment évalués dans le @RequestScope pour garantir que toutes les requêtes retournent la même valeur. En outre, la bibliothèque web fournit @FeatureGate, qui peut bloquer ou rediriger des requêtes web vers différents points de terminaison.

Vérification d’indicateur de fonctionnalité

FeatureManager est un @Bean objet qui peut être @Autowired ou injecté dans @Component des objets de type. FeatureManager a une méthode isEnabled qui, lorsqu’elle a passé le nom d’un indicateur de fonctionnalité, retourne son état.

@Autowired
FeatureManager featureManager;

if (featureManager.isEnabled("feature-t")) {
    // Do Something
}

Remarque

FeatureManger possède également une version asynchrone appelée isEnabled isEnabledAsync.

Si vous n’avez pas configuré la gestion des fonctionnalités ou que l’indicateur de fonctionnalité n’existe pas, isEnabled retourne falsetoujours . Si un indicateur de fonctionnalité existant est configuré avec un filtre de fonctionnalité inconnu, il FilterNotFoundException est levée. Vous pouvez modifier ce comportement pour revenir false en configurant fail-fast sur false. Le tableau suivant décrit fail-fast:

Nom	Description	Obligatoire	Par défaut
spring.cloud.azure.feature.management.fail-fast	Si une exception se produit, une RuntimeException exception est levée. Si cette propriété est définie falsesur , isEnabled retourne false à la place.	Non	true

La seule différence entre FeatureManagerSnapshot et FeatureManager est la mise en cache des résultats dans le @RequestScope.

Porte de fonctionnalité

Avec la bibliothèque web de gestion des fonctionnalités, vous pouvez exiger qu’une fonctionnalité donnée soit activée pour exécuter un point de terminaison. Vous pouvez configurer cette exigence à l’aide de l’annotation @FeatureGate , comme illustré dans l’exemple suivant :

@GetMapping("/featureT")
@FeatureGate(feature = "feature-t")
@ResponseBody
public String featureT() {
    ...
}

Vous ne pouvez accéder au featureT point de terminaison que si « feature-t » est activé.

Gestion des actions désactivées

Lorsqu’un point de terminaison est bloqué, car la fonctionnalité spécifiée est désactivée, DisabledFeaturesHandler est appelée. Par défaut, un HTTP 404 est retourné. Vous pouvez remplacer ce comportement en implémentant DisabledFeaturesHandler, comme illustré dans l’exemple suivant :

@Component
public class MyDisabledFeaturesHandler implements DisabledFeaturesHandler {

    @Override
    public HttpServletResponse handleDisabledFeatures(HttpServletRequest request, HttpServletResponse response) {
        ...
        return response;
    }

}

Routage

Certains itinéraires peuvent exposer les fonctionnalités d’application qui sont contrôlées par les fonctionnalités. Si une fonctionnalité est désactivée, vous pouvez rediriger ces itinéraires vers un autre point de terminaison, comme illustré dans l’exemple suivant :

@GetMapping("/featureT")
@FeatureGate(feature = "feature-t" fallback= "/oldEndpoint")
@ResponseBody
public String featureT() {
    ...
}

@GetMapping("/oldEndpoint")
@ResponseBody
public String oldEndpoint() {
    ...
}

Filtres de fonctionnalités intégrés

Il existe quelques filtres de fonctionnalités fournis avec le spring-cloud-azure-feature-management package. Ces filtres de fonctionnalités ne sont pas ajoutés automatiquement, mais vous pouvez les configurer dans un @Configuration.

AlwaysOnFilter

Ce filtre retourne truetoujours . Pour obtenir un exemple d’utilisation, consultez la section déclaration d’indicateur de fonctionnalité.

PercentageFilter

Chaque fois qu’un utilisateur effectue une demande, l’évaluation PercentageFilter peut retourner un résultat différent. Vous pouvez contourner cette incohérence à l’aide du FeatureManagementSnapshot, qui met en cache le résultat de l’indicateur de fonctionnalité par utilisateur. Cette fonctionnalité garantit qu’un utilisateur a une expérience cohérente, même s’il doit renvoyer la demande.

feature-management:
  feature-v:
    enabled-for:
    - name: PercentageFilter
      parameters:
        Value: 50

TimeWindowFilter

Ce filtre permet d’activer une fonctionnalité en fonction d’une fenêtre de temps. Si vous spécifiez uniquement End, la fonctionnalité est considérée comme activée jusqu’à ce moment. Si vous spécifiez uniquement Start, la fonctionnalité est considérée sur tous les points après cette heure. Si vous spécifiez les deux, la fonctionnalité est considérée comme valide entre les deux fois.

feature-management:
  feature-v:
    enabled-for:
    - name: TimeWindowFilter
      parameters:
        Start: "Wed, 01 May 2019 13:59:59 GMT",
        End: "Mon, 01 July 2019 00:00:00 GMT"

TargetingFilter

Ce filtre permet d’activer une fonctionnalité pour un public cible. Pour obtenir une explication détaillée du ciblage, consultez la section de la section ciblage. Les paramètres de filtre incluent un objet d’audience qui décrit les utilisateurs, les groupes et un pourcentage par défaut de la base d’utilisateurs qui doit avoir accès à la fonctionnalité. Pour chaque objet de groupe répertorié dans l’audience cible, un pourcentage est requis qui définit le pourcentage des membres de ce groupe ayant accès à la fonctionnalité. Un utilisateur dispose de la fonctionnalité activée dans les cas suivants :

• L’utilisateur est spécifié directement dans la section des utilisateurs.
• L’utilisateur se trouve dans le pourcentage inclus de l’un des déploiements de groupe.
• L’utilisateur tombe dans le pourcentage de déploiement par défaut.

feature-management: 
  target:
    enabled-for:
    - name: targetingFilter
      parameters:
        users:
        - Jeff
        - Alicia
        groups:
        - name: Ring0
          rollout-percentage: 100
        - name: Ring1
          rolloutPercentage: 100
        default-rollout-percentage: 50

Filtres de fonctionnalités personnalisés

La création d’un filtre de fonctionnalités personnalisé permet d’activer les fonctionnalités en fonction des critères que vous définissez. Pour créer un filtre de fonctionnalités personnalisé, vous devez implémenter l’interface FeatureFilter . FeatureFilter a une seule méthode evaluate. Lorsqu’une fonctionnalité spécifie qu’elle peut être activée avec un filtre de fonctionnalités, la evaluate méthode est appelée. Si evaluate elle est retournée true, cela signifie que la fonctionnalité doit être activée. S’il retourne false, il continue à évaluer les filtres de fonctionnalités jusqu’à ce qu’un retour soit effectué true. Si tous les filtres retournent false, la fonctionnalité est désactivée.

Les filtres de fonctionnalités sont définis en tant que Spring Beans, de sorte qu’ils sont définis comme @Component ou définis dans un @Configuration.

@Component("Random")
public class Random implements FeatureFilter {

    @Override
    public boolean evaluate(FeatureFilterEvaluationContext context) {
        double chance = Double.valueOf((String) context.getParameters().get("chance"));
        return Math.random() > chance / 100;
    }

}

Filtres de fonctionnalités paramétrables

Certains filtres de fonctionnalités nécessitent des paramètres pour déterminer si une fonctionnalité doit être activée. Par exemple, un filtre de fonctionnalités de navigateur peut activer une fonctionnalité pour un certain ensemble de navigateurs. Vous souhaiterez peut-être qu’une fonctionnalité soit activée pour les navigateurs Microsoft Edge et Chrome, mais pas Firefox. Pour configurer cette situation, vous pouvez concevoir un filtre de fonctionnalités pour attendre des paramètres. Ces paramètres sont spécifiés dans la configuration des fonctionnalités et dans le code, et sont accessibles via le FeatureFilterEvaluationContext paramètre de evaluate. FeatureFilterEvaluationContext a une propriété parameters, qui est un HashMap<String, Object>.

Ciblage

Le ciblage est une stratégie de gestion des fonctionnalités qui permet aux développeurs de déployer progressivement de nouvelles fonctionnalités sur leur base d’utilisateurs. La stratégie repose sur le concept de ciblage d’un ensemble d’utilisateurs appelés public cible. Un public est constitué d’utilisateurs, de groupes spécifiques et d’un pourcentage désigné de l’ensemble de la base d’utilisateurs. Les groupes inclus dans le public peuvent être divisés en pourcentages de leurs membres totaux.

Les étapes suivantes illustrent un exemple de déploiement progressif d’une nouvelle fonctionnalité « Bêta » :

1. Les utilisateurs individuels Jeff et Alicia ont accès à la version bêta.
2. Un autre utilisateur, Mark, demande d’accepter et est inclus.
3. Vingt pour cent d’un groupe appelé utilisateurs « Ring1 » sont inclus dans la version Bêta.
4. Le nombre d’utilisateurs « Ring1 » inclus dans la version bêta est passé à 100 %.
5. Cinq pour cent de la base d’utilisateurs sont inclus dans la version Bêta.
6. Le pourcentage de déploiement est passé à 100 % et la fonctionnalité est entièrement déployée.

Cette stratégie de déploiement d’une fonctionnalité est intégrée à la bibliothèque via le filtre de fonctionnalités inclus TargetingFilter .

Ciblage dans une application

Un exemple d’application web qui utilise le filtre de fonctionnalités de ciblage est disponible dans l’exemple de projet.

Pour commencer à utiliser l’application TargetingFilter , vous devez l’ajouter comme @Bean tout autre filtre de fonctionnalité. TargetingFilter s’appuie sur un autre @Bean à ajouter à l’application TargetingContextAccessor. Permet TargetingContextAccessor de définir le courant TargetingContext à utiliser pour définir l’ID d’utilisateur et les groupes actuels, comme illustré dans l’exemple suivant :

public class MyTargetingContextAccessor implements TargetingContextAccessor {

    @Override
    public void getContextAsync(TargetingContext context) {
        context.setUserId("Jeff");
        ArrayList<String> groups = new ArrayList<String>();
        groups.add("Ring0");
        context.setGroups(groups);
    }

}

Options d’évaluation de ciblage

Les options sont disponibles pour personnaliser la façon dont l’évaluation du ciblage est effectuée dans un ensemble donné TargetingFilter. Vous pouvez définir un paramètre facultatif, TargetingEvaluationOptionspendant la TargetingFilter création.

    @Bean
    public TargetingFilter targetingFilter(MyTargetingContextAccessor contextAccessor) {
        return new TargetingFilter(contextAccessor, new TargetingEvaluationOptions().setIgnoreCase(true));
    }

Actualisation de la configuration

L’activation de l’actualisation de la configuration pour vos configurations vous permet d’extraire leurs dernières valeurs à partir de votre magasin Ou magasin App Configuration sans avoir à redémarrer l’application.

Pour activer l’actualisation, vous devez activer la surveillance avec les déclencheurs de surveillance. Un déclencheur d’analyse est une clé avec une étiquette facultative qui recherche les modifications de valeur pour déclencher des mises à jour. La valeur du déclencheur de surveillance peut être n’importe quelle valeur, tant qu’elle change lorsqu’une actualisation est nécessaire.

Remarque

Toute opération qui modifie l’ETag d’un déclencheur de surveillance provoque une actualisation, telle qu’une modification de type de contenu.

spring:
  cloud:
    azure:
      appconfiguration:
        stores:
        - monitoring:
          enabled: true
          triggers:
          - key: [my-watched-key]
            label: [my-watched-label]

Pour déclencher une actualisation de la configuration, modifiez la valeur d’une clé dans votre magasin de configuration. Ensuite, mettez à jour l’une des clés espions vers une nouvelle valeur. Cette modification déclenche la création d’un journal. Par exemple, en modifiant la valeur des /application/config.message déclencheurs, le message de journal suivant :

INFO 17496 --- [TaskScheduler-1] o.s.c.e.event.RefreshEventListener       : Refresh keys changed: [config.message]

Une fois que l’application a généré le journal, elle actualise tous les @Beans dans l’étendue d’actualisation.

Remarque

Par défaut, @ConfigurationProperties les haricots annotés sont inclus dans cette étendue.

Actualisation basée sur l’extraction

Les bibliothèques Spring App Configuration prennent en charge la possibilité de vérifier régulièrement l’intervalle d’actualisation des modifications apportées aux déclencheurs de surveillance. Par défaut, l’intervalle d’actualisation est défini sur 30 secondes. Une fois l’intervalle d’actualisation passé, tous les déclencheurs sont archivés dans le magasin donné pour les modifications. Toute modification apportée à la clé entraîne un déclenchement d’une actualisation. Étant donné que les bibliothèques s’intègrent au système d’actualisation Spring, toutes les actualisations rechargent toutes les configurations de tous les magasins. Vous pouvez définir l’intervalle d’actualisation sur un intervalle de plus de 1 seconde. Les unités prises en charge pour l’intervalle d’actualisation sont s, met hd pour les secondes, les minutes, les heures et les jours respectivement. L’exemple suivant définit l’intervalle d’actualisation sur 5 minutes :

spring.cloud.azure.appconfiguration.stores[0].monitoring.refresh-interval= 5m

Automatisé

Lorsque vous utilisez la spring-cloud-azure-appconfiguration-config-web bibliothèque, l’application recherche automatiquement une actualisation chaque fois qu’une demande servlet se produit, en particulier ServletRequestHandledEvent. La façon la plus courante d’envoyer cet événement est par des demandes adressées aux points de terminaison dans un @RestController.

Manuel

Dans les applications qui utilisent uniquement spring-cloud-azure-appconfiguration-config, telles que les applications console, vous pouvez déclencher manuellement une actualisation en appelant AppConfigurationRefreshla méthode ' .refreshConfiguration AppConfigurationRefresh est un @Bean que vous pouvez injecter dans n’importe quel @Component.

En outre, étant donné que la bibliothèque utilise le système de configuration de Spring, le déclenchement d’une actualisation entraîne une actualisation de toutes vos configurations, pas seulement un rechargement des configurations à partir de votre magasin Azure App Configuration.

Actualisation par envoi (push)

Vous pouvez configurer la spring-cloud-azure-appconfiguration-config-web bibliothèque pour recevoir des notifications Push de votre magasin Azure App Configuration pour actualiser vos valeurs de configuration. Vous pouvez configurer cette configuration via un Web Hook Azure Event Grid, que vous pouvez configurer pour envoyer des notifications de modifications à des clés spécifiées. En ajoutant la bibliothèque Spring Actuator en tant que dépendance, vous pouvez exposer les points de terminaison d’actualisation d’App Configuration. Il existe deux points de terminaison différents : appconfiguration-refresh et appconfiguration-refresh-bus. Ces points de terminaison fonctionnent de la même façon que leurs équivalents refresh et refresh-bus, où les points de terminaison de configuration d’application expirent l’intervalle d’actualisation au lieu de forcer une actualisation lors de la réception. Vous pouvez toujours utiliser et refresh refresh-bus, mais vous ne pouvez pas les connecter directement à Azure Event Grid avec un Web Hook, car ils nécessitent une réponse lors de l’installation.

La propriété expire l’intervalle d’actualisation. L’intervalle appconfiguration-refresh d’actualisation restant n’est donc pas attendu avant la vérification de l’actualisation suivante. La appconfiguration-refresh-bus propriété envoie une notification à un service de messagerie connecté, tel qu’Azure Service Bus, pour notifier toutes les instances d’une application à actualiser. Dans les deux cas, il n’expire pas complètement à l’intervalle d’actualisation, mais est désactivé par une petite gigue. Cette gigue garantit que chaque instance de votre application n’essaie pas d’actualiser en même temps.

management.endpoints.web.exposure.include= appconfiguration-refresh, appconfiguration-refresh-bus

En plus d’exposer les points de terminaison d’actualisation, un paramètre de requête requis a été ajouté pour la sécurité. Aucun nom ou valeur de jeton n’est défini par défaut, mais la définition d’un jeton est requise pour utiliser les points de terminaison, comme indiqué dans l’exemple suivant :

spring.cloud.azure.appconfiguration.stores[0].monitoring.push-notification.primary-token.name=[primary-token-name]
spring.cloud.azure.appconfiguration.stores[0].monitoring.push-notification.primary-token.secret=[primary-token-secret]
spring.cloud.azure.appconfiguration.stores[0].monitoring.push-notification.secondary-token.name=[secondary-token-name]
spring.cloud.azure.appconfiguration.stores[0].monitoring.push-notification.secondary-token.secret=[secondary-token-secret]

Configuration des hooks web

Pour configurer un hook web, ouvrez votre magasin Azure App Configuration et ouvrez Événements à partir du menu de navigation. Ensuite, sélectionnez Abonnement aux événements. Définissez le nom de votre événement et sélectionnez le type de point de terminaison comme Web Hook. Si vous sélectionnez Web Hook, une option de point de terminaison s’affiche. Choisissez Sélectionner un point de terminaison. Votre point de terminaison doit ressembler à l’exemple suivant : https://www.myaplication.com/actuator/appconfiguration-refresh?myTokenName=mySecret.

Confirmez que la sélection envoie une notification d’installation à l’URI donné et attend une réponse. Si aucune réponse n’est retournée, le programme d’installation échoue. La azure-spring-cloud-appconfiguration-web configuration de la bibliothèque pour les points de terminaison retourne la réponse correcte si le magasin Azure App Configuration est configuré pour l’application. Cette confirmation peut être envoyée d’une autre manière. Pour plus d’informations sur la remise des hooks web, consultez remise d’événements webhook.

Remarque

Cette validation se produit uniquement lors de la création ou de la modification du point de terminaison.

Nous vous recommandons vivement de configurer des filtres, car sinon, une actualisation est déclenchée après chaque création et modification de clé.

Actualisation forcée du client

Vous pouvez configurer la bibliothèque pour forcer l’actualisation de toutes les configurations à un intervalle d’actualisation. Le tableau suivant décrit la refresh-interval propriété :

Nom	Description	Obligatoire	Par défaut
spring.cloud.azure.appconfiguration.refresh-interval	Durée standard entre les actualisations. Est un Duration.	Non	null

L’actualisation avec spring.cloud.azure.appconfiguration.refresh-interval ne vérifie aucune clé espion configurée. Cette propriété est utilisée pour vous assurer que les secrets Key Vault sont conservés à jour, car Azure App Configuration ne peut pas savoir quand ils sont mis à jour.

Étant donné qu’Azure Key Vault stocke la paire de clés publique et privée d’un certificat en tant que secret, votre application peut récupérer n’importe quel certificat en tant que référence Key Vault dans App Configuration. Étant donné que les certificats doivent faire l’objet d’une rotation périodique, les applications clientes doivent être mises à jour aussi fréquemment, ce qui peut être effectué à l’aide de l’intervalle d’actualisation du client.

Actualisation de l’indicateur de fonctionnalité

Si les indicateurs de fonctionnalité et la surveillance sont tous les deux activés, l’intervalle d’actualisation par défaut pour les indicateurs de fonctionnalité est défini sur 30 secondes. Une fois l’intervalle d’actualisation passé, tous les indicateurs de fonctionnalité sont archivés dans le magasin donné pour les modifications. Toute modification apportée à la clé entraîne un déclenchement d’une actualisation. Étant donné que les bibliothèques s’intègrent au système d’actualisation Spring, toutes les actualisations rechargent toutes les configurations de tous les magasins. Vous pouvez définir l’intervalle d’actualisation sur un intervalle de plus de 1 seconde. Les unités prises en charge pour l’intervalle d’actualisation sont s, met hd pour les secondes, les minutes, les heures et les jours respectivement. L’exemple suivant définit l’intervalle d’actualisation sur 5 minutes :

spring.cloud.azure.appconfiguration.stores[0].monitoring.feature-flag-refresh-interval= 5m

Indicateur d’intégrité

La bibliothèque cliente est fournie avec un indicateur d’intégrité qui vérifie si la connexion au magasin Azure App Configuration ou aux magasins est saine. Si elle est activée pour chaque magasin, elle donne l’une des valeurs d’état suivantes :

• UP : la dernière connexion a réussi.
• DOWN - La dernière connexion a entraîné un code d’erreur non-200. Cet état peut être dû à des problèmes allant des informations d’identification arrivant à expiration à un problème de service. La bibliothèque cliente retente automatiquement de se connecter au magasin à l’intervalle d’actualisation suivant.
• NOT LOADED : le magasin de configuration est répertorié dans le fichier de configuration local, mais le magasin de configuration n’a pas été chargé à partir du fichier au démarrage. Le magasin de configurations est désactivé dans le fichier de configuration ou la configuration ou les configurations n’ont pas pu être chargées au démarrage pendant que la fail-fast configuration du magasin a été définie falsesur .

Vous pouvez activer l’indicateur d’intégrité en définissant management.health.azure-app-configuration.enabled=true.

Personnalisation du client

La bibliothèque App Configuration utilise le Kit de développement logiciel (SDK) Azure pour Java pour la connexion à Azure App Configuration et Azure Key Vault. Deux interfaces et ConfigurationClientCustomizer SecretClientCustomizer, sont fournies pour modifier les clients. Chaque interface a une customize méthode qui prend dans son générateur respectif ainsi que la String valeur de l’URI pour lequel le client est configuré, comme indiqué dans les définitions d’interface suivantes :

public interface ConfigurationClientCustomizer {
    public void setup(ConfigurationClientBuilder builder, String endpoint);
}

public interface SecretClientCustomizer {
    public void setup(SecretClientBuilder builder, String endpoint);
}

Ces interfaces permettent la personnalisation du client HTTP et de ses configurations. L’exemple suivant remplace la valeur par défaut HttpClient par une autre qui utilise un proxy pour tout le trafic dirigé vers App Configuration et Key Vault.

Remarque

Les ConfigurationClientBuilder paramètres sont SecretClientBuilder déjà configurés pour être utilisés lors de leur passage.customize Toutes les modifications apportées aux clients, y compris les informations d’identification et la stratégie de nouvelle tentative, remplacent celles déjà en place.

Vous pouvez également effectuer cette configuration à l’aide de la configuration d’Azure Spring Cloud.

public class CustomClient implements ConfigurationClientCustomizer, SecretClientCustomizer {

    @Override
    public void customize(ConfigurationClientBuilder builder, String endpoint) {
        builder.httpClient(buildHttpClient());
    }

    @Override
    public void customize(SecretClientBuilder builder, String endpoint) {
        builder.httpClient(buildHttpClient());
    }

    private HttpClient buildHttpClient() {
        String hostname = System.getProperty("https.proxyHosts");
        String portString = System.getProperty("https.proxyPort");
        int port = Integer.valueOf(portString);

        ProxyOptions proxyOptions = new ProxyOptions(ProxyOptions.Type.HTTP,
                new InetSocketAddress(hostname, port));
        return new NettyAsyncHttpClientBuilder()
                .proxy(proxyOptions)
                .build();
    }

}