Share via

Ondersteuning voor app-configuratie

  • Artikel

In dit artikel wordt de Spring Cloud Azure-app Configuration-bibliotheek beschreven. Met deze bibliotheek worden configuraties en functievlagmen van de Azure-app Configuration-service geladen. De bibliotheek genereert PropertySource abstracties die overeenkomen met de abstracties die al zijn gegenereerd door de Spring-omgeving, zoals omgevingsvariabelen, opdrachtregelconfiguraties, lokale configuratiebestanden, enzovoort.

Spring is een opensource-toepassingsframework dat is ontwikkeld door VMware en biedt een vereenvoudigde, modulaire benadering voor het maken van Java-toepassingen. Spring Cloud Azure is een opensource-project dat naadloze Spring-integratie met Azure-services biedt.

Vereisten

Uw App Configuration-archief instellen

Gebruik de volgende opdracht om uw Azure-app Configuratiearchief te maken:

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

Met deze opdracht maakt u een nieuw, leeg configuratiearchief. U kunt uw configuraties uploaden met behulp van de volgende importopdracht:

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

Bevestig uw configuraties voordat u ze laadt. U kunt YAML-bestanden uploaden door de indeling te wijzigen in YAML. Het voorvoegselveld is belangrijk omdat het het standaardvoorvoegsel is dat door de clientbibliotheek wordt geladen.

Bibliotheekgebruik

Als u de functie in een toepassing wilt gebruiken, kunt u deze bouwen als een Spring Boot-toepassing. De handigste manier om de afhankelijkheid toe te voegen is met de Spring Boot-starter com.azure.spring:spring-cloud-azure-starter-appconfiguration-config. In het volgende voorbeeld pom.xml bestand Azure-app Configuratie wordt gebruikt:

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

Notitie

Als u Spring Boot 2.x gebruikt, moet u de spring-cloud-azure-dependencies versie instellen op 4.18.0. Zie welke versie van Spring Cloud Azure moet ik gebruiken voor meer informatie over de versie die voor deze BOM wordt gebruikt.

In het volgende voorbeeld ziet u een eenvoudige Spring Boot-toepassing met behulp van App Configuration:

@SpringBootApplication
@RestController
public class Application {

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

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

In dit voorbeeld bevat het bestand bootstrap.properties de volgende regel:

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

CONFIG_STORE_CONNECTION_STRINGis een omgevingsvariabele met de verbindingsreeks naar uw Azure-app Configuratiearchief. U hebt toegang tot uw verbindingsreeks met behulp van de volgende opdracht:

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

Als er geen configuraties zijn ingesteld, worden de configuraties die beginnen met /application/ een standaardlabel (No Label) geladen, tenzij een Spring-profiel is ingesteld, in welk geval het standaardlabel uw Spring-profiel is. Omdat het archief leeg is, worden er geen configuraties geladen, maar wordt de Azure-app bron van de configuratie-eigenschap nog steeds gegenereerd.

Er wordt een eigenschapsbron met /application/https://<name-of-your-store>.azconfig.io/ de eigenschappen van dat archief gemaakt. Het label dat in de aanvraag wordt gebruikt, wordt toegevoegd aan het einde van de naam. Als er geen label is ingesteld, is het teken \0 aanwezig als een lege spatie.

Configuratie laden

De bibliotheek ondersteunt het laden van een of meerdere App Configuration-archieven. In het geval dat een sleutel wordt gedupliceerd in meerdere winkels, resulteert het laden van alle winkels in de configuratie met de hoogste prioriteit die wordt geladen. De laatste wint. Dit proces wordt geïllustreerd in het volgende voorbeeld:

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

Als zowel de eerste als de tweede opslag dezelfde configuratie hebben, heeft de configuratie in het tweede archief de hoogste prioriteit en de laatste wint.

Notitie

U kunt Azure-app configuratie-instellingen gebruiken, zoals elke andere Spring-configuratie. Zie De belangrijkste functies in de Spring Boot-documentatie of quickstart: Een Java Spring-app maken met Azure-app-configuratie voor meer informatie.

Configuraties selecteren

Configuraties worden geladen door hun sleutel en label. Standaard worden de configuraties die beginnen met de sleutel /application/ geladen. Het standaardlabel is ${spring.profiles.active}. Als ${spring.profiles.active} dit niet is ingesteld, worden configuraties met het null label geladen. Het null label wordt weergegeven zoals (No Label) in Azure Portal.

U kunt de configuraties configureren die worden geladen door verschillende sleutel- en labelfilters te selecteren, zoals wordt weergegeven in het volgende voorbeeld:

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

De key-filter eigenschap ondersteunt de volgende filters:

Sleutelfilter Effect
* Komt overeen met een willekeurige sleutel.
abc Komt overeen met een sleutel met de naam abc.
abc* Komt overeen met sleutelnamen die beginnen met abc.
abc,xyz Komt overeen met sleutelnamen abc of xyz. Beperkt tot vijf door komma's gescheiden waarden.

De label-filter eigenschap ondersteunt de volgende filters:

Etiket Beschrijving
* Komt overeen met elk label, inclusief \0.
\0 Komt overeen met null labels, die worden weergegeven als (No Label) in Azure Portal.
1.0.0 Komt exact overeen met het label 1.0.0 .
1.0.* Komt overeen met labels die beginnen met 1.0.*.
,1.0.0 Komt overeen met labels null en 1.0.0. Beperkt tot vijf door komma's gescheiden waarden.

Als u YAML gebruikt met labelfilters en u moet beginnen, nullmoet het labelfilter tussen enkele aanhalingstekens staan, zoals wordt weergegeven in het volgende voorbeeld:

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

Notitie

U kunt niet combineren * met , filters. In dat geval moet u een extra select-waarde gebruiken.

Spring-profielen

spring.profiles.active Standaard is deze optie ingesteld als de standaardinstelling label-filter voor alle geselecteerde configuraties. U kunt deze functionaliteit overschrijven met behulp van label-filter. U kunt de Spring-profielen in het label-filter gebruik gebruiken, ${spring.profiles.active}zoals wordt weergegeven in het volgende voorbeeld:

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

In de eerste label-filterworden alle configuraties met het null label geladen, gevolgd door alle configuraties die overeenkomen met de Spring-profielen. Spring-profielen hebben prioriteit boven de null configuraties, omdat ze aan het einde staan.

In de tweede label-filterwordt de tekenreeks _local toegevoegd aan het einde van de Spring-profielen, maar alleen aan het laatste Spring-profiel.

Uitgeschakelde winkels

Met behulp van de configuratie spring.cloud.azure.appconfiguration.enabledkunt u het laden voor alle configuratiearchieven uitschakelen. Met de spring.cloud.azure.appconfiguration.stores[0].enabled configuratie kunt u een afzonderlijk archief uitschakelen.

Naast het uitschakelen van winkels kunt u ervoor zorgen dat winkels worden uitgeschakeld als ze niet worden geladen. Gebruik spring.cloud.azure.appconfiguration.stores[0].fail-fastvoor deze configuratie . Wanneer fail-fast dit is uitgeschakeld door deze in te falsestellen, RuntimeException wordt het toepassingsarchief uitgeschakeld zonder dat er configuraties worden geladen. Als een configuratiearchief is uitgeschakeld bij het opstarten, wordt het niet gecontroleerd op wijzigingen bij het vernieuwen. Er is ook geen poging om er waarden van te laden als configuraties worden bijgewerkt.

Als er een fout optreedt tijdens RuntimeException een vernieuwingscontrole of tijdens een poging om configuraties opnieuw te laden, wordt de vernieuwingspoging beëindigd en opnieuw geprobeerd nadat de refresh-interval configuratie is geslaagd.

Verificatie

De bibliotheek ondersteunt alle vormen van identiteit die worden ondersteund door de Azure Identity Library. U kunt verificatie uitvoeren via configuratie voor verbindingsreeks s en beheerde identiteit.

Connection string

Verificatie via verbindingsreeks is het eenvoudigste formulier om in te stellen. U kunt de verbindingsreeks s van een winkel openen met behulp van de volgende opdracht:

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

Vervolgens kunt u de spring.cloud.azure.appconfiguration.stores[0].connection-string eigenschap instellen op de verbindingsreeks. U wordt ten zeerste aangeraden de verbindingsreeks in het lokale configuratiebestand in te stellen op een tijdelijke aanduiding die is toegewezen aan een omgevingsvariabele. Met deze methode kunt u voorkomen dat u de verbindingsreeks toevoegt aan broncodebeheer.

Spring Cloud Azure-configuratie

U kunt de Azure-configuratie van Spring Cloud gebruiken om de bibliotheek te configureren. U kunt de volgende eigenschappen gebruiken om de bibliotheek te configureren:

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

Wanneer alleen het eindpunt is ingesteld, gebruikt de clientbibliotheek de DefaultAzureCredential om te verifiëren. Hierbij DefaultAzureCredential worden de volgende methoden gebruikt om te verifiëren:

  • Omgevingsreferenties
  • Referenties voor beheerde identiteit
  • Azure Developer CLI-referentie
  • IntelliJ-referentie
  • Azure CLI-referentie
  • Azure PowerShell-referentie

U moet een identiteit, zoals een door het systeem toegewezen identiteit, toewijzen aan leesconfiguraties. U kunt deze toewijzing maken met behulp van de volgende opdracht:

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>

Notitie

U kunt slechts één verificatiemethode per eindpunt definiëren: verbindingsreeks, door de gebruiker toegewezen identiteit of tokenreferenties. Als u wilt combineren en vergelijken, kunt u winkels wijzigen die een andere methode gebruiken ConfigurationClientCustomizer .

Geo-replicatie

De bibliotheek ondersteunt de functie voor geo-replicatie van Azure-app-configuratie. Met deze functie kunt u uw gegevens repliceren naar andere locaties. Deze functie is handig voor hoge beschikbaarheid en herstel na noodgevallen.

Elke replica die u maakt, heeft een toegewezen eindpunt. Als uw toepassing zich in meerdere geolocaties bevindt, kunt u elke implementatie van uw toepassing bijwerken op een locatie om verbinding te maken met de replica dichter bij die locatie, waardoor de netwerklatentie tussen uw toepassing en App Configuration wordt geminimaliseerd. Omdat elke replica een afzonderlijk aanvraagquotum heeft, helpt deze installatie ook de schaalbaarheid van uw toepassing terwijl deze groeit naar een gedistribueerde service met meerdere regio's.

De failover kan optreden als de bibliotheek aan een van de volgende voorwaarden voldoet:

  • Ontvangt antwoorden met servicestatuscode (HTTP 500 of hoger) van een eindpunt.
  • Ondervindt netwerkverbindingsproblemen.
  • Aanvragen worden beperkt (HTTP-statuscode 429).

Een configuratiearchief maken met geo-replicatie

Als u een replica van uw configuratiearchief wilt maken, kunt u de Azure CLI of Azure Portal gebruiken. In het volgende voorbeeld wordt de Azure CLI gebruikt om een replica te maken in de regio VS - oost 2:

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

De replica van het configuratiearchief gebruiken

Nadat u een replica hebt gemaakt, kunt u deze gebruiken in uw toepassing. Net als de origin Store kunt u verbinding maken met uw replica met behulp van Microsoft Entra ID of een verbindingsreeks.

Als u Microsoft Entra ID wilt gebruiken om verbinding te maken met uw replica, moet u de endpoints exemplaren van uw configuratiearchief weergeven, zoals wordt weergegeven in het volgende voorbeeld:

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

U kunt zoveel eindpunten weergeven als u replica's hebt. De bibliotheek probeert verbinding te maken met de eindpunten in de volgorde waarin ze worden weergegeven. Als de bibliotheek geen verbinding kan maken met een replica, wordt de volgende in de lijst geprobeerd. Nadat een bepaalde periode is verstreken, probeert de bibliotheek opnieuw verbinding te maken met de voorkeurseindpunten.

Sleutelwaarden

Azure-app Configuration ondersteunt meerdere typen sleutelwaarden, waarvan sommige speciale functies hebben ingebouwd. Azure-app Configuration biedt ingebouwde ondersteuning voor het JSON-inhoudstype, tijdelijke aanduidingen voor Spring en Key Vault-verwijzingen.

Tijdelijke aanduidingen

De bibliotheek ondersteunt configuraties met ${}tijdelijke aanduidingen voor de omgeving in -style. Wanneer u verwijst naar een Azure-app-configuratiesleutel met een tijdelijke aanduiding, verwijdert u voorvoegsels uit de verwijzing. Er wordt bijvoorbeeld /application/config.message naar verwezen als ${config.message}.

Notitie

Het voorvoegsel dat wordt verwijderd, komt overeen met de waarde spring.cloud.azure.appconfiguration.stores[0].selects[0].key-filter.

JSON

Configuraties met een inhoudstype application/json worden verwerkt als JSON-objecten. Met deze functie kunt u één configuratie toewijzen aan een complex object in een @ConfigurationProperties. Denk bijvoorbeeld aan de JSON-sleutel /application/config.colors met de volgende waarde:

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

Deze sleutel wordt toegewezen aan de volgende code:

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

    private Map<String, Color> colors;

}

Key Vault-verwijzingen

Azure-app Configuratie en de bijbehorende bibliotheken ondersteunen het verwijzen naar geheimen die zijn opgeslagen in Key Vault. In App Configuration kunt u sleutels maken met waarden die zijn toegewezen aan geheimen die zijn opgeslagen in een Sleutelkluis. Geheimen worden veilig opgeslagen in Key Vault, maar kunnen op dezelfde manier worden geopend als elke andere configuratie nadat deze is geladen.

Uw toepassing gebruikt de clientprovider om Key Vault-verwijzingen op te halen, net zoals voor andere sleutels die zijn opgeslagen in App Configuration. Omdat de client de sleutels herkent als Key Vault-verwijzingen, hebben ze een uniek inhoudstype en maakt de client verbinding met Key Vault om hun waarden voor u op te halen.

Notitie

Key Vault staat alleen toe dat geheimen één voor één worden opgehaald, dus elke Key Vault-verwijzing die is opgeslagen in App Configuration, resulteert in een pull voor Key Vault.

Key Vault-verwijzingen maken

U kunt een Key Vault-verwijzing maken in De Azure-portal door naar Configuration Explorer>>Key Vault-verwijzing maken te gaan. Vervolgens kunt u een geheim selecteren waarnaar u wilt verwijzen vanuit een van de key vaults waar u toegang tot hebt. U kunt ook willekeurige Key Vault-verwijzingen maken op het tabblad Invoer . Voer in Azure Portal een geldige URI in.

U kunt ook een Key Vault-verwijzing maken via de Azure CLI met behulp van de volgende opdracht:

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

U kunt elke geheime id maken via de Azure CLI. Geheime id's vereisen alleen de indeling {vault}/{collection}/{name}/{version?} waarin de versiesectie optioneel is.

Key Vault-verwijzingen gebruiken

U kunt de Azure-configuratie van Spring Cloud gebruiken om de bibliotheek te configureren. U kunt dezelfde referentie gebruiken om verbinding te maken met App Configuration om verbinding te maken met Azure Key Vault.

Niet-Key Vault-geheimen oplossen

De App Configuration-bibliotheek biedt een methode voor het lokaal oplossen van geheimen waaraan geen Key Vault is gekoppeld. Deze resolutie wordt gedaan via de KeyVaultSecretProvider. De KeyVaultSecretProvider naam wordt aangeroepen wanneer een TokenCredential niet is opgegeven voor een Key Vault-verwijzing. De URI van de Key Vault-verwijzing wordt opgegeven en de geretourneerde waarde wordt de waarde van het geheim.

Waarschuwing

Het gebruik van een KeyVaultSecretProvider overschrijft het automatische gebruik van de door het systeem toegewezen beheerde identiteit. Als u beide wilt gebruiken, moet u de URI's gebruiken KeyVaultCredentialProvider en retourneren null die moeten worden omgezet.

public class MySecretProvider implements KeyVaultSecretProvider {

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

}

Functiebeheer

Functiebeheer biedt een manier voor Spring Boot-toepassingen om dynamisch toegang te krijgen tot inhoud. Functiebeheer heeft verschillende functies, zoals de volgende:

  • Functievlagmen die inhoud kunnen in- of uitschakelen
  • Functiefilters voor targeting wanneer inhoud wordt weergegeven
  • Aangepaste functiefilters
  • Functiepoorten voor het dynamisch inschakelen van eindpunten

U kunt functievlagmen inschakelen via de volgende configuratie:

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

Ingeschakelde functievlagmen worden geladen in het Spring-configuratiesysteem met het voorvoegsel feature-management. U kunt ook functievlagmen registreren in het lokale configuratiebestand. Zie de sectie Functievlagdeclaratie voor meer informatie.

De eenvoudigste manier om functiebeheer te gebruiken, is door gebruik te maken van de spring-cloud-azure-feature-management en spring-cloud-azure-feature-management-web bibliotheken. Het verschil tussen de twee bibliotheken is dat spring-cloud-azure-feature-management-web afhankelijk is van de spring-web en spring-webmvc bibliotheken om meer functies toe te voegen, zoals functiepoorten.

U kunt functievlagmen inschakelen met behulp van sleutel-/labelfilters. Standaard wordt een null label, gezien als (No Label), toegewezen. U kunt de functievlagmen configureren die worden geladen door een labelfilter in te stellen, zoals wordt weergegeven in het volgende voorbeeld:

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

Basisprincipes van functiebeheer

Functievlaggen

Functievlagmen bestaan uit twee onderdelen: een naam en een lijst met functiefilters die worden gebruikt om de functie in te schakelen. Functievlagmen kunnen een booleaanse status aan/uit hebben, of ze kunnen een lijst met functiefilters hebben. Functievlagmen evalueren functiefilters totdat een functie wordt geretourneerd true. Als er geen functiefilter wordt geretourneerd true, wordt de functievlag geretourneerd false.

Functiefilters

Functiefilters definiëren een scenario voor wanneer een functie moet worden ingeschakeld. Functiefilters worden synchroon geëvalueerd.

De functiebeheerbibliotheek wordt geleverd met vier vooraf gedefinieerde filters: AlwaysOnFilter, PercentageFilter, TimeWindowFilter en TargetingFilter.

U kunt aangepaste functiefilters maken. U kunt bijvoorbeeld een functiefilter gebruiken om een aangepaste ervaring te bieden voor klanten die een Microsoft Edge-browser gebruiken. U kunt de functies in dit functiefilter bijvoorbeeld aanpassen om een specifieke koptekst weer te geven voor de doelgroep van de Microsoft Edge-browser.

Declaratie van functievlaggen

De bibliotheek voor functiebeheer ondersteunt Azure-app Configuratie, samen met application.yml of bootstrap.yml als bronnen voor functievlagmen. Hier volgt een voorbeeld van de indeling die wordt gebruikt voor het instellen van functievlagmen in een application.yml-bestand :

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

In dit voorbeeld zijn de volgende functievlagmen beschikbaar:

  • feature-t is ingesteld op false. Deze instelling retourneert altijd de waarde van de functievlag.
  • feature-u wordt gebruikt met functiefilters. Deze filters worden gedefinieerd onder de enabled-for eigenschap. In dit geval feature-u heeft u één functiefilter aangeroepen Random, waarvoor geen configuratie is vereist, dus alleen de naameigenschap is vereist.
  • feature-v hiermee geeft u een functiefilter met de naam TimeWindowFilter. Dit functiefilter kan parameters worden doorgegeven die moeten worden gebruikt als configuratie. In dit voorbeeld geeft een TimeWindowFilter, de begin- en eindtijd door waarin de functie actief is.
  • feature-wwordt gebruikt voor de AlwaysOnFilter, die altijd evalueert .true Het evaluate veld wordt gebruikt om de evaluatie van de functiefilters te stoppen en resulteert in het functiefilter dat altijd wordt geretourneerd false.

Functievlagmen evalueren

De spring-cloud-azure-feature-management bibliotheek biedt FeatureManager om te bepalen of een functievlag is ingeschakeld. FeatureManager biedt een asynchrone manier om de status van de vlag te controleren.

spring-cloud-azure-feature-management-webbevat, samen met het opgeven FeatureManagervan, FeatureManagerSnapshotbevat, waarmee de status van eerder geëvalueerde functievlagmen in de @RequestScope cache wordt opgeslagen om te garanderen dat alle aanvragen dezelfde waarde retourneren. Daarnaast biedt @FeatureGatede webbibliotheek, die webaanvragen kan blokkeren of omleiden naar verschillende eindpunten.

Controle van functievlag

FeatureManager is een @Bean object dat kan worden @Autowired opgenomen of geïnjecteerd in @Component typeobjecten. FeatureManager heeft een methode isEnabled die, wanneer de naam van een functievlag wordt doorgegeven, de status retourneert.

@Autowired
FeatureManager featureManager;

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

Notitie

FeatureManger heeft ook een asynchrone versie van isEnabled de aangeroepen isEnabledAsync.

Als u geen functiebeheer hebt geconfigureerd of als de functievlag niet bestaat, isEnabled wordt altijd geretourneerd false. Als een bestaande functievlag is geconfigureerd met een onbekend functiefilter, wordt er een FilterNotFoundException gegenereerd. U kunt dit gedrag wijzigen om terug te keren false door deze te fail-fast configureren in false. In de volgende tabel wordt het volgende beschreven fail-fast:

Name Beschrijving Vereist Standaardinstelling
spring.cloud.azure.feature.management.fail-fast Als er een uitzondering optreedt, wordt er een RuntimeException gegenereerd. Als deze eigenschap is ingesteld op false, wordt in isEnabled plaats daarvan geretourneerd false . Nee true

Het enige verschil tussen FeatureManagerSnapshot en FeatureManager is de caching van resultaten in de @RequestScope.

Functiepoort

Met de webbibliotheek voor functiebeheer kunt u vereisen dat een bepaalde functie is ingeschakeld om een eindpunt uit te voeren. U kunt deze vereiste instellen met behulp van de @FeatureGate aantekening, zoals wordt weergegeven in het volgende voorbeeld:

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

U hebt alleen toegang tot het featureT eindpunt als 'feature-t' is ingeschakeld.

Afhandeling van uitgeschakelde acties

Wanneer een eindpunt wordt geblokkeerd omdat de functie die wordt opgegeven, is uitgeschakeld, DisabledFeaturesHandler wordt aangeroepen. Standaard wordt een HTTP 404 geretourneerd. U kunt dit gedrag overschrijven door te implementeren DisabledFeaturesHandler, zoals wordt weergegeven in het volgende voorbeeld:

@Component
public class MyDisabledFeaturesHandler implements DisabledFeaturesHandler {

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

}
Routering

Bepaalde routes kunnen toepassingsmogelijkheden beschikbaar maken die worden beveiligd door functies. Als een functie is uitgeschakeld, kunt u deze routes omleiden naar een ander eindpunt, zoals wordt weergegeven in het volgende voorbeeld:

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

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

Ingebouwde functiefilters

Er zijn enkele functiefilters die bij het spring-cloud-azure-feature-management pakket worden geleverd. Deze functiefilters worden niet automatisch toegevoegd, maar u kunt ze instellen in een @Configuration.

AlwaysOnFilter

Dit filter retourneert truealtijd . Zie de sectie functievlagdeclaratie voor een gebruiksvoorbeeld.

PercentageFilter

Telkens wanneer een gebruiker een aanvraag indient, kan de evaluatie PercentageFilter een ander resultaat retourneren. U kunt deze inconsistentie omzeilen met behulp van de FeatureManagementSnapshotfunctievlag die het resultaat van de functievlag per gebruiker in de cache opgeslagen. Deze mogelijkheid zorgt ervoor dat een gebruiker een consistente ervaring heeft, zelfs als ze de aanvraag opnieuw moeten verzenden.

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

TimeWindowFilter

Dit filter biedt de mogelijkheid om een functie in te schakelen op basis van een tijdvenster. Als u alleen opgeeft End, wordt de functie tot die tijd overwogen. Als u alleen opgeeft Start, wordt de functie op alle punten na die tijd overwogen. Als u beide opgeeft, wordt de functie tussen de twee keer als geldig beschouwd.

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

Dit filter biedt de mogelijkheid om een functie in te schakelen voor een doelgroep. Zie de sectie targetingsectie voor een uitgebreide uitleg van targeting. De filterparameters bevatten een doelgroepobject dat gebruikers, groepen en een standaardpercentage van de gebruikersbasis beschrijft die toegang tot de functie moeten hebben. Voor elk groepsobject dat wordt vermeld in de doelgroep, is een percentage vereist dat het percentage van de leden van die groep definieert die toegang hebben tot de functie. Een gebruiker heeft de functie ingeschakeld in de volgende gevallen:

  • De gebruiker wordt rechtstreeks in de sectie gebruikers opgegeven.
  • De gebruiker bevindt zich in het opgenomen percentage van een van de groeps-implementaties.
  • De gebruiker valt in het standaardpercentage voor de implementatie.
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

Aangepaste functiefilters

Het maken van een aangepast functiefilter biedt een manier om functies in te schakelen op basis van criteria die u definieert. Als u een aangepast functiefilter wilt maken, moet u de FeatureFilter interface implementeren. FeatureFilter heeft één methode evaluate. Wanneer een functie aangeeft dat deze kan worden ingeschakeld met een functiefilter, wordt de evaluate methode aangeroepen. Als evaluate de functie wordt geretourneerd true, betekent dit dat de functie moet worden ingeschakeld. Als de functie wordt geretourneerd false, wordt de functiefilters nog steeds geëvalueerd totdat één filter wordt geretourneerd true. Als alle filters worden geretourneerd false, is de functie uitgeschakeld.

Functiefilters worden gedefinieerd als Spring Beans, dus ze worden gedefinieerd als @Component of gedefinieerd in een @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;
    }

}

Geparameteriseerde functiefilters

Voor sommige functiefilters zijn parameters vereist om te bepalen of een functie moet worden ingeschakeld. Een browserfunctiefilter kan bijvoorbeeld een functie inschakelen voor een bepaalde set browsers. Mogelijk wilt u een functie inschakelen voor Microsoft Edge- en Chrome-browsers, maar niet Voor Firefox. Als u deze situatie wilt instellen, kunt u een functiefilter ontwerpen om parameters te verwachten. Deze parameters worden opgegeven in de functieconfiguratie en in code en zijn toegankelijk via de FeatureFilterEvaluationContext parameter van evaluate. FeatureFilterEvaluationContext heeft een eigenschap parameters, een HashMap<String, Object>.

Targeten

Het doel is een strategie voor functiebeheer waarmee ontwikkelaars geleidelijk nieuwe functies kunnen implementeren in hun gebruikersbestand. De strategie is gebaseerd op het concept van het richten van een set gebruikers die bekend staan als de doelgroep. Een doelgroep bestaat uit specifieke gebruikers, groepen en een aangewezen percentage van de gehele gebruikersbasis. De groepen die in de doelgroep zijn opgenomen, kunnen verder worden onderverdeeld in percentages van hun totale leden.

In de volgende stappen ziet u een voorbeeld van een progressieve implementatie voor een nieuwe bètafunctie:

  1. Individuele gebruikers Jeff en Alicia krijgen toegang tot de bètaversie.
  2. Een andere gebruiker, Mark, vraagt zich aan te kiezen en is inbegrepen.
  3. Twintig procent van een groep die bekend staat als Ring1-gebruikers, worden opgenomen in de bètaversie.
  4. Het aantal ring1-gebruikers dat in de bètaversie is opgenomen, wordt tot 100 procent opgestoten.
  5. Vijf procent van de gebruikersbasis is opgenomen in de bètaversie.
  6. Het implementatiepercentage wordt maximaal 100 procent opgestoten en de functie wordt volledig uitgerold.

Deze strategie voor het implementeren van een functie is ingebouwd in de bibliotheek via het opgenomen TargetingFilter functiefilter.

Targeting in een toepassing

Een voorbeeldwebtoepassing die gebruikmaakt van het doelfunctiefilter is beschikbaar in het voorbeeldproject.

Als u de TargetingFilter toepassing in een toepassing wilt gaan gebruiken, moet u deze toevoegen als een @Bean ander functiefilter. TargetingFilter is afhankelijk van een andere @Bean die aan de toepassing TargetingContextAccessormoet worden toegevoegd. Hiermee TargetingContextAccessor kunt u de huidige TargetingContext gebruiken voor het definiëren van de huidige gebruikers-id en groepen, zoals wordt weergegeven in het volgende voorbeeld:

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

}

Evaluatieopties instellen

Er zijn opties beschikbaar om aan te passen hoe doelevaluatie wordt uitgevoerd in een bepaalde TargetingFilter. U kunt tijdens het TargetingFilter maken een optionele parameter TargetingEvaluationOptionsinstellen.

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

Configuratie vernieuwen

Als u het vernieuwen van configuraties voor uw configuraties inschakelt, kunt u de meest recente waarden ophalen uit uw App Configuration-archief of -archieven zonder dat u de toepassing opnieuw hoeft te starten.

Als u vernieuwen wilt inschakelen, moet u bewaking inschakelen, samen met bewakingstriggers. Een bewakingstrigger is een sleutel met een optioneel label dat wordt gecontroleerd op waardewijzigingen om updates te activeren. De waarde van de bewakingstrigger kan elke waarde zijn, zolang deze verandert wanneer een vernieuwing nodig is.

Notitie

Elke bewerking die de ETag van een bewakingstrigger wijzigt, veroorzaakt een vernieuwing, zoals een wijziging van het inhoudstype.

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

Als u een configuratievernieuwing wilt activeren, wijzigt u de waarde van een sleutel in uw configuratiearchief. Werk vervolgens een van de horlogesleutels bij naar een nieuwe waarde. Met deze wijziging wordt het maken van een logboek geactiveerd. Als u bijvoorbeeld de waarde van /application/config.message triggers wijzigt, wordt het volgende logboekbericht weergegeven:

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

Nadat de toepassing het logboek heeft gegenereerd, worden alle @Beanbestanden vernieuwd in het vernieuwingsbereik.

Notitie

Geannoteerde bonen zijn standaard @ConfigurationProperties opgenomen in dit bereik.

Vernieuwen op basis van pull

De Spring-bibliotheken van App Configuration ondersteunen de mogelijkheid om periodiek te controleren op een vernieuwingsinterval voor wijzigingen die zijn aangebracht in de bewakingstriggers. Het vernieuwingsinterval is standaard ingesteld op 30 seconden. Nadat het vernieuwingsinterval is verstreken, worden alle triggers gecontroleerd in het opgegeven archief voor wijzigingen. Elke wijziging in de sleutel zorgt ervoor dat een vernieuwing wordt geactiveerd. Omdat de bibliotheken zijn geïntegreerd met het Spring Refresh-systeem, worden bij elke vernieuwing alle configuraties uit alle winkels opnieuw geladen. U kunt het vernieuwingsinterval instellen op een interval dat langer is dan 1 seconde. De ondersteunde eenheden voor het vernieuwingsinterval zijn srespectievelijk seconden dmh, minuten, uren en dagen. In het volgende voorbeeld wordt het vernieuwingsinterval ingesteld op 5 minuten:

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

Geautomatiseerd

Wanneer u de spring-cloud-azure-appconfiguration-config-web bibliotheek gebruikt, controleert de toepassing automatisch op een vernieuwing wanneer een servlet-aanvraag plaatsvindt, met name ServletRequestHandledEvent. De meest voorkomende manier waarop deze gebeurtenis wordt verzonden, is door aanvragen naar eindpunten in een @RestController.

Handmatig

In toepassingen die alleen spring-cloud-azure-appconfiguration-configworden gebruikt, zoals consoletoepassingen, kunt u handmatig een vernieuwing activeren door de methode aan refreshConfiguration te roepenAppConfigurationRefresh. AppConfigurationRefresh is een @Bean die u kunt injecteren in elke @Component.

Omdat de bibliotheek gebruikmaakt van het configuratiesysteem van Spring, zorgt het activeren van een vernieuwing ook voor een vernieuwing van al uw configuraties, niet alleen voor het opnieuw laden van de configuraties uit uw Azure-app Configuratiearchief.

Push-gebaseerde vernieuwing

U kunt de spring-cloud-azure-appconfiguration-config-web bibliotheek instellen voor het ontvangen van pushmeldingen van uw Azure-app Configuratiearchief om uw configuratiewaarden te vernieuwen. U kunt deze configuratie instellen via een Azure Event Grid-webhook, die u kunt configureren voor het verzenden van meldingen van wijzigingen naar opgegeven sleutels. Door de Spring Actuator-bibliotheek als een afhankelijkheid toe te voegen, kunt u de vernieuwingseindpunten van App Configuration beschikbaar maken. Er zijn twee verschillende eindpunten: appconfiguration-refresh en appconfiguration-refresh-bus. Deze eindpunten werken op dezelfde manier als hun tegenhangers refresh en refresh-bus, waarbij de app-configuratie-eindpunten het vernieuwingsinterval laten verlopen in plaats van een vernieuwing af te dwingen bij ontvangst. U kunt de refresh en refresh-bus, maar u kunt ze niet rechtstreeks verbinden met Azure Event Grid met een webhook, omdat ze een reactie in de installatie vereisen.

De appconfiguration-refresh eigenschap verloopt het vernieuwingsinterval, zodat het resterende vernieuwingsinterval niet wordt gewacht voordat de volgende vernieuwingscontrole wordt uitgevoerd. De appconfiguration-refresh-bus eigenschap verzendt een melding naar een verbonden berichtenservice, zoals Azure Service Bus, om alle exemplaren van een toepassing op de hoogte te stellen om te vernieuwen. In beide gevallen verloopt het niet volledig bij het vernieuwingsinterval, maar is deze uitgeschakeld met een kleine jitterhoeveelheid. Deze jitter zorgt ervoor dat elk exemplaar van uw toepassing niet tegelijkertijd probeert te vernieuwen.

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

Naast het beschikbaar maken van de vernieuwingseindpunten, is er een vereiste queryparameter toegevoegd voor beveiliging. Er is standaard geen tokennaam of -waarde ingesteld, maar het instellen hiervan is vereist om de eindpunten te kunnen gebruiken, zoals wordt weergegeven in het volgende voorbeeld:

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]

Webhook instellen

Als u een webhook wilt instellen, opent u het Azure-app Configuratiearchief en opent u Gebeurtenissen vanuit het navigatiemenu. Selecteer vervolgens Gebeurtenisabonnement. Stel de naam van uw gebeurtenis in en selecteer het eindpunttype dat webhook moet zijn. Als u Webhook selecteert, wordt er een eindpuntoptie weergegeven. Selecteer Select an endpoint (Een eindpunt selecteren). Uw eindpunt moet eruitzien als in het volgende voorbeeld: https://www.myaplication.com/actuator/appconfiguration-refresh?myTokenName=mySecret.

Bevestig dat Selectie een installatiemelding naar de opgegeven URI verzendt en er een antwoord wordt verwacht. Als er geen antwoord wordt geretourneerd, mislukt de installatie. De azure-spring-cloud-appconfiguration-web bibliotheekinstallatie voor eindpunten retourneert het juiste antwoord als het Azure-app Configuratiearchief is geconfigureerd voor de toepassing. Deze bevestiging kan op andere manieren worden verzonden. Zie De levering van webhook-gebeurtenissen voor meer informatie over webhooklevering.

Notitie

Deze validatie vindt alleen plaats bij het maken of wijzigen van het eindpunt.

U wordt ten zeerste aangeraden filters in te stellen, omdat anders een vernieuwing wordt geactiveerd na het maken en wijzigen van de sleutel.

Geforceerde client vernieuwen

U kunt de bibliotheek zo configureren dat alle configuraties met een vernieuwingsinterval worden geforceerd vernieuwd. In de volgende tabel wordt de refresh-interval eigenschap beschreven:

Name Beschrijving Vereist Standaardinstelling
spring.cloud.azure.appconfiguration.refresh-interval De standaardtijd tussen vernieuwingen. Is een Duration. Nee Nul

Vernieuwen met spring.cloud.azure.appconfiguration.refresh-interval controleert geen geconfigureerde watchsleutels. Deze eigenschap wordt gebruikt om ervoor te zorgen dat Key Vault-geheimen up-to-date blijven, omdat Azure-app Configuratie niet kan zien wanneer ze worden bijgewerkt.

Omdat Azure Key Vault het openbare en persoonlijke sleutelpaar van een certificaat als geheim opslaat, kan uw toepassing elk certificaat ophalen als key vault-verwijzing in App Configuration. Omdat certificaten periodiek moeten worden geroteerd, moeten clienttoepassingen net zo vaak worden bijgewerkt, wat kan worden gedaan met behulp van het vernieuwingsinterval van de client.

Functievlag vernieuwen

Als functievlagmen en bewaking beide zijn ingeschakeld, wordt het vernieuwingsinterval voor functievlagmen standaard ingesteld op 30 seconden. Nadat het vernieuwingsinterval is verstreken, worden alle functievlagmen gecontroleerd in het opgegeven archief op wijzigingen. Elke wijziging in de sleutel zorgt ervoor dat een vernieuwing wordt geactiveerd. Omdat de bibliotheken zijn geïntegreerd met het Spring Refresh-systeem, worden bij elke vernieuwing alle configuraties uit alle winkels opnieuw geladen. U kunt het vernieuwingsinterval instellen op een interval dat langer is dan 1 seconde. De ondersteunde eenheden voor het vernieuwingsinterval zijn srespectievelijk seconden dmh, minuten, uren en dagen. In het volgende voorbeeld wordt het vernieuwingsinterval ingesteld op 5 minuten:

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

Statusindicator

De clientbibliotheek wordt geleverd met een statusindicator waarmee wordt gecontroleerd of de verbinding met het Azure-app Configuratiearchief of -archieven in orde is. Als deze optie is ingeschakeld voor elk archief, krijgt deze een van de volgende statuswaarden:

  • UP: de laatste verbinding is geslaagd.
  • DOWN- De laatste verbinding heeft geresulteerd in een niet-200-foutcode. Deze status kan worden veroorzaakt door problemen, variërend van referenties die verlopen tot een serviceprobleem. De clientbibliotheek probeert automatisch opnieuw verbinding te maken met de store tijdens het volgende vernieuwingsinterval.
  • NIET GELADEN: het configuratiearchief wordt vermeld in het lokale configuratiebestand, maar het configuratiearchief is niet geladen vanuit het bestand bij het opstarten. Het configuratiearchief is uitgeschakeld in het configuratiebestand of de configuratie of configuraties zijn niet geladen tijdens het opstarten terwijl de fail-fast configuratie voor het archief is ingesteld op false.

U kunt de statusindicator inschakelen door de instelling in te stellen management.health.azure-app-configuration.enabled=true.

Clientaanpassing

De App Configuration-bibliotheek maakt gebruik van de Azure SDK voor Java om verbinding te maken met Azure-app Configuratie en Azure Key Vault. Er zijn twee interfaces ConfigurationClientCustomizer en SecretClientCustomizer, beschikbaar om de clients te wijzigen. Elke interface heeft een customize methode die in hun respectieve opbouwfunctie wordt gebruikt, samen met de String waarde van de URI waarvoor de client wordt geconfigureerd, zoals wordt weergegeven in de volgende interfacedefinities:

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

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

Met deze interfaces kunnen de HTTP-client en de bijbehorende configuraties worden aangepast. In het volgende voorbeeld wordt de standaardwaarde HttpClient vervangen door een andere die gebruikmaakt van een proxy voor al het verkeer dat wordt omgeleid naar App Configuration en Key Vault.

Notitie

De ConfigurationClientBuilder en SecretClientBuilder zijn al ingesteld voor gebruik wanneer ze worden doorgegeven aan customize. Wijzigingen in de clients, inclusief de referenties en het beleid voor opnieuw proberen, overschrijven deze al.

U kunt deze configuratie ook uitvoeren met behulp van de Spring Cloud Azure-configuratie.

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

}