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

Nastavení app Configuration Storu

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á Aplikace Azure 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.12.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>

Poznámka:

Pokud používáte Spring Boot 2.x, nezapomeňte nastavit spring-cloud-azure-dependencies verzi na 4.18.0. Další informace o verzi použité pro tuto kusovníku najdete v tématu Jakou verzi Spring Cloud Azure mám použít.

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 bootstrap.properties obsahuje následující řádek:

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

CONFIG_STORE_CONNECTION_STRINGje proměnná prostředí s připojovací řetězec do vašeho úložiště konfigurace Aplikace Azure. K připojovací řetězec se dostanete pomocí následujícího příkazu:

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

Pokud nejsou nastaveny žádné konfigurace, načtou se konfigurace začínající /application/ na výchozí popisek (No Label) , pokud není nastavený profil Spring, v takovém případě je výchozím popiskem váš profil Spring. Vzhledem k tomu, že úložiště je prázdné, nenačtou se žádné konfigurace, ale zdroj vlastností konfigurace Aplikace Azure je stále generován.

Vytvoří se zdroj /application/https://<name-of-your-store>.azconfig.io/ vlastností obsahující vlastnosti tohoto úložiště. Popisek použitý v požadavku 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 napříč více úložišti, načtení všech úložišť vede k načtení konfigurace úložišť s nejvyšší prioritou. Poslední vyhrává. Tento proces je znázorněn v následujícím příkladu:

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

V tomto příkladu platí, že pokud mají první i druhé úložiště stejnou konfiguraci, má konfigurace v druhém úložišti nejvyšší prioritu a poslední z nich vyhraje.

Poznámka:

Můžete použít nastavení konfigurace Aplikace Azure stejně jako jakákoli jiná konfigurace Spring. Další informace najdete v dokumentaci ke Spring Bootu nebo v rychlém startu: Vytvoření aplikace Java Spring s Aplikace Azure Configuration.

Výběr konfigurací

Konfigurace se načítají podle jejich klíče a popisku. Ve výchozím nastavení se načtou konfigurace, které začínají klíčem /application/ . Výchozí popisek je ${spring.profiles.active}. Pokud ${spring.profiles.active} není nastavená, načtou se konfigurace s popiskem null . Popisek null se zobrazí jako (No Label) na webu Azure Portal.

Konfigurace, které jsou načteny, můžete nakonfigurovat tak, že vyberete různé filtry klíčů a popisků, jak je znázorněno v následujícím příkladu:

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 s názvem abc.
abc*	Odpovídá názvům klíčů, které začínají na abc.
abc,xyz	Odpovídá názvům abc klíčů 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 popisku, včetně \0.
\0	Odpovídá null popiskům, které se zobrazují jako (No Label) na webu Azure Portal.
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 potřebujete začít s null, musí být filtr popisků obklopen jednoduchými uvozovkami, jak je znázorněno v následujícím příkladu:

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.

Profily pružiny

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í příkazu ${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 se načtou všechny konfigurace s null popiskem následované všemi konfiguracemi odpovídajícími profilům Spring. Profily Spring mají přednost před null 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.

Zakázané obchody

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

Kromě zakázání úložišť můžete úložiště nakonfigurovat tak, aby byla zakázaná, pokud se jim nepodaří načíst. Pro tuto konfiguraci použijte spring.cloud.azure.appconfiguration.stores[0].fail-fast. Když fail-fast ho nastavíte tak, že ho nastavíte na false, RuntimeException způsobí, že se v úložišti aplikací zakáže bez konfigurací, které by se načítaly. Pokud je při spuštění zakázané úložiště konfigurace, při aktualizaci se změny nekontrolují. Pokud se konfigurace aktualizují, nemusíte se z něj pokoušet načíst hodnoty.

Pokud dojde k chybě RuntimeException během kontroly aktualizace nebo při pokusu o opětovné načtení konfigurací, pokus o aktualizaci skončí a bude se opakovat po refresh-interval jeho uplynutí.

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.

Connection string

Ověřování prostřednictvím připojovací řetězec je nejjednodušší způsob nastavení. K připojovací řetězec obchodu se dostanete pomocí následujícího příkazu:

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

Vlastnost pak můžete nastavit spring.cloud.azure.appconfiguration.stores[0].connection-string na připojovací řetězec. 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í řetězec 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 . K DefaultAzureCredential ověření se používají následující metody:

• Přihlašovací údaje prostředí
• Přihlašovací údaje spravované identity
• Přihlašovací údaje Azure Developer CLI
• Přihlašovací údaje IntelliJ
• Přihlašovací údaje Azure CLI
• Přihlašovací údaje Azure PowerShellu

Ke čtení konfigurací je potřeba přiřadit identitu, jako je identita přiřazená systémem. 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 k úpravě úložišť, které používají jinou metodu.

Geografická replikace

Knihovna podporuje funkci geografické replikace konfigurace Aplikace Azure. 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ů, pomůže tato instalace také škálovatelnost vaší aplikace, zatímco roste na distribuovanou službu ve více oblastech.

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 omezené (stavový kód HTTP 429).

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]

Použití repliky úložiště konfigurace

Po vytvoření repliky ji můžete použít ve své aplikaci. Podobně jako v úložišti původu se můžete k replice připojit pomocí ID Microsoft Entra nebo připojovací řetězec.

Microsoft Entra ID

Pokud chcete pro připojení k replice použít Microsoft Entra ID, musíte uvést endpoints seznam instancí úložiště konfigurace, jak je znázorněno v následujícím příkladu:

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

Můžete uvést libovolný počet koncových bodů, kolik máte replik. Knihovna se pokusí připojit ke koncovým bodům v pořadí, v jakém jsou uvedené. Pokud se knihovna nemůže připojit k replice, pokusí se o další knihovnu v seznamu. Po uplynutí časového období se knihovna pokusí znovu připojit k upřednostňovaným koncovým bodům.

připojovací řetězec

Pokud chcete použít připojovací řetězec pro připojení k replice, musíte uvést connectionStrings seznam instancí úložiště konfigurace, jak je znázorněno v následujícím příkladu:

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]

Můžete uvést libovolný počet připojovací řetězec, kolik máte replik. Knihovna se pokusí připojit k připojovací řetězec v uvedeném pořadí. Pokud se knihovna nemůže připojit k replice, pokusí se o další knihovnu v seznamu. Po uplynutí časového období se knihovna pokusí znovu připojit k upřednostňovaným připojovací řetězec.

Hodnoty klíče

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í -style. 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.

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

Aplikace Azure Konfigurace a její knihovny podporují odkazování na tajné kódy uložené ve službě Key Vault. V App Configuration můžete vytvořit klíče s hodnotami, které se mapuje na tajné kódy uložené ve službě Key Vault. Tajné kódy jsou bezpečně uložené ve službě Key Vault, ale po načtení se k nim dají přistupovat stejným způsobem jako k jakékoli jiné konfiguraci.

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 a klient se připojí ke službě Key Vault a načte své hodnoty za vás.

Poznámka:

Key Vault umožňuje načíst tajné kódy vždy po jednom, takže každý odkaz na Key Vault uložený v App Configuration způsobí přijetí změn ve službě Key Vault.

Vytváření odkazů služby Key Vault

Odkaz na službu Key Vault můžete vytvořit na webu Azure Portal tak, že přejdete na referenční informace k vytvoření>služby Key Vault v Průzkumníku>konfigurace. 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.

Řešení tajných kódů jiného než Key Vaultu

Knihovna App Configuration poskytuje metodu pro místní řešení tajných kódů, které nemají přidruženou službu Key Vault. Toto řešení se provádí prostřednictvím KeyVaultSecretProvidernástroje . Volá se KeyVaultSecretProvider v případě TokenCredential , že není k dispozici odkaz na službu Key Vault. Poskytuje se identifikátor URI odkazu služby Key Vault a vrácená hodnota se stane hodnotou tajného klíče.

Upozorňující

Použití KeyVaultSecretProvider přepsání automatického použití spravované identity přiřazené systémem. Pokud chcete použít obojí, musíte použít KeyVaultCredentialProvider a vrátit null identifikátory URI, které potřebují přeložit.

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 funkcí pro cílení, když se zobrazí obsah
• 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é příznaky funkcí se načtou 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í knihovenspring-cloud-azure-feature-management.spring-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ávislost na knihovnách spring-web a spring-webmvc knihovnách přidává další funkce, jako jsou brány funkcí.

Příznaky funkcí můžete povolit pomocí filtrů klíčů a popisků. Ve výchozím nastavení null je přiřazen popisek, který se považuje za (No Label)přiřazený. Příznaky funkcí, které jsou načteny, můžete nakonfigurovat nastavením filtru popisku, 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í ze dvou částí: názvu a seznamu filtrů funkcí, které se používají k zapnutí funkce. Příznaky funkcí můžou mít buď logický stav zapnuto/vypnuto, nebo můžou mít seznam filtrů funkcí. Příznaky funkcí vyhodnocují filtry funkcí, dokud se nevrátí true. Pokud žádný filtr funkce nevrátí true, vrátí falsepříznak funkce .

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 Aplikace Azure Configuration spolu s application.yml nebo bootstrap.yml jako zdroje pro příznaky funkcí. Tady je příklad formátu použitého k nastavení příznaků funkcí v souboru application.yml :

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

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

• feature-t je nastavena na falsehodnotu . 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. Tento filtr funkcí lze předat parametry, které se mají použít jako konfigurace. V tomto příkladu předá čas TimeWindowFilterzačátku a konce, během kterého 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 informace o povolení příznaku funkce. 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říznaku funkce

FeatureManager je objekt, @Bean který lze @Autowired vložit do @Component objektů typu. 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:

FeatureManger má také asynchronní verzi volaného isEnabledisEnabledAsync.

Pokud jste nenakonfigurovali správu funkcí nebo příznak funkce neexistuje, isEnabled vždy se vrátí false. Pokud je příznak existující funkce nakonfigurovaný s neznámým filtrem funkcí, FilterNotFoundException vyvolá se chyba. Toto chování můžete změnit tak, aby se vrátilo false konfigurací falsefail-fast . 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, RuntimeException vyvolá se chyba. Pokud je tato vlastnost nastavena na false, vrátí falseisEnabled místo toho.	No	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.

Zakázané 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 obsahuje spring-cloud-azure-feature-management několik filtrů funkcí. Tyto filtry funkcí se nepřidají automaticky, ale můžete je nastavit v souboru @Configuration.

AlwaysOnFilter

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

PercentageFilter

Pokaždé, když uživatel provede požadavek, 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 do mezipaměti pro jednotlivé uživatele. Tato funkce zajišťuje, že uživatel bude mít konzistentní prostředí, i když bude muset žádost znovu odeslat.

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

TimeWindowFilter

Tento filtr poskytuje možnost povolit funkci na základě časového intervalu. Pokud zadáte jenom Endtuto funkci, bude funkce do té doby považována za zapnutou. Pokud zadáte jenom Starttuto funkci, bude funkce považovaná za všechny body po uplynutí této doby. Pokud zadáte obojí, funkce se považuje za platnou mezi těmito dvěma časy.

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

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é procentuální hodnotě některého ze zavedení skupin.
• Uživatel spadá do výchozího procenta uvedení.

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

Filtry vlastních 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í, evaluate volá se metoda. Pokud evaluate se vrátí true, znamená to, že by funkce měla být povolená. Pokud se vrátí false, pokračuje v vyhodnocování filtrů funkcí, dokud se nevrátí true. Pokud se vrátí falsevšechny filtry, funkce je 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. FeatureFilterEvaluationContextmá vlastnost parameters, která je .HashMap<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ů okruhu 1 zahrnutých v beta verzi se zhrouží až na 100 procent.
5. Pět procent uživatelské základny je součástí beta verze.
6. Procento zavedení se přeplní až na 100 procent a funkce se kompletně zavádí.

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 aplikaci, musíte ji přidat jako @Bean jakýkoli jiný filtr funkcí. TargetingFilter spoléhá na další @Bean přidání do aplikace TargetingContextAccessor. Umožňuje TargetingContextAccessor definovat aktuální, TargetingContext který se má použít k definování aktuálního ID uživatele a skupin, jak je znázorněno v následujícím příkladu:

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

}

Možnosti vyhodnocení cílení

Možnosti jsou k dispozici pro přizpůsobení způsobu, jakým se hodnocení cílení provádí v daném TargetingFilterprostř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í aktualizace konfigurace pro vaše konfigurace umožňuje vyžádat si nejnovější hodnoty z app Configuration Storu nebo obchodů, aniž byste museli aplikaci restartovat.

Pokud chcete povolit aktualizaci, musíte povolit monitorování spolu s aktivačními událostmi monitorování. Aktivační událost monitorování je klíč s volitelným popiskem, který kontroluje změny hodnot pro aktivaci aktualizací. 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 z klíčů kukátek na novou hodnotu. Tato změna aktivuje vytvoření protokolu. Například změna hodnoty aktivačních /application/config.message událostí následující zpráva 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í @ConfigurationProperties jsou v tomto oboru zahrnuty poznámkové boby.

Aktualizace na základě vyžádané replikace

Knihovny Sady App Configuration Spring podporují možnost pravidelně kontrolovat interval aktualizace pro změny triggerů monitorování. Ve výchozím nastavení je interval aktualizace nastavený na 30 sekund. Po uplynutí intervalu aktualizace jsou všechny triggery v daném úložišti vráceny se změnami. 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, jsou požadavky na koncové body v @RestController.

Ruční

V aplikacích, které používají pouze spring-cloud-azure-appconfiguration-configkonzolové aplikace, můžete aktualizaci aktivovat ručně voláním AppConfigurationRefreshrefreshConfiguration metody. AppConfigurationRefresh@Bean je to, že 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 konfigurací, nejen opětovné načtení z úložiště konfigurace Aplikace Azure.

Aktualizace založená na nabízených oznámeních

Knihovnu spring-cloud-azure-appconfiguration-config-web můžete nastavit tak, aby přijímala nabízená oznámení z úložiště konfigurace Aplikace Azure a 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 Poháněcího zařízení jako závislosti můžete zveřejnit koncové body aktualizace služby App Configuration. 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í.

Platnost appconfiguration-refresh vlastnosti vyprší, takže zbývající interval aktualizace se nečeká 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 oboupřípadechch 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 se pro zabezpečení přidal povinný parametr dotazu. Ve výchozím nastavení není nastavený žádný název nebo hodnota tokenu, ale pro použití koncových bodů se vyžaduje nastavení jednoho tokenu, 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 události a vyberte typ koncového bodu, který má být 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.

Potvrďte, že výběr odešle oznámení o nastavení danému identifikátoru 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čování událostí 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 vynutil aktualizaci všech konfigurací v intervalu aktualizace. 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.	No	null

spring.cloud.azure.appconfiguration.refresh-interval Při aktualizaci se nekontrolují žádné nakonfigurované klíče kukátek. 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říznaku funkce

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 uplynutí intervalu aktualizace jsou všechny příznaky funkcí v daném úložišti vráceny se změnami. 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 indikátor stavu, který kontroluje, jestli je připojení k úložišti konfigurace Aplikace Azure nebo úložišti 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í způsobilo kód chyby, který není 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í připojit k úložišti v další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 konfigurace nebo konfigurace se nepodařilo načíst při spuštění, zatímco fail-fast konfigurace úložiště byla nastavena na false.

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í ke službě Aplikace Azure Configuration a Azure Key Vault. K úpravě klientů jsou poskytována ConfigurationClientCustomizer dvě rozhraní a SecretClientCustomizerjsou k dispozici. Každé rozhraní má metodu customize , která přebírá v příslušném tvůrci spolu s String hodnotou identifikátoru URI, pro kterou se klient konfiguruje, jak je znázorněno v následujících definicích rozhraní:

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

public interface SecretClientCustomizer {
    public void setup(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:

SecretClientBuilder A ConfigurationClientBuilder 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íší 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();
    }

}