Ondersteuning voor app-configuratie

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

• Een Azure-abonnement (u kunt een gratis abonnement maken).
• Java Development Kit (JDK) versie 8 of hoger.
• Apache Maven
• Azure-CLI

Uw App Configuration-winkel instellen

Gebruik de volgende opdracht om je Azure-appconfiguratieopslag 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 het formaat op YAML in te stellen. 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>7.0.0-beta.1</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>

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 application.properties de volgende regel:

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

CONFIG_STORE_ENDPOINT is een omgevingsvariabele met de eindpunt-URL naar uw Azure App Configuration Store.

Als er geen configuraties zijn ingesteld, worden de configuraties die beginnen met /application/ geladen met een standaardlabel van (No Label), tenzij er een Spring-profiel is ingesteld, in dat geval is het standaardlabel uw Spring-profiel.

Er wordt een eigenschapsbron gemaakt die de eigenschappen van die winkel bevat. 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 één of meerdere App Configuration-opslagplaatsen. In de situatie waarin een sleutel wordt gedupliceerd in meerdere winkels, wint de laatste.

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

Als beide winkels in dit voorbeeld dezelfde configuratiesleutel hebben, heeft de configuratie in het tweede archief de hoogste prioriteit.

Configuraties selecteren

De bibliotheek laadt configuraties met behulp van hun sleutel en label. Standaard worden de configuraties die beginnen met de sleutel /application/ geladen. Het standaardlabel is \0, dat wordt weergegeven als (No Label) in Azure Portal. Als er een Spring-profiel is ingesteld en er geen label is opgegeven, is het standaardlabel uw Spring-profiel.${spring.profiles.active}

U kunt configureren welke configuraties worden geladen door verschillende sleutel- en labelfilters te selecteren:

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:

De label-filter eigenschap ondersteunt de volgende filters:

Als u YAML met labelfilters gebruikt en u configuraties zonder label en meer configuraties met andere labels wilt laden, moet u een lege ,map opnemen. Bijvoorbeeld ,dev overeenkomsten \0 en dev. In dit geval plaatst u het labelfilter tussen enkele aanhalingstekens. Met deze waarde kunt u de configuratie zonder label eerst laden, gevolgd door configuraties met specifieke labels, in hetzelfde filter:

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

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 gebruiken met ${spring.profiles.active}, zoals in het volgende voorbeeld wordt getoond:

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-filterlaadt de bibliotheek eerst alle configuraties met het \0 label, gevolgd door alle configuraties die overeenkomen met de Spring-profielen. Spring-profielen hebben prioriteit boven de \0 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 als er meer dan één is.

Uitgeschakelde winkels

Met behulp van de configuratie spring.cloud.azure.appconfiguration.enabledkunt u het laden voor alle configuratiearchieven uitschakelen. Met de configuratie spring.cloud.azure.appconfiguration.stores[0].enabled kun je een individuele winkel uitschakelen.

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.

Connectiestring (niet aanbevolen)

Verificatie via verbindingsreeks is het eenvoudigste formulier om in te stellen, hoewel dit niet wordt aanbevolen. 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. Wanneer u deze methode gebruikt, raden we u ten zeerste aan om de verbindingsreeks in het lokale configuratiebestand in te stellen op een tijdelijke aanduiding die wordt 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.

U moet de identiteit toewijzen die wordt gebruikt voor het lezen van configuraties. 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>

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.

Standaard detecteert de bibliotheek automatisch alle replica's die bestaan voor een configuratiearchief. Wanneer er een aanvraag wordt ingediend bij het opgegeven archief en mislukt, wordt de aanvraag automatisch opnieuw uitgevoerd op basis van de beschikbare replica's.

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

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

Nadat de opgegeven winkel weer online is, probeert de bibliotheek de aanvraag automatisch opnieuw uit te voeren voor de opgegeven winkel.

Als u het failovergedrag wilt beheren, kunt u handmatig een lijst met winkels opgeven die moeten worden gebruikt voor failover.

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

of

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]

Als alle opgegeven replica-eindpunten mislukken, probeert de bibliotheek verbinding te maken met automatisch gedetecteerde replica's van het primaire archief.

U kunt replicatie uitschakelen met de instelling spring.cloud.azure.appconfiguration.stores[0].replica-discovery-enabled=false.

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]

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.

Plaatsaanduidingen

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

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 komt overeen met 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 blijven veilig in Key Vault, maar u kunt ze op dezelfde manier openen als bij het laden van de app.

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.

Key Vault-verwijzingen maken

U kunt een Key Vault-verwijzing maken in de Azure-portal door naar Configuration explorer>Create>Key Vault reference 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.

U kunt ook een SecretClientCustomizer dezelfde manier maken als u een ConfigurationClientCustomizer methode maakt om uw eigen verificatiemethode op te geven.

Niet-Key Vault-geheimen oplossen

De App Configuration-bibliotheek biedt een methode voor het overschrijven van de resolutie van sleutelkluisverwijzingen. U kunt deze bijvoorbeeld gebruiken om geheimen lokaal op te lossen in een ontwikkelomgeving. Deze resolutie wordt gerealiseerd door de KeyVaultSecretProvider. De KeyVaultSecretProvider, indien opgegeven, wordt aangeroepen op elke sleutelkluisverwijzing. Als getSecret een niet-null-waarde wordt geretourneerd, wordt deze gebruikt als de geheime waarde. Anders wordt de Key Vault-verwijzing normaal opgelost.

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

Alle functievlagmen met een \0 label, gezien als (No Label), worden standaard geladen. 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 meerdere onderdelen, waaronder een naam en een lijst met functiefilters die worden gebruikt om de functie in te schakelen. Functievlagmen kunnen een Booleaanse status in- of uitschakelen, of ze kunnen een lijst met functiefilters hebben. Functievlaggen evalueren functiefilters totdat er een wordt geretourneerd true. Als er geen functiefilter true oplevert, retourneert de functievlag 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 kenmerkvlaggen

De bibliotheek voor functiebeheer ondersteunt Azure App Configuration, samen met application.yml of application.properties 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_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

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 heeft feature-u één functiefilter genaamd Random, waarvoor geen configuratie is vereist, dus alleen de eigenschap 'naam' is vereist.
• feature-v hiermee geeft u een functiefilter met de naam TimeWindowFilter. Er kunnen parameters worden doorgegeven aan dit functiefilter die voor configuratie worden gebruikt. In dit voorbeeld geeft een TimeWindowFilter, de begin- en eindtijd door waarin de functie actief is.
• feature-w wordt gebruikt voor de AlwaysOnFilter, die altijd evalueert tot true. Het evaluate veld wordt gebruikt om de evaluatie van de functiefilters te stoppen en resulteert in het functiefilter dat altijd wordt geretourneerd false.

Functievlaggen 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-web, samen met het bieden van FeatureManager, bevat FeatureManagerSnapshot, die de status van eerder geëvalueerde functievlaggen in de @RequestScope cache opslaat om te garanderen dat alle aanvragen dezelfde waarde retourneren. Daarnaast biedt de webbibliotheek @FeatureGate, die webaanvragen kan blokkeren of omleiden naar verschillende eindpunten.

Controle van functionaliteitsvlag

FeatureManager is een @Bean dat kan worden @Autowired 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
}

Zonder configuratie van functiebeheer of wanneer 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 false terug te laten geven door fail-fast naar false te configureren. In de volgende tabel wordt fail-fast beschreven.

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, wordt DisabledFeaturesHandler 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 automatisch toegevoegd.

Altijd AanFilter

Dit filter retourneert altijd true. Zie de sectie functievlagdeclaratie voor een gebruiksvoorbeeld.

Percentage Filter

Telkens wanneer deze wordt gecontroleerd, kan de evaluatie PercentageFilter een ander resultaat retourneren. U kunt deze inconsistentie omzeilen met behulp van de FeatureManagementSnapshot, die het resultaat van de functievlag per aanvraag in de cache opgeslagen.

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

Tijdvensterfilter

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

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"

Dit filter ondersteunt ook terugkerende tijdvensterfilters. Het ondersteunt zowel dagelijkse als wekelijkse terugkeerpatronen, samen met een verlooptijd.

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

Dit terugkeerpatroon vindt elke week plaats op maandag en woensdag van 00:00:00 GMT tot 12:00:00 GMT en verloopt niet.

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"

Dit terugkeerpatroon vindt elke dag plaats van 00:00:00 GMT tot 12:00:00 GMT tot de einddatum.

Doelgroepfilter

Dit filter biedt de mogelijkheid om een functie in te schakelen voor een doelgroep. Zie 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 uitrol.

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

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 evaluatetrue retourneert, betekent dit dat de functie moet worden ingeschakeld. Als het false retourneert, worden de functiefilters nog steeds geëvalueerd totdat een true wordt geretourneerd. Als de uitkomst van alle filters false is, dan 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 de eigenschap parameters, en dit is een Map<String, Object>.

Doelgerichtheid

Targeting is een strategie voor functiebeheer waarmee ontwikkelaars nieuwe functies progressief kunnen invoeren bij hun gebruikers. 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 om mee te doen en wordt toegevoegd.
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 tot 100 procent verhoogd 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 in een toepassing wilt gaan gebruiken, moet u deze toevoegen zoals elk ander functiefilter. TargetingFilter is afhankelijk van een andere @Bean die aan de toepassing TargetingContextAccessormoet worden toegevoegd. Met de TargetingContextAccessor kunt u de huidige TargetingContext definiëren, die vervolgens wordt gebruikt voor het bepalen van de huidige gebruikers-id en groepen, zoals in het volgende voorbeeld wordt getoond:

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

}

Evaluatieopties richten

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

    @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 verversen wilt inschakelen, moet u monitoring inschakelen samen met monitoringtriggers. Een bewakingstrigger is een sleutel met een optioneel label dat door het systeem 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.

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 wijzigt, resulteert dat in het volgende logboekbericht:

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

Nadat de toepassing het logboek heeft gegenereerd, worden alle @Beans vernieuwd binnen de vernieuwingsscope.

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 op wijzigingen wanneer er een vernieuwingspoging wordt uitgevoerd. Elke wijziging in de sleutel zorgt ervoor dat een verversing 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 mhd, 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-config gebruiken, zoals consoletoepassingen, kunt u handmatig een vernieuwing activeren door de AppConfigurationRefresh-methode van refreshConfiguration aan te roepen. 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 Configuration-archief.

Push-gebaseerde vernieuwing (niet aanbevolen)

U kunt de spring-cloud-azure-appconfiguration-config-web bibliotheek instellen voor het ontvangen van pushmeldingen van uw Azure App Configuration-archief 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 nog steeds de refresh en refresh-bus gebruiken, maar u kunt ze niet rechtstreeks verbinden met Azure Event Grid via een webhook, omdat ze een reactie tijdens de installatie vereisen.

De eigenschap appconfiguration-refresh zorgt ervoor dat het vernieuwingsinterval verloopt, zodat niet wordt gewacht op het resterende vernieuwingsinterval 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 elke instantie van uw toepassing niet op hetzelfde moment probeert te verversen.

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

Naast het beschikbaar maken van de vernieuwingseindpunten, vereist de bibliotheek een queryparameter voor beveiliging. Er bestaat standaard geen tokennaam of -waarde, maar u moet er een instellen om de eindpunten te 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]

Webhooks instellen

Als u een webhook wilt instellen, opent u uw Azure App Configuratie en selecteert u Gebeurtenissen vanuit het navigatiemenu. Vervolgens Gebeurtenisabonnement selecteren. Stel de naam van uw gebeurtenis in en selecteer het eindpunttype dat webhook moet zijn. Het selecteren van Web Hook zorgt ervoor dat er een Endpoint verschijnt als optie. 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 Selectie verzendt een configuratiemelding naar de opgegeven URI en verwacht een antwoord. Als er geen antwoord wordt geretourneerd, mislukt de installatie. De azure-spring-cloud-appconfiguration-web bibliotheekinstelling voor eindpunten retourneert de juiste respons als de Azure App Configuration store is geconfigureerd voor de toepassing. Deze bevestiging kan op andere manieren worden verzonden. Zie Levering van webhook-gebeurtenissen voor meer informatie over webhooklevering.

Wij raden sterk aan filters in te stellen, omdat anders een verversing wordt geactiveerd na het maken en wijzigen van sleutels.

Geforceerd vernieuwen van de client

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

Vernieuwen met spring.cloud.azure.appconfiguration.refresh-interval controleert geen geconfigureerde waaksluitels. 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 privé-sleutelpaar van een certificaat als geheim opslaat, kan uw toepassing elk certificaat als een Key Vault-verwijzing in App Configuration ophalen. 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 bijwerken

Als functievlagmen en bewaking beide zijn ingeschakeld, wordt het vernieuwingsinterval voor functievlagmen standaard ingesteld op 30 seconden. Wanneer het vernieuwingsinterval afloopt, controleert het systeem alle functievlagmen in het opgegeven archief op wijzigingen. Elke wijziging in de sleutel zorgt ervoor dat een verversing 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 mhd, 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

Gezondheidsindicator

De clientbibliotheek wordt geleverd met een gezondheidsindicator waarmee wordt gecontroleerd of de verbinding met de Azure App Configuration store of stores gezond is. Als deze optie voor elke winkel is ingeschakeld, krijgt het een van de volgende statuswaarden:

• UP: de laatste verbinding is geslaagd.
• DOWN - De laatste verbinding resulteerde in een foutcode die niet 200 was. Deze status kan worden veroorzaakt door problemen, variërend van inloggegevens die zijn verlopen tot een probleem met de service. 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 gezondheidsindicator inschakelen door management.health.azure-app-configuration.enabled=true in te stellen.

Cliëntspecificatie

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 hun respectieve builder ontvangt samen met de String waarde van de URI waarvoor de client wordt geconfigureerd, zoals weergegeven in de volgende interfacedefinities.

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

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

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

}