Stöd för appkonfiguration

I den här artikeln beskrivs Azure App Configuration-biblioteket för Spring Cloud. Det här biblioteket läser in konfigurationer och funktionsflaggor från Azure App Configuration Service. Biblioteket genererar abstraktioner PropertySource som matchar de abstraktioner som redan genererats av Spring-miljön, till exempel miljövariabler, kommandoradskonfigurationer, lokala konfigurationsfiler och så vidare.

Spring är ett programramverk med öppen källkod som utvecklats av VMware och som ger en förenklad, modulär metod för att skapa Java-program. Spring Cloud Azure är ett projekt med öppen källkod som ger sömlös Spring-integrering med Azure-tjänster.

Förutsättningar

• En Azure-prenumeration – skapa en kostnadsfritt.
• Java Development Kit (JDK) version 8 eller senare.
• Apache Maven
• Azure CLI

Konfigurera appkonfigurationsarkivet

Använd följande kommando för att skapa ditt Azure App Configuration Store:

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

Det här kommandot skapar ett nytt, tomt konfigurationsarkiv. Du kan ladda upp dina konfigurationer med hjälp av följande importkommando:

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

Bekräfta konfigurationerna innan du läser in dem. Du kan ladda upp YAML-filer genom att ändra formatet till YAML. Prefixfältet är viktigt eftersom det är standardprefixet som läses in av klientbiblioteket.

Biblioteksanvändning

Om du vill använda funktionen i ett program kan du skapa den som ett Spring Boot-program. Det enklaste sättet att lägga till beroendet är med Spring Boot-startprogrammet com.azure.spring:spring-cloud-azure-starter-appconfiguration-config. I följande exempel pom.xml fil används 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.19.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>

Kommentar

Om du använder Spring Boot 2.x måste du ange spring-cloud-azure-dependencies versionen till 4.19.0. Mer information om vilken version som används för den här strukturlistan finns i Vilken version av Spring Cloud Azure ska jag använda.

I följande exempel visas ett grundläggande Spring Boot-program med appkonfiguration:

@SpringBootApplication
@RestController
public class Application {

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

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

I det här exemplet innehåller filen bootstrap.properties följande rad:

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

CONFIG_STORE_CONNECTION_STRINGär en miljövariabel med anslutningssträng till Azure App Configuration Store. Du kan komma åt anslutningssträng med hjälp av följande kommando:

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

Kommentar

Microsoft rekommenderar att du använder det säkraste tillgängliga autentiseringsflödet. Det autentiseringsflöde som beskrivs i den här proceduren, till exempel för databaser, cacheminnen, meddelanden eller AI-tjänster, kräver en mycket hög grad av förtroende för programmet och medför risker som inte finns i andra flöden. Använd endast det här flödet när säkrare alternativ, till exempel hanterade identiteter för lösenordslösa eller nyckellösa anslutningar, inte är genomförbara. För lokala datoråtgärder föredrar du användaridentiteter för lösenordslösa eller nyckellösa anslutningar.

Om inga konfigurationer har angetts läses som standard konfigurationerna som börjar med /application/ in med en standardetikett (No Label) på om inte en Spring-profil har angetts, i vilket fall standardetiketten är din Spring-profil. Eftersom arkivet är tomt läses inga konfigurationer in, men Azure App Configuration Property Source genereras fortfarande.

En egenskapskälla med namnet /application/https://<name-of-your-store>.azconfig.io/ skapas som innehåller egenskaperna för det arkivet. Etiketten som används i begäran läggs till i slutet av namnet. Om ingen etikett har angetts visas tecknet \0 som ett tomt utrymme.

Inläsningskonfiguration

Biblioteket stöder inläsning av ett eller flera appkonfigurationslager. I den situation där en nyckel dupliceras i flera butiker resulterar inläsningen av alla butiker i konfigurationen för de högsta prioritetslager som läses in. Den sista vinner. Den här processen illustreras i följande exempel:

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

I exemplet, om både det första och andra arkivet har samma konfiguration, har konfigurationen i det andra arkivet högsta prioritet och den sista vinner.

Kommentar

Du kan använda Azure App Configuration-inställningar som alla andra Spring-konfigurationer. Mer information finns i Grundläggande funktioner i Spring Boot-dokumentationen eller Snabbstart: Skapa en Java Spring-app med Azure App Configuration.

Välja konfigurationer

Konfigurationer läses in av deras nyckel och etikett. Som standard läses de konfigurationer som börjar med nyckeln /application/ in. Standardetiketten är ${spring.profiles.active}. Om ${spring.profiles.active} inte har angetts läses konfigurationer med null etiketten in. Etiketten null visas som (No Label) i Azure Portal.

Du kan konfigurera de konfigurationer som läses in genom att välja olika nyckel- och etikettfilter, som du ser i följande exempel:

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

Egenskapen key-filter stöder följande filter:

Nyckelfilter	Effekt
*	Matchar valfri nyckel.
abc	Matchar en nyckel med namnet abc.
abc*	Matchar nyckelnamn som börjar med abc.
abc,xyz	Matchar nyckelnamn abc eller xyz. Begränsat till fem kommaavgränsade värden.

Egenskapen label-filter stöder följande filter:

Etikett	Description
*	Matchar alla etiketter, inklusive \0.
\0	Matchar null etiketter som visas som (No Label) i Azure Portal.
1.0.0	Matchar etiketten 1.0.0 exakt.
1.0.*	Matchar etiketter som börjar med 1.0.*.
,1.0.0	Matchar etiketter null och 1.0.0. Begränsat till fem kommaavgränsade värden.

Om du använder YAML med etikettfilter och du måste börja med nullmåste etikettfiltret omges av enkla citattecken, som du ser i följande exempel:

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

Kommentar

Du kan inte kombinera * med , i filter. I så fall måste du använda ytterligare ett select-värde.

Fjäderprofiler

Som standard spring.profiles.active anges som standard label-filter för alla valda konfigurationer. Du kan åsidosätta den här funktionen med hjälp label-filterav . Du kan använda Spring Profiles i label-filter med hjälp ${spring.profiles.active}av , som du ser i följande exempel:

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

I den första label-filterläses alla konfigurationer med null etiketten in, följt av alla konfigurationer som matchar Spring Profiles. Spring Profiles har prioritet framför konfigurationerna null eftersom de är i slutet.

I den andra label-filterläggs strängen _local till i slutet av Spring Profiles, men bara till den sista Spring-profilen.

Inaktiverade butiker

Med hjälp av konfigurationen spring.cloud.azure.appconfiguration.enabledkan du inaktivera inläsning för alla konfigurationslager. Med konfigurationen spring.cloud.azure.appconfiguration.stores[0].enabled kan du inaktivera ett enskilt arkiv.

Förutom att inaktivera butiker kan du konfigurera att butiker ska inaktiveras om de inte läses in. För den här konfigurationen använder du spring.cloud.azure.appconfiguration.stores[0].fail-fast. När fail-fast är inaktiverat genom att ställa in det på false, resulterar ett RuntimeException resultat i att programarkivet inaktiveras utan konfigurationer från det läses in. Om ett konfigurationsarkiv är inaktiverat vid start kontrolleras det inte för ändringar vid uppdatering. Det går inte heller att läsa in värden från den om konfigurationerna uppdateras.

Om ett fel som resulterar i ett RuntimeException inträffar under en uppdateringskontroll eller vid försök att läsa in konfigurationer igen avslutas uppdateringsförsöket och görs ett nytt försök efter att refresh-interval det har passerat.

Autentisering

Biblioteket stöder alla former av identiteter som stöds av Azure Identity Library. Du kan utföra autentisering via konfiguration för anslutningssträng och hanterad identitet.

Kommentar

Microsoft rekommenderar att du använder det säkraste tillgängliga autentiseringsflödet. Det autentiseringsflöde som beskrivs i den här proceduren, till exempel för databaser, cacheminnen, meddelanden eller AI-tjänster, kräver en mycket hög grad av förtroende för programmet och medför risker som inte finns i andra flöden. Använd endast det här flödet när säkrare alternativ, till exempel hanterade identiteter för lösenordslösa eller nyckellösa anslutningar, inte är genomförbara. För lokala datoråtgärder föredrar du användaridentiteter för lösenordslösa eller nyckellösa anslutningar.

Connection string

Autentisering via anslutningssträng är det enklaste formuläret att konfigurera. Du kan komma åt ett butiks anslutningssträng med hjälp av följande kommando:

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

Du kan sedan ange spring.cloud.azure.appconfiguration.stores[0].connection-string egenskapen till anslutningssträng. Vi rekommenderar starkt att du ställer in anslutningssträng i den lokala konfigurationsfilen till ett platshållarvärde som mappar till en miljövariabel. Med den här metoden kan du undvika att lägga till anslutningssträng i källkontrollen.

Azure-konfiguration för Spring Cloud

Du kan använda Spring Cloud Azure-konfigurationen för att konfigurera biblioteket. Du kan använda följande egenskaper för att konfigurera biblioteket:

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

När endast slutpunkten har angetts använder klientbiblioteket StandardAzureCredential för att autentisera. DefaultAzureCredential Använder följande metoder för att autentisera:

• Miljöautentiseringsuppgifter
• Autentiseringsuppgifter för hanterad identitet
• Cli-autentiseringsuppgifter för Azure Developer
• IntelliJ-autentiseringsuppgifter
• Azure CLI-autentiseringsuppgifter
• Azure PowerShell-autentiseringsuppgifter

Du måste tilldela en identitet, till exempel en systemtilldelad identitet för att läsa konfigurationer. Du kan skapa den här tilldelningen med hjälp av följande kommando:

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>

Kommentar

Du kan bara definiera en autentiseringsmetod per slutpunkt: anslutningssträng, användartilldelad identitet eller tokenautentiseringsuppgifter. Om du behöver blanda och matcha kan du använda ConfigurationClientCustomizer för att ändra butiker som använder en annan metod.

Kommentar

Microsoft rekommenderar att du använder det säkraste tillgängliga autentiseringsflödet. Det autentiseringsflöde som beskrivs i den här proceduren, till exempel för databaser, cacheminnen, meddelanden eller AI-tjänster, kräver en mycket hög grad av förtroende för programmet och medför risker som inte finns i andra flöden. Använd endast det här flödet när säkrare alternativ, till exempel hanterade identiteter för lösenordslösa eller nyckellösa anslutningar, inte är genomförbara. För lokala datoråtgärder föredrar du användaridentiteter för lösenordslösa eller nyckellösa anslutningar.

Geo-replikering

Biblioteket stöder geo-replikeringsfunktionen i Azure App Configuration. Med den här funktionen kan du replikera dina data till andra platser. Den här funktionen är användbar för hög tillgänglighet och haveriberedskap.

Varje replik som du skapar har en dedikerad slutpunkt. Om ditt program finns i flera geolokaliseringar kan du uppdatera varje distribution av ditt program på en plats för att ansluta till repliken närmare den platsen, vilket hjälper till att minimera nätverksfördröjningen mellan programmet och appkonfigurationen. Eftersom varje replik har sin separata kvot för begäran hjälper den här konfigurationen även programmets skalbarhet när den växer till en distribuerad tjänst i flera regioner.

Redundansväxlingen kan inträffa om biblioteket observerar något av följande villkor:

• Tar emot svar med statuskod för tjänsten som inte är tillgänglig (HTTP 500 eller senare) från en slutpunkt.
• Upplever problem med nätverksanslutningen.
• Begäranden begränsas (HTTP-statuskod 429).

Skapa ett konfigurationslager med geo-replikering

Om du vill skapa en replik av konfigurationsarkivet kan du använda Azure CLI eller Azure Portal. I följande exempel används Azure CLI för att skapa en replik i regionen USA, östra 2:

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

Använda konfigurationslagerrepliken

När du har skapat en replik kan du använda den i ditt program. Precis som ursprungsarkivet kan du ansluta till din replik med hjälp av Microsoft Entra-ID eller en anslutningssträng.

Kommentar

Microsoft rekommenderar att du använder det säkraste tillgängliga autentiseringsflödet. Det autentiseringsflöde som beskrivs i den här proceduren, till exempel för databaser, cacheminnen, meddelanden eller AI-tjänster, kräver en mycket hög grad av förtroende för programmet och medför risker som inte finns i andra flöden. Använd endast det här flödet när säkrare alternativ, till exempel hanterade identiteter för lösenordslösa eller nyckellösa anslutningar, inte är genomförbara. För lokala datoråtgärder föredrar du användaridentiteter för lösenordslösa eller nyckellösa anslutningar.

Microsoft Entra-ID (rekommenderas)

Om du vill använda Microsoft Entra-ID för att ansluta till din replik måste du visa en lista över endpoints konfigurationsarkivinstanserna, som du ser i följande exempel:

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

Du kan lista så många slutpunkter som du har repliker. Biblioteket försöker ansluta till slutpunkterna i den ordning de visas. Om biblioteket inte kan ansluta till en replik försöker det nästa i listan. När en tidsperiod har passerat försöker biblioteket återansluta till de önskade slutpunkterna.

anslutningssträng

Om du vill använda en anslutningssträng för att ansluta till repliken måste du visa en lista över connectionStrings konfigurationsarkivinstanserna, som du ser i följande exempel:

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]

Du kan lista så många anslutningssträng som du har repliker. Biblioteket försöker ansluta till anslutningssträng i den ordning de visas. Om biblioteket inte kan ansluta till en replik försöker det nästa i listan. När en tidsperiod har passerat försöker biblioteket återansluta till önskad anslutningssträng.

Nyckelvärden

Azure App Configuration stöder flera typer av nyckelvärden, varav vissa har inbyggda specialfunktioner. Azure App Configuration har inbyggt stöd för JSON-innehållstypen, Spring-platshållare och Key Vault-referenser.

Platshållare

Biblioteket stöder konfigurationer med ${}miljöplatshållare i -format. När du refererar till en Azure App Configuration-nyckel med en platshållare tar du bort prefix från referensen. Till exempel /application/config.message refereras till som ${config.message}.

Kommentar

Prefixet som tas bort matchar värdet spring.cloud.azure.appconfiguration.stores[0].selects[0].key-filter.

JSON

Konfigurationer som har en innehållstyp application/json bearbetas som JSON-objekt. Med den här funktionen kan du mappa en konfiguration till ett komplext objekt i en @ConfigurationProperties. Tänk till exempel på JSON-nyckeln /application/config.colors med följande värde:

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

Den här nyckeln mappar till följande kod:

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

    private Map<String, Color> colors;

}

Key Vault-referenser

Azure App Configuration och dess bibliotek stöder referens av hemligheter som lagras i Key Vault. I App Configuration kan du skapa nycklar med värden som mappas till hemligheter som lagras i ett Key Vault. Hemligheter lagras säkert i Key Vault, men kan nås på samma sätt som andra konfigurationer när de har lästs in.

Ditt program använder klientprovidern för att hämta Key Vault-referenser, precis som för andra nycklar som lagras i App Configuration. Eftersom klienten identifierar nycklarna som Key Vault-referenser har de en unik innehållstyp och klienten ansluter till Key Vault för att hämta sina värden åt dig.

Kommentar

Key Vault tillåter endast att hemligheter hämtas en i taget, så varje Key Vault-referens som lagras i App Configuration resulterar i en hämtning mot Key Vault.

Skapa Key Vault-referenser

Du kan skapa en Key Vault-referens i Azure Portal genom att gå till Konfigurationsutforskaren>Skapa>Key Vault-referens. Du kan sedan välja en hemlighet att referera till från någon av de Nyckelvalv som du har åtkomst till. Du kan också skapa godtyckliga Key Vault-referenser från fliken Indata. I Azure Portal anger du en giltig URI.

Du kan också skapa en Key Vault-referens via Azure CLI med hjälp av följande kommando:

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

Du kan skapa alla hemliga identifierare via Azure CLI. Hemliga identifierare kräver bara formatet {vault}/{collection}/{name}/{version?} där versionsavsnittet är valfritt.

Använda Key Vault-referenser

Du kan använda Spring Cloud Azure-konfigurationen för att konfigurera biblioteket. Du kan använda samma autentiseringsuppgifter som används för att ansluta till App Configuration för att ansluta till Azure Key Vault.

Lösa icke-Key Vault-hemligheter

Appkonfigurationsbiblioteket innehåller en metod för att lokalt lösa hemligheter som inte har ett nyckelvalv associerat med dem. Den här lösningen görs via KeyVaultSecretProvider. KeyVaultSecretProvider Anropas när en TokenCredential inte anges för en Key Vault-referens. URI:n för Key Vault-referensen tillhandahålls och det returnerade värdet blir hemlighetens värde.

Varning

Användningen av en KeyVaultSecretProvider åsidosätter den automatiska användningen av den systemtilldelade hanterade identiteten. Om du vill använda båda måste du använda KeyVaultCredentialProvider och returnera null för de URI:er som behöver matchas.

public class MySecretProvider implements KeyVaultSecretProvider {

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

}

Funktionshantering

Funktionshantering är ett sätt för Spring Boot-program att dynamiskt komma åt innehåll. Funktionshantering har olika funktioner, till exempel följande:

• Funktionsflaggor som kan aktivera eller inaktivera innehåll
• Funktionsfilter för mål när innehåll visas
• Anpassade funktionsfilter
• Funktionsportar för dynamisk aktivering av slutpunkter

Du kan aktivera funktionsflaggor via följande konfiguration:

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

Aktiverade funktionsflaggor läses in i Spring-konfigurationssystemet med prefixet feature-management. Du kan också registrera funktionsflaggor i den lokala konfigurationsfilen. Mer information finns i avsnittet Funktionsflaggadeklaration.

Det enklaste sättet att använda funktionshantering är att använda biblioteken spring-cloud-azure-feature-management och spring-cloud-azure-feature-management-web . Skillnaden mellan de två biblioteken är att spring-cloud-azure-feature-management-web det krävs ett beroende av biblioteken spring-web och spring-webmvc för att lägga till fler funktioner, till exempel funktionsportar.

Du kan aktivera funktionsflaggor med hjälp av nyckel-/etikettfilter. Som standard tilldelas en null etikett, som ses som (No Label), . Du kan konfigurera funktionsflaggor som läses in genom att ange ett etikettfilter, enligt följande exempel:

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

Grunderna för funktionshantering

Funktionsflaggor

Funktionsflaggor består av två delar: ett namn och en lista över funktionsfilter som används för att aktivera funktionen. Funktionsflaggor kan antingen ha ett booleskt tillstånd av på/av, eller så kan de ha en lista med funktionsfilter. Funktionsflaggor utvärderar funktionsfilter tills en returnerar true. Om inget funktionsfilter returnerar truereturnerar falsefunktionsflaggan .

Funktionsfilter

Funktionsfilter definierar ett scenario för när en funktion ska aktiveras. Funktionsfilter utvärderas synkront.

Funktionshanteringsbiblioteket innehåller fyra fördefinierade filter: AlwaysOnFilter, PercentageFilter, TimeWindowFilter och TargetingFilter.

Du kan skapa anpassade funktionsfilter. Du kan till exempel använda ett funktionsfilter för att ge en anpassad upplevelse för kunder som använder en Microsoft Edge-webbläsare. Du kan anpassa funktionerna i det här funktionsfiltret, till exempel för att visa en specifik rubrik för Microsoft Edge-webbläsarpubliken.

Deklaration av funktionsflagga

Funktionshanteringsbiblioteket stöder Azure App Configuration tillsammans med application.yml eller bootstrap.yml som källor för funktionsflaggor. Här är ett exempel på det format som används för att konfigurera funktionsflaggor i en application.yml fil:

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

Det här exemplet har följande funktionsflaggor:

• feature-t är inställt på false. Den här inställningen returnerar alltid funktionsflaggans värde.
• feature-u används med funktionsfilter. Dessa filter definieras under egenskapen enabled-for . I det här fallet feature-u har ett funktionsfilter som heter Random, vilket inte kräver någon konfiguration, så endast namnegenskapen krävs.
• feature-v anger ett funktionsfilter med namnet TimeWindowFilter. Det här funktionsfiltret kan skickas parametrar som ska användas som konfiguration. I det här exemplet skickas en TimeWindowFilter, i start- och sluttiderna då funktionen är aktiv.
• feature-w används för AlwaysOnFilter, som alltid utvärderas till true. Fältet evaluate används för att stoppa utvärderingen av funktionsfiltren och resulterar i att funktionsfiltret alltid returnerar false.

Utvärdera funktionsflaggor

Biblioteket spring-cloud-azure-feature-management tillhandahåller FeatureManager för att avgöra om en funktionsflagga är aktiverad. FeatureManager ger ett asynkront sätt att kontrollera flaggans tillstånd.

spring-cloud-azure-feature-management-web, tillsammans med att tillhandahålla FeatureManager, innehåller FeatureManagerSnapshot, som cachelagrar tillståndet för tidigare utvärderade funktionsflaggor i @RequestScope för att garantera att alla begäranden returnerar samma värde. Dessutom tillhandahåller @FeatureGatewebbbiblioteket , som antingen kan blockera eller omdirigera webbbegäranden till olika slutpunkter.

Kontroll av funktionsflagga

FeatureManager är en @Bean som kan matas @Autowired in eller matas in i @Component typobjekt. FeatureManager har en metod isEnabled som returnerar dess tillstånd när namnet på en funktionsflagga skickas.

@Autowired
FeatureManager featureManager;

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

Kommentar

FeatureManger har också en asynkron version av isEnabled som heter isEnabledAsync.

Om du inte har konfigurerat funktionshantering eller om funktionsflaggan inte finns isEnabled returnerar falsealltid . Om en befintlig funktionsflagga har konfigurerats med ett okänt funktionsfilter genereras en FilterNotFoundException . Du kan ändra det här beteendet så att det återgår false genom att fail-fast konfigurera till false. I följande tabell beskrivs fail-fast:

Name	beskrivning	Obligatoriskt	Standardvärde
spring.cloud.azure.feature.management.fail-fast	Om ett undantag inträffar genereras en RuntimeException . Om den här egenskapen är inställd på falsereturnerar den isEnabled false i stället.	Nej	true

Den enda skillnaden mellan FeatureManagerSnapshot och FeatureManager är cachelagring av resultat i @RequestScope.

Funktionsgrind

Med webbbiblioteket för funktionshantering kan du kräva att en viss funktion är aktiverad för att köra en slutpunkt. Du kan konfigurera det här kravet med hjälp av kommentaren @FeatureGate , som du ser i följande exempel:

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

Du kan bara komma åt featureT slutpunkten om "feature-t" är aktiverat.

Inaktiverad åtgärdshantering

När en slutpunkt blockeras eftersom den funktion som anges är inaktiverad DisabledFeaturesHandler anropas. Som standard returneras en HTTP 404. Du kan åsidosätta det här beteendet genom att implementera DisabledFeaturesHandler, enligt följande exempel:

@Component
public class MyDisabledFeaturesHandler implements DisabledFeaturesHandler {

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

}

Routning

Vissa vägar kan exponera programfunktioner som är gated av funktioner. Om en funktion är inaktiverad kan du omdirigera dessa vägar till en annan slutpunkt, som du ser i följande exempel:

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

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

Inbyggda funktionsfilter

Det finns några funktionsfilter som medföljer spring-cloud-azure-feature-management paketet. Dessa funktionsfilter läggs inte till automatiskt, men du kan konfigurera dem i en @Configuration.

AlwaysOnFilter

Det här filtret returnerar truealltid . Ett användningsexempel finns i avsnittet funktionsflaggadeklaration.

PercentageFilter

Varje gång en användare gör en begäran kan utvärderingen av PercentageFilter returnera ett annat resultat. Du kan kringgå den här inkonsekvensen FeatureManagementSnapshotmed hjälp av , som cachelagrar resultatet av funktionsflaggan per användare. Den här funktionen säkerställer att en användare har en konsekvent upplevelse, även om de måste skicka begäran igen.

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

TimeWindowFilter

Det här filtret ger möjlighet att aktivera en funktion baserat på ett tidsfönster. Om du bara Endanger betraktas funktionen som aktiverad fram till dess. Om du bara Startanger betraktas funktionen på vid alla tidpunkter efter den tiden. Om du anger båda betraktas funktionen som giltig mellan de två gångerna.

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

Det här filtret ger möjlighet att aktivera en funktion för en målgrupp. En detaljerad förklaring av mål finns i avsnittet om mål. Filterparametrarna innehåller ett målgruppsobjekt som beskriver användare, grupper och en standardprocent av användarbasen som ska ha åtkomst till funktionen. För varje gruppobjekt som visas i målgruppen krävs en procentandel som definierar procentandelen av gruppens medlemmar som har åtkomst till funktionen. En användare har funktionen aktiverad i följande fall:

• Användaren anges direkt i användaravsnittet.
• Användaren ingår i procentandelen för någon av gruppdistributionerna.
• Användaren hamnar i standardprocenten för distribution.

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

Anpassade funktionsfilter

Genom att skapa ett anpassat funktionsfilter kan du aktivera funktioner baserat på kriterier som du definierar. Om du vill skapa ett anpassat funktionsfilter måste du implementera FeatureFilter gränssnittet. FeatureFilter har en enda metod evaluate. När en funktion anger att den kan aktiveras med ett funktionsfilter evaluate anropas metoden. Om evaluate returnerar trueinnebär det att funktionen ska vara aktiverad. Om den returnerar falsefortsätter den att utvärdera funktionsfilter tills en returnerar true. Om alla filter returneras falseär funktionen inaktiverad.

Funktionsfilter definieras som Spring Beans, så de definieras antingen som @Component eller definieras i en @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;
    }

}

Parameteriserade funktionsfilter

Vissa funktionsfilter kräver parametrar för att avgöra om en funktion ska aktiveras. Ett webbläsarfunktionsfilter kan till exempel aktivera en funktion för en viss uppsättning webbläsare. Du kanske vill ha en funktion aktiverad för Microsoft Edge- och Chrome-webbläsare, men inte Firefox. Om du vill konfigurera den här situationen kan du utforma ett funktionsfilter för att förvänta dig parametrar. Dessa parametrar anges i funktionskonfigurationen och i koden och skulle vara tillgängliga via parametern FeatureFilterEvaluationContext evaluate. FeatureFilterEvaluationContext har en egenskap parameters, som är en HashMap<String, Object>.

Sök mål

Inriktning är en strategi för funktionshantering som gör det möjligt för utvecklare att successivt distribuera nya funktioner till sin användarbas. Strategin bygger på konceptet att rikta in sig på en uppsättning användare som kallas målgruppen. En målgrupp består av specifika användare, grupper och en angiven procentandel av hela användarbasen. De grupper som ingår i målgruppen kan delas upp ytterligare i procent av deras totala medlemmar.

Följande steg visar ett exempel på en progressiv distribution för en ny betafunktion:

1. Enskilda användare Jeff och Alicia beviljas åtkomst till betaversionen.
2. En annan användare, Mark, ber att få anmäla sig och inkluderas.
3. Tjugo procent av en grupp som kallas "Ring1"-användare ingår i betaversionen.
4. Antalet "Ring1"-användare som ingår i betaversionen ökas till 100 procent.
5. Fem procent av användarbasen ingår i betaversionen.
6. Distributionsprocenten ökar till 100 procent och funktionen distribueras helt.

Den här strategin för att lansera en funktion är inbyggd i biblioteket via det inkluderade funktionsfiltret TargetingFilter .

Målinriktning i ett program

Ett exempel på ett webbprogram som använder målfunktionsfiltret är tillgängligt i exempelprojektet.

Om du vill börja använda TargetingFilter i ett program måste du lägga till det som ett @Bean som alla andra funktionsfilter. TargetingFilter förlitar sig på en annan @Bean som ska läggas till i programmet TargetingContextAccessor. Gör TargetingContextAccessor det möjligt att definiera den aktuella som TargetingContext ska användas för att definiera aktuellt användar-ID och grupper, som du ser i följande exempel:

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

}

Mål för utvärderingsalternativ

Det finns alternativ för att anpassa hur målutvärdering utförs i en viss TargetingFilter. Du kan ange en valfri parameter, TargetingEvaluationOptions, under TargetingFilter skapandet.

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

Konfigurationsuppdatering

Om du aktiverar konfigurationsuppdatering för dina konfigurationer kan du hämta de senaste värdena från appkonfigurationsarkivet eller -butikerna utan att behöva starta om programmet.

För att aktivera uppdatering måste du aktivera övervakning tillsammans med övervakningsutlösare. En övervakningsutlösare är en nyckel med en valfri etikett som kontrolleras efter värdeändringar för att utlösa uppdateringar. Värdet för övervakningsutlösaren kan vara valfritt värde, så länge det ändras när en uppdatering behövs.

Kommentar

Alla åtgärder som ändrar ETag för en övervakningsutlösare orsakar en uppdatering, till exempel en ändring av innehållstyp.

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

Om du vill utlösa en konfigurationsuppdatering ändrar du värdet för en nyckel i konfigurationsarkivet. Uppdatera sedan en av klocknycklarna till ett nytt värde. Den här ändringen utlöser skapandet av en logg. Om du till exempel ändrar värdet /application/config.message för utlöses följande loggmeddelande:

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

När programmet har genererat loggen uppdateras alla @Beani uppdateringsomfånget.

Kommentar

Som standard @ConfigurationProperties ingår kommenterade bönor i det här omfånget.

Pull-baserad uppdatering

App Configuration Spring-biblioteken stöder möjligheten att regelbundet kontrollera ett uppdateringsintervall för ändringar som gjorts i övervakningsutlösarna. Som standard är uppdateringsintervallet inställt på 30 sekunder. När uppdateringsintervallet har passerat kontrolleras alla utlösare i det angivna arkivet för ändringar. Ändringar i nyckeln gör att en uppdatering utlöses. Eftersom biblioteken integreras med Spring Refresh-systemet läser alla uppdateringar in alla konfigurationer från alla butiker igen. Du kan ange uppdateringsintervallet till ett intervall som är längre än 1 sekund. De enheter som stöds för uppdateringsintervallet är s, m, hoch d för sekunder, minuter, timmar respektive dagar. I följande exempel anges uppdateringsintervallet till 5 minuter:

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

Automatiserade

När du använder spring-cloud-azure-appconfiguration-config-web biblioteket söker programmet automatiskt efter en uppdatering när en servlet-begäran inträffar, särskilt ServletRequestHandledEvent. Det vanligaste sättet att skicka den här händelsen är av begäranden till slutpunkter i en @RestController.

Manuell

I program som endast spring-cloud-azure-appconfiguration-configanvänder , till exempel konsolprogram, kan du manuellt utlösa en uppdatering genom att anropa AppConfigurationRefreshmetoden 's refreshConfiguration . AppConfigurationRefresh är en @Bean som du kan mata in i valfri @Component.

Eftersom biblioteket använder Spring-konfigurationssystemet orsakar utlösande av en uppdatering dessutom en uppdatering av alla dina konfigurationer, inte bara en ny inläsning av dem från Azure App Configuration Store.

Push-baserad uppdatering

Du kan konfigurera biblioteket så att det spring-cloud-azure-appconfiguration-config-web tar emot push-meddelanden från Azure App Configuration Store för att uppdatera dina konfigurationsvärden. Du kan konfigurera den här konfigurationen via en Azure Event Grid Web Hook, som du kan konfigurera för att skicka meddelanden om ändringar till angivna nycklar. Genom att lägga till Spring Actuator-biblioteket som ett beroende kan du exponera App Configurations uppdateringsslutpunkter. Det finns två olika slutpunkter: appconfiguration-refresh och appconfiguration-refresh-bus. Dessa slutpunkter fungerar på samma sätt som deras motsvarigheter refresh och refresh-bus, där appkonfigurationsslutpunkterna förfaller uppdateringsintervallet i stället för att framtvinga en uppdatering när de tas emot. Du kan fortfarande använda refresh och refresh-bus, men du kan inte ansluta dem direkt till Azure Event Grid med en webbhook eftersom de kräver ett svar i installationen.

Egenskapen appconfiguration-refresh förfaller uppdateringsintervallet, så det återstående uppdateringsintervallet väntar inte innan nästa uppdateringskontroll. Egenskapen appconfiguration-refresh-bus skickar ett meddelande till en ansluten meddelandetjänst, till exempel Azure Service Bus, för att meddela alla instanser av ett program att uppdatera. I båda fallen upphör den inte helt att gälla vid uppdateringsintervallet, men av med en liten jittermängd. Detta jitter säkerställer att varje instans av ditt program inte försöker uppdatera på samma gång.

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

Förutom att exponera uppdateringsslutpunkterna har en obligatorisk frågeparameter lagts till för säkerhet. Inget tokennamn eller värde anges som standard, men du måste ange ett för att använda slutpunkterna, som du ser i följande exempel:

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]

Konfigurera webbkrokar

Om du vill konfigurera en webbkrok öppnar du Azure App Configuration Store och öppnar Händelser från navigeringsmenyn. Välj sedan Händelseprenumeration. Ange namnet på händelsen och välj den slutpunktstyp som ska vara Web Hook. Om du väljer Web Hook visas ett slutpunktsalternativ . Välj Välj en slutpunkt. Slutpunkten bör se ut som i följande exempel: https://www.myaplication.com/actuator/appconfiguration-refresh?myTokenName=mySecret.

Confirm Selection skickar ett installationsmeddelande till den angivna URI:n och förväntar sig ett svar. Om inget svar returneras misslyckas installationen. Bibliotekskonfigurationen azure-spring-cloud-appconfiguration-web för slutpunkter returnerar rätt svar om Azure App Configuration Store har konfigurerats för programmet. Den här bekräftelsen kan skickas på andra sätt. Mer information om leverans av webbkrokar finns i Webhook-händelseleverans.

Kommentar

Den här verifieringen sker endast när slutpunkten skapas eller ändras.

Vi rekommenderar starkt att du konfigurerar filter eftersom annars utlöses en uppdatering efter varje nyckelskapande och ändring.

Framtvingad klientuppdatering

Du kan konfigurera biblioteket så att det framtvingar en uppdatering av alla konfigurationer med ett uppdateringsintervall. I följande tabell beskrivs egenskapen refresh-interval :

Name	beskrivning	Obligatoriskt	Standardvärde
spring.cloud.azure.appconfiguration.refresh-interval	Standardtiden mellan uppdateringarna. Är en Duration.	Nej	NULL

Uppdatering med spring.cloud.azure.appconfiguration.refresh-interval kontrollerar inte några konfigurerade klocknycklar. Den här egenskapen används för att se till att Key Vault-hemligheter hålls uppdaterade eftersom Azure App Configuration inte kan se när de uppdateras.

Eftersom Azure Key Vault lagrar det offentliga och privata nyckelparet för ett certifikat som en hemlighet, kan ditt program hämta valfritt certifikat som en Key Vault-referens i App Configuration. Eftersom certifikat måste roteras regelbundet måste klientprogram uppdateras lika ofta, vilket kan göras med hjälp av klientuppdateringsintervallet.

Uppdatering av funktionsflagga

Om både funktionsflaggor och övervakning är aktiverade anges uppdateringsintervallet för funktionsflaggor som standard till 30 sekunder. När uppdateringsintervallet har passerat kontrolleras alla funktionsflaggor i det angivna arkivet för ändringar. Ändringar i nyckeln gör att en uppdatering utlöses. Eftersom biblioteken integreras med Spring Refresh-systemet läser alla uppdateringar in alla konfigurationer från alla butiker igen. Du kan ange uppdateringsintervallet till ett intervall som är längre än 1 sekund. De enheter som stöds för uppdateringsintervallet är s, m, hoch d för sekunder, minuter, timmar respektive dagar. I följande exempel anges uppdateringsintervallet till 5 minuter:

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

Hälsoindikator

Klientbiblioteket levereras med en hälsoindikator som kontrollerar om anslutningen till Azure App Configuration Store eller -butikerna är felfri. Om det är aktiverat för varje arkiv, ger det något av följande statusvärden:

• UP – Den senaste anslutningen lyckades.
• DOWN – Den senaste anslutningen resulterade i en felkod som inte var 200. Den här statusen kan bero på problem som sträcker sig från autentiseringsuppgifter som upphör att gälla till ett tjänstproblem. Klientbiblioteket försöker automatiskt ansluta till arkivet igen vid nästa uppdateringsintervall.
• INTE INLÄST – Konfigurationsarkivet visas i den lokala konfigurationsfilen, men konfigurationsarkivet lästes inte in från filen vid start. Konfigurationsarkivet är inaktiverat i konfigurationsfilen eller konfigurationen eller konfigurationerna kunde inte läsas in vid start medan konfigurationen fail-fast för arkivet var inställd på false.

Du kan aktivera hälsoindikatorn genom att ange management.health.azure-app-configuration.enabled=true.

Klientanpassning

Appkonfigurationsbiblioteket använder Azure SDK för Java för att ansluta till Azure App Configuration och Azure Key Vault. Två gränssnitt och ConfigurationClientCustomizer SecretClientCustomizer, tillhandahålls för att ändra klienterna. Varje gränssnitt har en customize metod som tar in respektive byggare tillsammans med String värdet för den URI som klienten konfigureras för, enligt följande gränssnittsdefinitioner:

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

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

Dessa gränssnitt möjliggör anpassning av HTTP-klienten och dess konfigurationer. I följande exempel ersätts standardvärdet HttpClient med en annan som använder en proxy för all trafik som dirigeras till App Configuration och Key Vault.

Kommentar

Och ConfigurationClientBuilder SecretClientBuilder är redan konfigurerade för användning när de skickas till customize. Eventuella ändringar av klienterna, inklusive autentiseringsuppgifterna och återförsöksprincipen, åsidosätter de som redan finns.

Du kan också göra den här konfigurationen med hjälp av Azure-konfigurationen för 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();
    }

}