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 din Appkonfigurationsbutik

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

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 application.properties följande rad:

spring.config.import=azureAppConfiguration
spring.cloud.azure.appconfiguration.stores[0].endpoint=${CONFIG_STORE_ENDPOINT}

CONFIG_STORE_ENDPOINT är en miljövariabel med slutpunkts-URL:en till Azure App Configuration Store.

Anteckning

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, laddas som standard konfigurationerna som börjar med /application/ med standardetiketten (No Label) utom i det fall då en Spring-profil har angetts, då är standardetiketten din Spring-profil.

En egenskapskälla med namnet /application/https://<name-of-your-store>.azconfig.io/ skapas, och den innehåller egenskaperna för den butiken. 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.

Laddar konfiguration

Biblioteket stöder inläsning av en eller flera appkonfigurationslagringar. I den situation där en nyckel dupliceras i flera butiker vinner den sista.

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

Om båda butikerna i det här exemplet har samma konfigurationsnyckel har konfigurationen i det andra arkivet högsta prioritet.

Anteckning

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

Biblioteket läser in konfigurationer med hjälp av deras nyckel och etikett. Som standard läses de konfigurationer som börjar med nyckeln /application/ in. Standardetiketten är \0, som visas som (No Label) i Azure-portalen. Om en Spring-profil har angetts och ingen etikett har angetts är standardetiketten din Spring-profil, som är ${spring.profiles.active}.

Du kan konfigurera vilka konfigurationer som läses in genom att välja olika nyckel- och etikettfilter:

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	Beskrivning
*	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 vill läsa in konfigurationer utan etikett och fler konfigurationer med andra etiketter måste du inkludera en tom ,. Till exempel ,dev matchningar \0 och dev. I det här fallet omger du etikettfiltret med enkla citattecken. Med det här värdet kan du läsa in konfigurationen utan etikett först, följt av konfigurationer med specifika etiketter i samma filter:

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

Anteckning

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

När du använder * i etikettfiltret och flera konfigurationer med samma nyckel läses in läses de in i alfabetisk ordning och etiketten sist i alfabetisk ordning används.

Spring-profiler

Som standard anges spring.profiles.active som label-filter för alla valda konfigurationer. Du kan åsidosätta den här funktionen med hjälp av label-filter. Du kan använda Spring Profiles i label-filter med hjälp av ${spring.profiles.active}, 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äser biblioteket först in alla konfigurationer med \0 etiketten följt av alla konfigurationer som matchar Spring Profiles. Spring Profiles har prioritet framför konfigurationerna \0 eftersom de är i slutet.

I den andra label-filterläggs strängen _local till i slutet av springprofilerna, men bara till den sista Vårprofilen om det finns fler än en.

Inaktiverade butiker

Med hjälp av konfigurationen spring.cloud.azure.appconfiguration.enabled kan du inaktivera inläsning för alla konfigurationslager. Med konfigurationen spring.cloud.azure.appconfiguration.stores[0].enabled kan du inaktivera en enskild butik.

Anteckning

Om du använder hälsomått ser du fortfarande dina butiker i listan, men med värdet NOT LOADED. När du kontrollerar inlästa egenskapskällor visas de fortfarande i listan, men de innehåller inga värden. Det här beteendet beror på att egenskapen spring.config.import har angetts. Om azureAppConfiguration inte har angetts för spring.config.importvisas inga värden.

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.

Anteckning

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.

Anslutningssträng (rekommenderas inte)

Autentisering via anslutningssträng är det enklaste sättet att installera, men det rekommenderas inte. 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. När du använder den här metoden rekommenderar vi starkt att du anger anslutningssträngen 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.

Du måste tilldela den identitet som används 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>

Anteckning

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 ConfigurationClientBuilder för att använda olika metoder.

Anteckning

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 dedicerad endpunkt. 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.

Som standard identifierar biblioteket automatiskt alla repliker som finns för ett konfigurationsarkiv. När en begäran görs till det angivna arkivet och misslyckas försöker biblioteket automatiskt skicka begäran mot de tillgängliga replikerna igen.

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

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

När det angivna arkivet är online igen försöker biblioteket automatiskt skicka begäran mot det angivna arkivet igen.

Om du vill styra redundansbeteendet kan du manuellt ange en lista över butiker som ska användas för redundansväxling.

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

eller

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

Om alla angivna replikslutpunkter misslyckas försöker biblioteket ansluta till automatiskt identifierade repliker i det primära arkivet.

Du kan inaktivera replikering med inställningen spring.cloud.azure.appconfiguration.stores[0].replica-discovery-enabled=false.

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 East US 2.

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

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 platshållare för miljöer i ${}-stil. 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}.

Anteckning

Prefixet som tas bort matchar värdet spring.cloud.azure.appconfiguration.stores[0].selects[0].key-filter. Prefixet som trimmas kan ändras genom att ange ett värde för spring.cloud.azure.appconfiguration.stores[0].trim-key-prefix[0].

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 förblir säkra i Key Vault, men du kan komma åt dem på samma sätt som andra konfigurationer när du läser in appen.

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.

Anteckning

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 förfrågan till 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.

Du kan också skapa på SecretClientCustomizer samma sätt som du skapar en ConfigurationClientCustomizer för att tillhandahålla din egen autentiseringsmetod.

Lösa icke-Key Vault-hemligheter

Appkonfigurationsbiblioteket innehåller en metod för att åsidosätta lösningen för key vault-referenser. Du kan till exempel använda den för att lokalt lösa hemligheter i en utvecklingsmiljö. Detta beslut fattas genom KeyVaultSecretProvider. , KeyVaultSecretProviderom det tillhandahålls, anropas på varje key vault-referens. Om getSecret returnerar ett värde som inte är null används det som hemligt värde. Annars matchas Key Vault-referensen normalt.

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

Som standard läses alla funktionsflaggor med en \0 etikett, som ses som (No Label), in. 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 flera delar, inklusive ett namn och en lista över funktionsfilter som används för att aktivera funktionen. Funktionsflaggor kan antingen ha ett booleskt tillstånd på på eller av, eller så kan de ha en lista med funktionsfilter. Funktionsflaggor utvärderar funktionsfilter tills en returnerar true. Om inget funktionsfilter returnerar true, kommer funktionsflaggan att returnera false.

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 application.properties 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_flags:
  - id: feature-t
    enabled: false
  - id: feature-u
    conditions:
      client_filters:
      - name: Random
  - id: feature-v
    conditions:
      client_filters:
      - name: TimeWindowFilter
        parameters:
          Start: "Wed, 01 May 2019 13:59:59 GMT"
          End: "Mon, 01 July 2019 00:00:00 GMT"

  - id: feature-w
    evaluate: false
    conditions:
      client_filters:
      - 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 filterfunktionen kan ges parametrar för att användas som konfiguration. I det här exemplet skickas en TimeWindowFilter med start- och sluttiderna för när 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 @Autowired eller injiceras i objekt av typen @Component. 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
}

Anteckning

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

Utan konfiguration av funktionshantering eller när funktionsflaggan inte finns isEnabled returnerar falsealltid . Om en befintlig funktionsflagga har konfigurerats med ett okänt funktionsfilter, kastas 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:

Namn	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 isEnabledfalse 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.

Hantering av åtgärder inaktiverad

När en slutpunkt blockeras eftersom den funktion som anges är inaktiverad DisabledFeaturesHandler anropas. Som standardinställning 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 till automatiskt.

AlwaysOnFilter (AlltidPåFilter)

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

PercentageFilter (PercentageFilter)

Varje gång den kontrolleras 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 begäran.

feature-management:
  feature_flags:
  - name: feature-v
    conditions:
      client_filters:
      - name: PercentageFilter
        parameters:
          Value: 50

Tidsfönsterfilter

Det här filtret ger möjlighet att aktivera en funktion baserat på ett tidsfönster. Om du anger bara End anses funktionen vara aktiverad fram till dess. Om du bara anger Start anses funktionen vara på från och med den tidpunkten. Om du anger båda betraktas funktionen som giltig mellan de två gångerna.

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

Det här filtret stöder också återkommande tidsfönsterfilter. Den stöder både dagliga och veckovisa upprepningar, tillsammans med en förfallotid.

feature-management:
  feature_flags:
  - name: feature-v
    conditions:
      client_filters:
      - name: TimeWindowFilter
        parameters:
          Start: "Mon, 01 July 2019 00:00:00 GMT"
          End: "Mon, 01 July 2019 12:00:00 GMT"
          Recurrence:
            Pattern:
              Type: Weekly
              Interval: 1
              FirstDayOfWeek: Sunday
              DaysOfWeek:
              - Monday
              - Wednesday

Det här upprepningsmönstret inträffar varje vecka på måndag och onsdag från 00:00:00 GMT till 12:00:00 GMT och upphör inte att gälla.

feature-management:
  feature_flags:
  - name: feature-v
    conditions:
      client_filters:
      - name: TimeWindowFilter
        parameters:
          Start: "Mon, 01 July 2019 00:00:00 GMT"
          End: "Mon, 01 July 2019 12:00:00 GMT"
          Recurrence:
            Pattern:
              Type: Daily
              Interval: 2
            Range:
              Type: EndDate
              EndDate: "Fri, 15 Aug 2025 07:00:00 GMT"

Det här upprepningsmönstret inträffar varannan dag från 00:00:00 GMT till 12:00:00 GMT fram till slutdatumet.

Målgruppsfilter

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 den procentsats som ingår i någon av grupputrullningarna.
• Användaren hamnar i standardprocenten för distribution.

feature-management:
  feature_flags:
  - name: target
    conditions:
      client_filters:
      - 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 FeatureFilterEvaluationContextevaluate. FeatureFilterEvaluationContext har en egenskap parameters, som är en Map<String, Object>.

Inriktning

Målinriktning är en strategi för hantering av funktioner som gör det möjligt för utvecklare att etappvis rulla ut 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. Utrullningsprocenten höjs till 100 procent och funktionen lanseras 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. TargetingContextAccessor gör det möjligt att definiera den aktuella TargetingContext som ska användas för att bestämma det aktuella användar-ID:t och grupperna, vilket framgår av följande exempel:

public class MyTargetingContextAccessor implements TargetingContextAccessor {

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

}

Inriktning på 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));
    }

Uppdatering av konfiguration

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 systemet övervakar för 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.

Anteckning

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]

Efter att programmet har skapat loggen, uppdateras alla @Bean inom uppdateringsområdet.

Anteckning

Som standardinställning ingår annoterade komponenter 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, när ett uppdateringsförsök görs, 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

Automatiserad

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 begäranden till slutpunkter i en @RestController.

Handbok

I program som endast använder spring-cloud-azure-appconfiguration-config, till exempel konsolprogram, kan du manuellt utlösa en uppdatering genom att anropa AppConfigurationRefresh.refreshConfiguration-metoden. 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 (rekommenderas inte)

Anteckning

Den här metoden rekommenderas inte längre, men stöds för närvarande fortfarande.

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 sina motsvarigheter refresh och refresh-bus, där appkonfigurationsslutpunkterna avslutar uppdateringsintervallet i stället för att framtvinga en uppdatering vid mottagning. 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 upphör uppdateringsintervallet, så det återstående uppdateringsintervallet väntas inte på 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äkrar att varje instans av ditt program inte försöker uppdatera samtidigt.

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

Förutom att exponera uppdateringsslutpunkterna kräver biblioteket en frågeparameter för säkerhet. Inget tokennamn eller värde finns 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 webhooks finns i Webhook-händelseleverans.

Anteckning

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 :

Namn	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 är slut kontrollerar systemet alla funktionsflaggor i det angivna arkivet efter ä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 butik, 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 att automatiskt ansluta till lagringsplatsen 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, ConfigurationClientCustomizer och 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 customize(ConfigurationClientBuilder builder, String endpoint);
}

public interface SecretClientCustomizer {
    public void customize(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.

Anteckning

Och ConfigurationClientBuilderSecretClientBuilder ä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 standardinställningar 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();
    }

}