Podpora konfigurace aplikací

Tento článek popisuje knihovnu konfigurace Aplikace Azure Spring Cloud. Tato knihovna načte konfigurace a příznaky funkcí ze služby konfigurace Aplikace Azure. Knihovna generuje PropertySource abstrakce tak, aby odpovídaly abstrakcím, které už prostředí Spring vygenerovalo, například proměnné prostředí, konfigurace příkazového řádku, místní konfigurační soubory atd.

Spring je opensourcová aplikační architektura vyvinutá VMware, která poskytuje zjednodušený modulární přístup pro vytváření aplikací v Javě. Spring Cloud Azure je opensourcový projekt, který poskytuje bezproblémovou integraci Spring se službami Azure.

Požadavky

• Předplatné Azure – vytvořte si ho zdarma.
• Java Development Kit (JDK) verze 8 nebo vyšší.
• Apache Maven
• Azure CLI

Nastavte své úložiště konfigurace aplikace

Pomocí následujícího příkazu vytvořte úložiště konfigurace Aplikace Azure:

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

Tento příkaz vytvoří nové prázdné úložiště konfigurace. Konfigurace můžete nahrát pomocí následujícího příkazu importu:

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

Před načtením potvrďte konfigurace. Soubory YAML můžete nahrát tak, že změníte formát na YAML. Pole předpony je důležité, protože se jedná o výchozí předponu načtenou klientskou knihovnou.

Využití knihovny

Pokud chcete tuto funkci použít v aplikaci, můžete ji sestavit jako aplikaci Spring Boot. Nejpohodlnější způsob, jak přidat závislost, je s úvodní aplikací com.azure.spring:spring-cloud-azure-starter-appconfiguration-configSpring Boot . Následující příklad pom.xml soubor používá 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>

Následující příklad ukazuje základní aplikaci Spring Boot pomocí konfigurace aplikace:

@SpringBootApplication
@RestController
public class Application {

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

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

V tomto příkladu soubor application.properties obsahuje následující řádek:

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

CONFIG_STORE_ENDPOINT je proměnná prostředí s adresou URL koncového bodu pro Azure App Configuration Store.

Poznámka:

Microsoft doporučuje používat nejbezpečnější dostupný tok ověřování. Tok ověřování popsaný v tomto postupu, například pro databáze, mezipaměti, zasílání zpráv nebo služby AI, vyžaduje velmi vysoký stupeň důvěryhodnosti v aplikaci a nese rizika, která nejsou přítomna v jiných tocích. Tento tok používejte pouze v případě, že nejsou dostupné bezpečnější možnosti, jako jsou řízené identity pro připojení bez hesla nebo bez klíčů. V případě místních operací počítačů upřednostňujete identity uživatelů pro připojení bez hesla nebo bez klíčů.

Ve výchozím nastavení, pokud nejsou nastaveny žádné konfigurace, načtou se konfigurace začínající /application/ s výchozím popiskem (No Label). Pokud je však nastaven profil Spring, pak je výchozím popiskem váš profil Spring.

Vytvoří se zdroj vlastností /application/https://<name-of-your-store>.azconfig.io/, který obsahuje vlastnosti daného úložiště. Štítek použitý v žádosti se připojí na konec názvu. Pokud není nastavený žádný popisek, znak \0 se zobrazí jako prázdné místo.

Načítání konfigurace

Knihovna podporuje načítání jednoho nebo více úložišť App Configuration. V situaci, kdy je klíč duplikován v několika úložištích, vyhraje poslední klíč.

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

V tomto příkladu platí, že pokud obě úložiště mají stejný konfigurační klíč, má konfigurace ve druhém úložišti nejvyšší prioritu.

Poznámka:

Můžete použít nastavení konfigurace Aplikace Azure stejně jako jakákoli jiná konfigurace Spring. Další informace najdete v dokumentaci ke Základním funkcím Spring Boot nebo v Rychlý start: Vytvoření aplikace Java Spring s Azure App Configuration.

Výběr konfigurací

Knihovna načítá konfigurace pomocí jejich klíče a popisku. Ve výchozím nastavení se načtou konfigurace, které začínají klíčem /application/ . Výchozí popisek je \0, který se zobrazí jako (No Label) na webu Azure Portal. Pokud je nastavený profil Spring a není k dispozici žádný popisek, je výchozím popiskem váš profil Spring, což je ${spring.profiles.active}.

Konfiguraci, které konfigurace se načtou, můžete nakonfigurovat výběrem různých filtrů klíčů a popisků:

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

Vlastnost key-filter podporuje následující filtry:

Filtr klíčů	Účinnost
*	Odpovídá libovolnému klíči.
abc	Odpovídá klíči pojmenovanému abc.
abc*	Odpovídá názvům klíčů, které začínají na abc.
abc,xyz	Porovnává názvy klíčů, jako jsou abc nebo xyz. Omezeno na pět hodnot oddělených čárkami.

Vlastnost label-filter podporuje následující filtry:

Štítek	Popis
*	Odpovídá jakémukoli štítku, včetně \0.
\0	Odpovídá null popiskům, které se zobrazují jako (No Label) v Azure Portalu.
1.0.0	Přesně odpovídá popisku 1.0.0 .
1.0.*	Odpovídá popiskům, které začínají na 1.0.*.
,1.0.0	Odpovídá popiskům null a 1.0.0. Omezeno na pět hodnot oddělených čárkami.

Pokud používáte YAML s filtry popisků a chcete načíst konfigurace bez popisku a dalších konfigurací s jinými popisky, musíte zahrnout prázdný ,. Například ,dev shody \0 a dev. V tomto případě ohraničí filtr popisku jednoduchými uvozovkami. Tato hodnota umožňuje nejprve načíst konfiguraci bez popisku a následně konfigurace s konkrétními popisky ve stejném filtru:

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

Poznámka:

Ve filtrech se nedá kombinovat *, . V takovém případě musíte použít další hodnotu výběru.

Když použijete * filtr popisků a načte se několik konfigurací se stejným klíčem, načtou se v abecedním pořadí a popisek se použije jako poslední v abecedním pořadí.

Spring Profily

Ve výchozím nastavení spring.profiles.active je nastavená jako výchozí label-filter pro všechny vybrané konfigurace. Tuto funkci můžete přepsat pomocí funkce label-filter. Profily Spring můžete label-filter použít pomocí ${spring.profiles.active}, jak je znázorněno v následujícím příkladu:

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

V první label-filterčásti knihovna nejprve načte všechny konfigurace s \0 popiskem, následované všemi konfiguracemi odpovídajícími profilům Spring. Profily Spring mají přednost před \0 konfiguracemi, protože jsou na konci.

V druhé label-filterčásti se řetězec _local připojí ke konci profilů spring, ale pouze k poslednímu profilu springu, pokud existuje více než jeden.

Zakázané obchody

Pomocí konfigurace spring.cloud.azure.appconfiguration.enabledmůžete zakázat načítání pro všechna úložiště konfigurace. S konfigurací spring.cloud.azure.appconfiguration.stores[0].enabled můžete zakázat jednotlivý obchod.

Poznámka:

Pokud používáte zdravotní metriky, vaše obchody se stále zobrazují, ale s hodnotou NOT LOADED. Když zkontrolujete načtené zdroje vlastností, jsou stále zobrazeny, ale neobsahují žádné hodnoty. Toto chování je způsobeno nastavenou spring.config.import vlastností. Pokud azureAppConfiguration není nastaveno pro spring.config.import, nezobrazí se žádné hodnoty.

Ověřování

Knihovna podporuje všechny formy identity podporované službou Azure Identity Library. Ověřování můžete provést prostřednictvím konfigurace pro připojovací řetězec a spravovanou identitu.

Poznámka:

Microsoft doporučuje používat nejbezpečnější dostupný tok ověřování. Tok ověřování popsaný v tomto postupu, například pro databáze, mezipaměti, zasílání zpráv nebo služby AI, vyžaduje velmi vysoký stupeň důvěryhodnosti v aplikaci a nese rizika, která nejsou přítomna v jiných tocích. Tento tok používejte pouze v případě, že nejsou dostupné bezpečnější možnosti, jako jsou řízené identity pro připojení bez hesla nebo bez klíčů. V případě místních operací počítačů upřednostňujete identity uživatelů pro připojení bez hesla nebo bez klíčů.

Připojovací řetězec (nedoporučuje se)

Ověřování prostřednictvím připojovacího řetězce je nejjednodušší způsob nastavení, i když se nedoporučuje. Získáte přístup k připojovacím řetězcům obchodu pomocí následujícího příkazu:

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

Potom můžete nastavit vlastnost spring.cloud.azure.appconfiguration.stores[0].connection-string na připojovací řetězec. Při použití tohoto přístupu důrazně doporučujeme nastavit připojovací řetězec v místním konfiguračním souboru na zástupnou hodnotu, která se mapuje na proměnnou prostředí. Tento přístup umožňuje vyhnout se přidávání připojovacího řetězce do správy zdrojového kódu.

Konfigurace Azure Spring Cloudu

Ke konfiguraci knihovny můžete použít konfiguraci Spring Cloud Azure. Ke konfiguraci knihovny můžete použít následující vlastnosti:

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

Pokud je nastavený pouze koncový bod, klientská knihovna k ověření používá defaultAzureCredential .

Musíte přiřadit identitu použitou ke čtení konfigurací. Toto přiřazení můžete vytvořit pomocí následujícího příkazu:

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>

Poznámka:

Pro každý koncový bod můžete definovat pouze jednu metodu ověřování: připojovací řetězec, identitu přiřazenou uživatelem nebo přihlašovací údaje tokenu. Pokud potřebujete kombinovat a shodovat, můžete použít ConfigurationClientCustomizer úpravu ConfigurationClientBuilder použití různých metod.

Poznámka:

Microsoft doporučuje používat nejbezpečnější dostupný tok ověřování. Tok ověřování popsaný v tomto postupu, například pro databáze, mezipaměti, zasílání zpráv nebo služby AI, vyžaduje velmi vysoký stupeň důvěryhodnosti v aplikaci a nese rizika, která nejsou přítomna v jiných tocích. Tento tok používejte pouze v případě, že nejsou dostupné bezpečnější možnosti, jako jsou řízené identity pro připojení bez hesla nebo bez klíčů. V případě místních operací počítačů upřednostňujete identity uživatelů pro připojení bez hesla nebo bez klíčů.

Geografická replikace

Knihovna podporuje funkci geografické replikace služby Azure App Configuration. Tato funkce umožňuje replikovat data do jiných umístění. Tato funkce je užitečná pro vysokou dostupnost a zotavení po havárii.

Každá replika, kterou vytvoříte, má vyhrazený koncový bod. Pokud se vaše aplikace nachází v několika geografických polohách, můžete každé nasazení vaší aplikace aktualizovat v umístění, aby se připojila k replice blíže k danému umístění, což pomáhá minimalizovat latenci sítě mezi vaší aplikací a službou App Configuration. Vzhledem k tomu, že každá replika má samostatnou kvótu požadavků, toto nastavení také pomůže s škálovatelností vaší aplikace, zatímco se stává distribuovanou službou v rámci více regionů.

Ve výchozím nastavení knihovna automaticky zjistí všechny repliky, které existují pro úložiště konfigurace. Když se do poskytnutého úložiště odešle požadavek a selže, knihovna požadavek automaticky opakuje s dostupnými replikami.

K převzetí služeb při selhání může dojít v případě, že knihovna sleduje některou z následujících podmínek:

• Přijímá odpovědi s nedostupným stavovým kódem služby (HTTP 500 nebo vyšší) z koncového bodu.
• Dochází k problémům s připojením k síti.
• Požadavky jsou omezovány (stavový kód HTTP 429).

Jakmile se poskytnuté úložiště vrátí do online režimu, knihovna automaticky opakuje požadavek na poskytnuté úložiště.

Pokud chcete řídit chování převzetí služeb při selhání, můžete ručně zadat seznam úložišť, které se mají použít pro převzetí služeb při selhání.

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

nebo

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]

Pokud všechny zadané koncové body repliky selžou, knihovna se pokusí připojit k automaticky zjištěnými replikám primárního úložiště.

Replikaci můžete zakázat pomocí nastavení spring.cloud.azure.appconfiguration.stores[0].replica-discovery-enabled=false.

Vytvoření úložiště konfigurace s geografickou replikací

K vytvoření repliky úložiště konfigurace můžete použít Azure CLI nebo Azure Portal. Následující příklad používá Azure CLI k vytvoření repliky v oblasti USA – východ 2:

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

Klíčové hodnoty

Aplikace Azure Konfigurace podporuje více typů hodnot klíčů, z nichž některé mají integrované speciální funkce. Aplikace Azure Configuration má integrovanou podporu pro typ obsahu JSON, zástupné symboly Springu a reference ke službě Key Vault.

Zástupné symboly

Knihovna podporuje konfigurace se zástupnými symboly prostředí ve stylu ${}. Při odkazování na konfigurační klíč Aplikace Azure se zástupným symbolem odeberte předpony z odkazu. Například /application/config.message se odkazuje na ${config.message}.

Poznámka:

Odebraná předpona odpovídá hodnotě spring.cloud.azure.appconfiguration.stores[0].selects[0].key-filter. Předponu, která je oříznuta, lze změnit nastavením hodnoty pro spring.cloud.azure.appconfiguration.stores[0].trim-key-prefix[0].

JSON

Konfigurace, které mají typ application/json obsahu, se zpracovávají jako objekty JSON. Tato funkce umožňuje namapovat jednu konfiguraci na složitý objekt uvnitř objektu @ConfigurationProperties. Představte si například klíč /application/config.colors JSON s následující hodnotou:

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

Tento klíč se mapuje na následující kód:

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

    private Map<String, Color> colors;

}

Reference ke službě Key Vault

Konfigurace aplikací Azure a její knihovny podporují odkazování na tajemství uložená ve službě Key Vault. V App Configuration můžete vytvořit klíče s hodnotami, které se mapují na tajemství uložená v Key Vault. Tajné kódy zůstávají ve službě Key Vault zabezpečené, ale při načítání aplikace k nim máte přístup stejným způsobem jako jakákoli jiná konfigurace.

Vaše aplikace pomocí zprostředkovatele klienta načítá odkazy na Key Vault, stejně jako u všech dalších klíčů uložených v App Configuration. Vzhledem k tomu, že klient rozpozná klíče jako reference ke službě Key Vault, má jedinečný typ obsahu, klient se připojí ke službě Key Vault a načte tyto hodnoty za vás.

Poznámka:

Key Vault umožňuje načíst tajemství vždy po jednom, takže každý odkaz na Key Vault uložený v App Configuration způsobí dotazování proti službě Key Vault.

Vytváření referencí na Key Vault

Odkaz na službu Key Vault můžete vytvořit v Azure portálu tím, že přejdete na Průzkumník konfigurace>Vytvořit>Odkaz na Key Vault. Pak můžete vybrat tajný klíč, na který chcete odkazovat z některého z trezorů klíčů, ke kterým máte přístup. Na kartě Vstup můžete také vytvořit libovolné odkazy služby Key Vault. Na webu Azure Portal zadejte platný identifikátor URI.

Pomocí následujícího příkazu můžete také vytvořit referenční informace ke službě Key Vault prostřednictvím Azure CLI:

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

Pomocí Azure CLI můžete vytvořit libovolný identifikátor tajného kódu. Identifikátory tajných kódů vyžadují jenom formát {vault}/{collection}/{name}/{version?} , ve kterém je oddíl verze volitelný.

Použití odkazů služby Key Vault

Ke konfiguraci knihovny můžete použít konfiguraci Spring Cloud Azure. K připojení ke službě Azure Key Vault můžete použít stejné přihlašovací údaje, které se používají pro připojení ke službě App Configuration.

Můžete také vytvořit SecretClientCustomizer stejný způsob, jakým byste vytvořili metodu ConfigurationClientCustomizer ověřování.

Řešení tajemství mimo Key Vault

Knihovna App Configuration poskytuje metodu přepsání překladu odkazů na trezor klíčů. Můžete ho například použít k místnímu řešení tajných kódů ve vývojovém prostředí. Toto řešení se provádí prostřednictvím KeyVaultSecretProvider. Pokud KeyVaultSecretProviderje k dispozici, volá se pro každý odkaz na trezor klíčů. Pokud getSecret vrátí hodnotu, která není null, použije se jako tajná hodnota. V opačném případě se referenční informace ke službě Key Vault vyřeší normálně.

public class MySecretProvider implements KeyVaultSecretProvider {

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

}

Správa funkcí

Správa funkcí umožňuje aplikacím Spring Boot dynamicky přistupovat k obsahu. Správa funkcí má různé funkce, například následující funkce:

• Příznaky funkcí, které můžou povolit nebo zakázat obsah
• Filtry vlastností pro cílení, kdy se obsah zobrazí
• Přizpůsobené filtry funkcí
• Brány funkcí pro dynamické povolení koncových bodů

Příznaky funkcí můžete povolit prostřednictvím následující konfigurace:

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

Povolené funkční příznaky jsou načteny do konfiguračního systému Spring s předponou feature-management. Příznaky funkcí můžete také zaregistrovat v místním konfiguračním souboru. Další informace najdete v části Deklarace příznaku funkce.

Nejjednodušší způsob, jak používat správu funkcí, je použití knihoven spring-cloud-azure-feature-managementspring-cloud-azure-feature-management-web. Rozdíl mezi těmito dvěma knihovnami spočívá v tom, že spring-cloud-azure-feature-management-web závisí na knihovnách spring-web a spring-webmvc ke přidání dalších funkcí, jako jsou brány funkcí.

Ve výchozím nastavení se načtou všechny příznaky funkcí s popiskem \0 , který je vidět jako (No Label). Příznaky funkcí, které jsou načteny, můžete nakonfigurovat nastavením filtru štítku, jak je znázorněno v následujícím příkladu:

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

Základy správy funkcí

Hlavní příznaky

Příznaky funkcí se skládají z několika částí včetně názvu a seznamu filtrů funkcí, které se používají k zapnutí funkce. Příznaky funkcí můžou mít buď logický stav zapnuto nebo vypnuto, nebo můžou mít seznam filtrů funkcí. Funkční příznaky vyhodnocují filtry funkcí, dokud některý nevrátí hodnotu true. Pokud žádný filtr funkce nevrátí true, pak příznak funkce vrátí false.

Filtry funkcí

Filtry funkcí definují scénář, kdy má být funkce povolená. Filtry funkcí se vyhodnocují synchronně.

Knihovna pro správu funkcí obsahuje čtyři předdefinované filtry: AlwaysOnFilter, PercentageFilter, TimeWindowFilter a TargetingFilter.

Můžete vytvořit vlastní filtry funkcí. Pomocí filtru funkcí můžete například poskytnout vlastní prostředí pro zákazníky, kteří používají prohlížeč Microsoft Edge. Funkce v tomto filtru funkcí si můžete přizpůsobit, například tak, aby zobrazovaly konkrétní záhlaví pro cílovou skupinu prohlížeče Microsoft Edge.

Deklarace příznaku funkce

Knihovna pro správu funkcí podporuje Azure App Configuration spolu s application.yml nebo application.properties jako zdroji příznaků funkcí. Tady je příklad formátu použitého k nastavení příznaků funkcí v souboru application.yml :

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

V tomto příkladu jsou následující příznaky funkcí:

• feature-t je nastaveno na false. Toto nastavení vždy vrátí hodnotu příznaku funkce.
• feature-u se používá s filtry funkcí. Tyto filtry jsou definovány v rámci enabled-for vlastnosti. V tomto případě feature-u má jeden filtr funkcí s názvem Random, který nevyžaduje žádnou konfiguraci, takže je vyžadována pouze vlastnost názvu.
• feature-v určuje filtr funkcí s názvem TimeWindowFilter. Na tento filtr funkcí lze předat parametry k použití jako konfigurace. V tomto příkladu TimeWindowFilter předá časy začátku a konce, během nichž je funkce aktivní.
• feature-w se používá pro AlwaysOnFilter, který se vždy vyhodnotí jako true. Toto evaluate pole slouží k zastavení vyhodnocení filtrů funkcí a výsledkem je vždy vrácení falsefiltru funkcí .

Vyhodnocení příznaků funkcí

Knihovna spring-cloud-azure-feature-management poskytuje FeatureManager k určení, zda je příznak funkce povolen. FeatureManager poskytuje asynchronní způsob, jak zkontrolovat stav příznaku.

spring-cloud-azure-feature-management-web, spolu s poskytováním FeatureManager, obsahuje FeatureManagerSnapshot, který ukládá do mezipaměti stav dříve vyhodnocených příznaků funkcí v @RequestScope rámci záruky, že všechny požadavky vrátí stejnou hodnotu. Kromě toho poskytuje webová knihovna @FeatureGate, která může blokovat nebo přesměrovat webové požadavky na různé koncové body.

Kontrola přepínače funkce

FeatureManager je @Bean, který může být @Autowired nebo vložen do objektů typu @Component. FeatureManager má metodu isEnabled , která při předání názvu příznaku funkce vrátí svůj stav.

@Autowired
FeatureManager featureManager;

...

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

Poznámka:

FeatureManager má také asynchronní verzi isEnabled nazývanou isEnabledAsync.

Bez konfigurace správy funkcí nebo pokud příznak funkce neexistuje, isEnabled vždy vrátí .false Pokud je příznak existující funkce nakonfigurovaný s neznámým filtrem funkcí, vyvolá se chyba FilterNotFoundException. Toto chování můžete změnit tak, že nakonfigurujete false na fail-fast pro návrat false. Následující tabulka popisuje fail-fast:

Název	Popis	Požaduje se	Výchozí
spring.cloud.azure.feature.management.fail-fast	Pokud dojde k výjimce, je vyvolána RuntimeException. Pokud je tato vlastnost nastavena na false, vrátí isEnabled místo toho false.	Ne	true

Jediným rozdílem mezi FeatureManagerSnapshot a FeatureManager je ukládání výsledků do mezipaměti v souboru @RequestScope.

Hradlo funkcí

S webovou knihovnou pro správu funkcí můžete vyžadovat, aby byla daná funkce povolená, aby bylo možné spustit koncový bod. Tento požadavek můžete nastavit pomocí poznámky @FeatureGate , jak je znázorněno v následujícím příkladu:

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

Ke koncovému featureT bodu se dostanete jenom v případě, že je povolená funkce feature-t.

Deaktivované zpracování akcí

Když je koncový bod zablokovaný, protože funkce, kterou určuje, je zakázaná, DisabledFeaturesHandler je vyvolána. Ve výchozím nastavení se vrátí http 404. Toto chování můžete přepsat implementací DisabledFeaturesHandler, jak je znázorněno v následujícím příkladu:

@Component
public class MyDisabledFeaturesHandler implements DisabledFeaturesHandler {

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

}

Směrování

Některé trasy můžou zpřístupnit možnosti aplikace, které jsou chráněné funkcemi. Pokud je funkce zakázaná, můžete tyto trasy přesměrovat do jiného koncového bodu, jak je znázorněno v následujícím příkladu:

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

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

Předdefinované filtry funkcí

Balíček spring-cloud-azure-feature-management obsahuje několik filtrů funkce. Tyto filtry funkcí se přidají automaticky.

Filtr AlwaysOnFilter

Tento filtr vždy vrátí true. Příklad použití najdete v části deklarace příznaku funkce.

Procentuální filtr

Při každé kontrole může vyhodnocení PercentageFilter vrátit jiný výsledek. Tuto nekonzistence můžete obejít pomocí FeatureManagementSnapshotfunkce, která ukládá výsledek příznaku funkce na požadavek do mezipaměti.

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

FiltrČasovéhoOkna

Tento filtr poskytuje možnost povolit funkci na základě časového intervalu. Pokud zadáte pouze End, bude funkce do té doby považována za zapnutou. Pokud zadáte jenom Start, funkce je považována za zapnutou ve všech bodech po tomto čase. Pokud zadáte obojí, funkce se považuje za platnou mezi těmito dvěma časy.

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"

Tento filtr také podporuje filtry opakovaných časových intervalů. Podporuje denní i týdenní opakování spolu s časem vypršení platnosti.

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

Tento způsob opakování probíhá každý týden v pondělí a ve středu od 00:00:00 GMT do 12:00:00 GMT a nevyprší platnost.

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"

Tento způsob opakování probíhá každý druhý den od 00:00:00 GMT do 12:00:00 GMT do koncového data.

Filtr cílení

Tento filtr poskytuje možnost povolit funkci cílové cílové skupině. Podrobné vysvětlení cílení najdete v části věnované cílení. Parametry filtru zahrnují objekt cílové skupiny, který popisuje uživatele, skupiny a výchozí procento uživatelské základny, které by měly mít přístup k této funkci. Pro každý objekt skupiny, který je uveden v cílové cílové skupině, je vyžadováno procento, které definuje procento členů této skupiny, kteří mají přístup k této funkci. Uživatel má tuto funkci povolenou v následujících případech:

• Uživatel se zadává přímo v části uživatelů.
• Uživatel se nachází v zahrnutém procentu některé ze skupinových nasazení.
• Uživatel spadá do výchozího procenta rozložení.

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

Přizpůsobené filtry funkcí

Vytvoření vlastního filtru funkcí poskytuje způsob, jak povolit funkce na základě vámi definovaných kritérií. Pokud chcete vytvořit vlastní filtr funkcí, musíte implementovat FeatureFilter rozhraní. FeatureFilter má jednu metodu evaluate. Pokud funkce určuje, že je možné ji povolit pomocí filtru funkcí, je volána metoda evaluate. Pokud evaluate vrátí true, znamená to, že funkce má být povolená. Pokud se vrátí false, pokračuje v vyhodnocování filtrů funkcí, dokud se nevrátí true. Pokud se všechny filtry vrátí false, pak je funkce vypnutá.

Filtry funkcí jsou definovány jako Spring Beans, takže jsou buď definovány jako @Component nebo definovány v @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;
    }

}

Parametrizované filtry funkcí

Některé filtry funkcí vyžadují parametry k určení, jestli má být funkce zapnutá. Filtr funkcí prohlížeče může například zapnout funkci pro určitou sadu prohlížečů. Možná budete chtít povolit funkci pro prohlížeče Microsoft Edge a Chrome, ale ne Firefox. Pokud chcete tuto situaci nastavit, můžete navrhnout filtr funkcí tak, aby očekával parametry. Tyto parametry by byly zadány v konfiguraci funkce a v kódu a byly by přístupné prostřednictvím parametru FeatureFilterEvaluationContextevaluate. FeatureFilterEvaluationContext má vlastnost parameters, která je Map<String, Object>.

Cílení

Cílení je strategie správy funkcí, která vývojářům umožňuje postupně zavádět nové funkce do uživatelské základny. Strategie je založená na konceptu cílení na skupinu uživatelů, kteří se označují jako cílová skupina. Cílová skupina se skládá z konkrétních uživatelů, skupin a určeného procenta celé uživatelské základny. Skupiny, které jsou součástí cílové skupiny, je možné dále rozdělit do procent jejich celkových členů.

Následující kroky ukazují příklad postupného zavedení nové funkce Beta:

1. Jednotlivým uživatelům Jeff a Alicia jsou udělen přístup k beta verzi.
2. Jiný uživatel, Mark, žádá, aby se přihlásil a je zahrnutý.
3. Do beta verze je zahrnuta dvacet procent skupiny, která se označuje jako "Ring1".
4. Počet uživatelů "Ring1" zahrnutých v beta verzi se zvýšil na 100 procent.
5. Pět procent uživatelské základny je součástí beta verze.
6. Procento zavedení se zvýší na 100 procent a funkce je zcela zavedena.

Tato strategie pro zavádění funkce je integrovaná do knihovny prostřednictvím zahrnutého TargetingFilter filtru funkcí.

Cílení v aplikaci

Ukázková webová aplikace, která používá filtr funkcí cílení, je dostupná v ukázkovém projektu.

Pokud chcete začít používat TargetingFilter v aplikaci, musíte jej přidat jako @Bean podobně jako jakýkoli jiný filtr funkcí. TargetingFilter spoléhá na další @Bean, který bude přidán do aplikace TargetingContextAccessor. TargetingContextAccessor umožňuje definovat aktuální TargetingContext, který se používá k určení ID aktuálního uživatele a jeho skupin, jak je ukázáno v následujícím příkladu:

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

}

Možnosti vyhodnocení cílení

Jsou k dispozici možnosti pro přizpůsobení způsobu, jak se hodnocení cílení provádí v daném TargetingFilter prostředí. Během vytváření můžete nastavit volitelný parametrTargetingEvaluationOptionsTargetingFilter.

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

Aktualizace konfigurace

Povolením aktualizace konfigurací vám umožní vyžádat si jejich nejnovější hodnoty z úložiště konfigurace aplikace nebo úložišť, aniž byste museli aplikaci restartovat.

Pokud chcete povolit aktualizaci, musíte povolit monitorování spolu se spouštěči monitorování. Aktivační událost monitorování je klíč s volitelným popiskem, který systém monitoruje změny hodnot, aby aktivoval aktualizace. Hodnota triggeru monitorování může být libovolná hodnota, pokud se změní v případě potřeby aktualizace.

Poznámka:

Jakákoli operace, která změní značku ETag triggeru monitorování, způsobí aktualizaci, například změnu typu obsahu.

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

Pokud chcete aktivovat aktualizaci konfigurace, změňte hodnotu klíče v úložišti konfigurace. Potom aktualizujte jeden ze sledovacích klíčů na novou hodnotu. Tato změna spustí vytvoření protokolu. Například změna hodnoty /application/config.message vyvolá následující zprávu protokolu:

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

Jakmile aplikace vygeneruje protokol, aktualizuje všechna @Beandata v oboru aktualizace.

Poznámka:

Ve výchozím nastavení jsou v tomto oboru zahrnuty @ConfigurationProperties anotované komponenty.

Aktualizace na základě požadavku

Knihovny Spring pro konfiguraci aplikace podporují možnost pravidelně kontrolovat změny v monitorovacích triggerech v rámci intervalu obnovy. Ve výchozím nastavení je interval aktualizace nastavený na 30 sekund. Po uplynutí intervalu aktualizace jsou při pokusu o aktualizaci všechny triggery vráceny do daného úložiště pro změny. Jakákoli změna klíče způsobí aktivaci aktualizace. Vzhledem k tomu, že se knihovny integrují se systémem Spring Refresh, všechny aktualizace znovu načtou všechny konfigurace ze všech úložišť. Interval aktualizace můžete nastavit na libovolný interval delší než 1 sekundu. Podporované jednotky pro interval aktualizace jsou s, m, h, a d pro sekundy, minuty, hodiny a dny v uvedeném pořadí. Následující příklad nastaví interval aktualizace na 5 minut:

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

Automatizováno

Při použití spring-cloud-azure-appconfiguration-config-web knihovny aplikace automaticky kontroluje aktualizaci vždy, když dojde k požadavku servletu, konkrétně ServletRequestHandledEvent. Nejběžnější způsob, jakým je tato událost odeslána, je pomocí požadavků na koncové body v @RestController.

Příručka

V aplikacích, které používají pouze spring-cloud-azure-appconfiguration-config, jako například konzolové aplikace, můžete aktualizaci aktivovat ručně voláním metody AppConfigurationRefreshrefreshConfiguration. AppConfigurationRefresh je @Bean, který můžete vložit do libovolného @Component.

Vzhledem k tomu, že knihovna používá konfigurační systém Springu, vyvolání aktualizace způsobí aktualizaci všech vašich konfigurací, nejen opětovné načtení těch z azure App Configuration Storu.

Aktualizace založená na push technologii (nedoporučuje se)

Poznámka:

Tato metoda se už nedoporučuje, ale v současné době je stále podporovaná.

Knihovnu spring-cloud-azure-appconfiguration-config-web můžete nastavit tak, aby přijímala push oznámení z Azure App Configuration Store a tím aktualizovala hodnoty konfigurace. Tuto konfiguraci můžete nastavit prostřednictvím webového háku služby Azure Event Grid, který můžete nakonfigurovat tak, aby odesílala oznámení o změnách zadaných klíčů. Přidáním knihovny Spring Actuator jako závislosti můžete zveřejnit koncové body pro aktualizaci konfigurace aplikace. Existují dva různé koncové body: appconfiguration-refresh a appconfiguration-refresh-bus. Tyto koncové body fungují podobně jako jejich protějšky refresh a refresh-bus, kde koncové body konfigurace aplikace vyprší interval aktualizace místo vynucení aktualizace po přijetí. Můžete je dál používat refresh , refresh-busale nemůžete je připojit přímo ke službě Azure Event Grid pomocí webhooku, protože vyžadují odpověď v nastavení.

Vlastnost appconfiguration-refresh vyprší stanovený interval aktualizace, což znamená, že se nečeká na zbývající čas aktualizace před další kontrolou aktualizace. Tato appconfiguration-refresh-bus vlastnost odešle oznámení do připojené služby zasílání zpráv, jako je Azure Service Bus, a upozorní všechny instance aplikace na aktualizaci. V obou případech nevyprší úplně v intervalu obnovení, ale zůstane o malou odchylku mimo. Tím se zajistí, že se každá instance vaší aplikace nebude pokoušet aktualizovat ve stejnou dobu.

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

Kromě zveřejnění koncových bodů aktualizace vyžaduje knihovna parametr dotazu pro zabezpečení. Ve výchozím nastavení neexistuje žádný název nebo hodnota tokenu, ale musíte ho nastavit tak, aby používal koncové body, jak je znázorněno v následujícím příkladu:

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]

Nastavení webhooků

Pokud chcete nastavit webhook, otevřete úložiště konfigurace Aplikace Azure a v navigační nabídce otevřete události. Pak vyberte Odběr událostí. Nastavte název vaší události a vyberte jako typ koncového bodu možnost webhook. Výběr webhooku způsobí, že se zobrazí možnost Koncový bod . Zvolte Vybrat koncový bod. Váš koncový bod by měl vypadat jako v následujícím příkladu: https://www.myaplication.com/actuator/appconfiguration-refresh?myTokenName=mySecret.

Potvrzení výběru odešle oznámení o nastavení na danou URI a očekává odpověď. Pokud se nevrátí žádná odpověď, instalace selže. Nastavení azure-spring-cloud-appconfiguration-web knihovny pro koncové body vrátí správnou odpověď, pokud je pro aplikaci nakonfigurované úložiště konfigurace Aplikace Azure. Toto potvrzení lze odeslat jinými způsoby. Další informace o doručení webhooku naleznete v tématu Webhook event delivery.

Poznámka:

K tomuto ověření dochází pouze při vytváření nebo úpravě koncového bodu.

Důrazně doporučujeme nastavit filtry, protože jinak se po každém vytvoření a úpravě klíče aktivuje aktualizace.

Vynucená aktualizace klienta

Knihovnu můžete nakonfigurovat tak, aby vynutila aktualizaci všech konfigurací v obnovovacím intervalu. Následující tabulka popisuje refresh-interval vlastnost:

Název	Popis	Požaduje se	Výchozí
spring.cloud.azure.appconfiguration.refresh-interval	Standardní doba mezi aktualizacemi. Je to Duration.	Ne	null

Při obnovení pomocí spring.cloud.azure.appconfiguration.refresh-interval se nekontrolují žádné nakonfigurované sledovací klíče. Tato vlastnost slouží k zajištění aktualosti tajných kódů služby Key Vault, protože Aplikace Azure Konfigurace nemůže zjistit, kdy se aktualizují.

Vzhledem k tomu, že Azure Key Vault ukládá dvojici veřejného a privátního klíče certifikátu jako tajný klíč, může vaše aplikace načíst libovolný certifikát jako odkaz služby Key Vault v Konfiguraci aplikace. Vzhledem k tomu, že certifikáty je potřeba pravidelně obměňovat, musí se klientské aplikace aktualizovat stejně často, což je možné provést pomocí intervalu aktualizace klienta.

Aktualizace přepínače funkcí

Pokud jsou příznaky funkcí i monitorování povolené, je ve výchozím nastavení interval aktualizace příznaků funkcí nastavený na 30 sekund. Po skončení intervalu aktualizace systém zkontroluje změny všech příznaků funkcí v daném úložišti. Jakákoli změna klíče způsobí aktivaci aktualizace. Vzhledem k tomu, že se knihovny integrují se systémem Spring Refresh, všechny aktualizace znovu načtou všechny konfigurace ze všech úložišť. Interval aktualizace můžete nastavit na libovolný interval delší než 1 sekundu. Podporované jednotky pro interval aktualizace jsou s, m, h, a d pro sekundy, minuty, hodiny a dny v uvedeném pořadí. Následující příklad nastaví interval aktualizace na 5 minut:

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

Indikátor stavu

Klientská knihovna obsahuje pohotovostní indikátor, který kontroluje, zda je připojení k úložišti nebo úložištím služby Azure App Configuration v pořádku. Pokud je pro každé úložiště povolené, poskytne jednu z následujících hodnot stavu:

• UP – Poslední připojení bylo úspěšné.
• DOWN - Poslední připojení mělo za následek kód chyby, který nebyl 200. Příčinou tohoto stavu můžou být problémy od vypršení platnosti přihlašovacích údajů až po problém se službou. Klientská knihovna se automaticky pokusí znovu připojit k úložišti při následujícím intervalu aktualizace.
• NENAČÍTANÉ – Konfigurační úložiště je uvedené v místním konfiguračním souboru, ale při spuštění nebylo načteno z konfiguračního úložiště. Konfigurační úložiště je zakázáno v konfiguračním souboru nebo se konfigurace nepodařilo načíst při spuštění, zatímco konfigurace úložiště byla nastavena na fail-fast.

Indikátor stavu můžete povolit nastavením management.health.azure-app-configuration.enabled=true.

Přizpůsobení klienta

Knihovna App Configuration používá sadu Azure SDK pro Javu pro připojení k Azure App Configuration a Azure Key Vault. Jsou poskytována dvě rozhraní, ConfigurationClientCustomizer a SecretClientCustomizer, k úpravě klientů. Každé rozhraní má metodu customize, která přebírá svého příslušného tvůrce spolu s String hodnotou URI, pro kterou se klient konfiguruje, jak je znázorněno v následujících definicích rozhraní:

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

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

Tato rozhraní umožňují přizpůsobení klienta HTTP a jeho konfigurace. Následující příklad nahrazuje výchozí HttpClient hodnotu jinou, která používá proxy server pro veškerý provoz směrovaný na App Configuration a Key Vault.

Poznámka:

ConfigurationClientBuilder A SecretClientBuilder jsou již nastaveny pro použití při předání do customize. Všechny změny klientů, včetně přihlašovacích údajů a zásad opakování, přepíší výchozí hodnoty, které jsou už zavedené.

Tuto konfiguraci můžete provést také pomocí konfigurace 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();
    }

}