Supporto per la configurazione delle app

Questo articolo descrive la libreria di configurazione di Spring Cloud app Azure. Questa libreria carica configurazioni e flag di funzionalità dal servizio Configurazione app di Azure. La libreria genera PropertySource astrazioni in modo che corrispondano alle astrazioni già generate dall'ambiente Spring, ad esempio variabili di ambiente, configurazioni della riga di comando, file di configurazione locali e così via.

Spring è un framework di applicazioni open source, sviluppato da VMware, che fornisce un approccio modulare semplificato alla creazione di applicazioni Java. Spring Cloud Azure è un progetto open source che offre l'integrazione perfetta di Spring con i servizi di Azure.

Prerequisiti

• Una sottoscrizione di Azure: crearne una gratuitamente.
• Java Development Kit (JDK) versione 8 o successiva.
• Apache Maven
• Interfaccia della riga di comando di Azure

Configurare lo store di configurazione applicazioni

Usare il comando seguente per creare l'archivio di configurazione app Azure:

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

Questo comando crea un nuovo archivio di configurazione vuoto. È possibile caricare le configurazioni usando il comando di importazione seguente:

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

Verificare le configurazioni prima di caricarle. È possibile caricare file YAML modificando il formato in YAML. Il campo prefisso è importante perché è il prefisso predefinito caricato dalla libreria client.

Utilizzo della libreria

Per usare la funzionalità in un'applicazione, è possibile compilarla come applicazione Spring Boot. Il modo più pratico per aggiungere la dipendenza è utilizzare lo starter di Spring Boot com.azure.spring:spring-cloud-azure-starter-appconfiguration-config. Il seguente file esempio pom.xml utilizza Azure App Configuration:

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>{spring-boot-version}</version>
    <relativePath />
</parent>

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.azure.spring</groupId>
      <artifactId>spring-cloud-azure-dependencies</artifactId>
      <version>7.1.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>

L'esempio seguente illustra un'applicazione Spring Boot di base usando Configurazione app:

@SpringBootApplication
@RestController
public class Application {

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

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

Per questo esempio, il file application.properties contiene la riga seguente:

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

CONFIG_STORE_ENDPOINT è una variabile di ambiente con l'URL dell'endpoint per l'archivio di Configurazione delle App di Azure.

Per impostazione predefinita, se non sono impostate configurazioni, le configurazioni che iniziano con /application/ vengono caricate con un'etichetta predefinita di (No Label) a meno che non sia impostato un profilo Spring, nel qual caso l'etichetta predefinita è spring profile.

Viene creata un'origine di proprietà, chiamata /application/https://<name-of-your-store>.azconfig.io/, che contiene le proprietà di tale archivio. L'etichetta utilizzata nella richiesta viene aggiunta alla fine del nome. Se non è impostata alcuna etichetta, il carattere \0 è presente come spazio vuoto.

Caricamento della configurazione

La libreria supporta il caricamento di uno o più archivi di Configurazione App. Nella situazione in cui una chiave viene duplicata in più negozi, l'ultima è quella che prevale.

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

In questo esempio, se entrambi gli archivi hanno la stessa chiave di configurazione, la configurazione nel secondo archivio ha la priorità più alta.

Selezione delle configurazioni

La libreria carica le configurazioni usando la chiave e l'etichetta o l'istantanea. Quando non viene usato alcun metodo di selezione, la libreria carica tutte le chiavi con il prefisso /application/ e l'etichetta \0, che viene visualizzata come (No Label) nel portale di Azure.

Il filtro della chiave predefinito è /application/*. Il filtro di etichetta predefinito è \0, che viene visualizzato come (No Label) nel portale di Azure. Se viene impostato un profilo Spring e non viene fornita alcuna etichetta, l'etichetta predefinita è Spring Profile, ovvero ${spring.profiles.active}.

È anche possibile caricare le configurazioni da uno snapshot specifico. Uno snapshot è una visualizzazione statica della configurazione in un determinato momento. Quando si carica da uno snapshot, si caricano le configurazioni così come erano al momento della creazione dello snapshot e non vengono aggiornate fino a quando non si crea un nuovo snapshot e lo si carica da esso. Lo snapshot deve essere del tipo di Keycomposizione ed è possibile specificare lo snapshot da cui caricare usando la snapshot proprietà :

You can configure which configurations are loaded by selecting different key and label filters:

```properties
spring.cloud.azure.appconfiguration.stores[0].selects[0].key-filter=[my-key]
spring.cloud.azure.appconfiguration.stores[0].selects[0].label-filter=[my-label]
spring.cloud.azure.appconfiguration.stores[0].selects[1].snapshot=[snapshot-name]

La key-filter proprietà supporta i filtri seguenti:

La label-filter proprietà supporta i filtri seguenti:

Se si usa YAML con filtri di etichetta e si vogliono caricare configurazioni senza etichetta e altre configurazioni con altre etichette, è necessario includere un oggetto vuoto ,. Ad esempio, ,dev corrisponde \0 a e dev. In questo caso, virgolettare il filtro etichetta con virgolette singole. Questo valore consente di caricare prima la configurazione senza etichetta, seguita da configurazioni con etichette specifiche, nello stesso filtro:

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

Profili Spring

Per impostazione predefinita, spring.profiles.active è impostato come predefinito label-filter per tutte le configurazioni selezionate. È possibile eseguire l'override di questa funzionalità usando label-filter. È possibile usare i profili Spring in label-filter usando ${spring.profiles.active}, come illustrato nell'esempio seguente:

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

Nella prima label-filter, la libreria carica inizialmente tutte le configurazioni con l'etichetta \0, seguite poi da tutte le configurazioni che corrispondono ai profili Spring. I profili Spring hanno la priorità sulle \0 configurazioni, perché sono alla fine.

Nella seconda label-filter, la stringa _local viene aggiunta alla fine dei profili Spring, anche se solo all'ultimo dei profili Spring se ce ne sono più di uno.

Negozi disabilitati

Usando la configurazione spring.cloud.azure.appconfiguration.enabled, è possibile disabilitare il caricamento per tutti gli archivi di configurazione. Con la spring.cloud.azure.appconfiguration.stores[0].enabled configurazione è possibile disabilitare un singolo negozio.

Autenticazione

La libreria supporta tutte le forme di identità supportate dalla libreria di identità di Azure. È possibile eseguire l'autenticazione tramite la configurazione per le stringa di connessione e l'identità gestita.

Stringa di connessione (non consigliata)

L'autenticazione tramite stringa di connessione è la forma più semplice da configurare, anche se non è consigliata. È possibile accedere alle stringa di connessione di un archivio usando il comando seguente:

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

È quindi possibile impostare la spring.cloud.azure.appconfiguration.stores[0].connection-string proprietà sul stringa di connessione. Quando si usa questo approccio, è consigliabile impostare la stringa di connessione nel file di configurazione locale su un valore segnaposto mappato a una variabile di ambiente. Questo approccio consente di evitare di aggiungere la stringa di connessione al controllo del codice sorgente.

Configurazione di Spring Cloud Azure

È possibile usare la configurazione di Spring Cloud Azure per configurare la libreria. Per configurare la libreria, è possibile usare le proprietà seguenti:

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

Quando viene impostato solo l'endpoint, la libreria client usa DefaultAzureCredential per l'autenticazione.

È necessario assegnare l'identità usata per leggere le configurazioni. È possibile creare questa assegnazione usando il comando seguente:

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>

Replica geografica

La libreria supporta la funzionalità di replica geografica di Configurazione App di Azure. Questa funzionalità consente di replicare i dati in altre posizioni. Questa funzionalità è utile per la disponibilità elevata e il ripristino di emergenza.

Ogni replica creata ha un endpoint dedicato. Se l'applicazione si trova in più geolocalizzazioni, è possibile aggiornare ogni istanza di distribuzione della tua applicazione in un luogo per connettersi alla replica più vicina a tale posizione, riducendo al minimo la latenza di rete tra la tua applicazione e App Configuration. Poiché ogni replica ha una quota di richiesta separata, questa configurazione consente anche la scalabilità dell'applicazione mentre aumenta fino a un servizio distribuito in più aree.

Per impostazione predefinita, la libreria individua automaticamente tutte le repliche esistenti per un archivio di configurazione. Quando viene effettuata una richiesta all'archivio fornito e ha esito negativo, la libreria ritenta automaticamente la richiesta rispetto alle repliche disponibili.

Il failover può verificarsi se la libreria osserva una delle condizioni seguenti:

• Riceve risposte con codice di stato del servizio non disponibile (HTTP 500 o versione successiva) da un endpoint.
• Si verificano problemi di connettività di rete.
• Le richieste vengono limitate (codice di stato HTTP 429).

Dopo che il negozio fornito torna online, la libreria ritenta automaticamente la richiesta rispetto all'archivio fornito.

Se si vuole controllare il comportamento di failover, è possibile fornire manualmente un elenco di archivi da usare per il 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]

o

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]

Se tutti gli endpoint di replica forniti hanno esito negativo, la libreria tenta di connettersi alle repliche individuate automaticamente dell'archivio primario.

È possibile disabilitare la replica con l'impostazione spring.cloud.azure.appconfiguration.stores[0].replica-discovery-enabled=false.

Creazione di un archivio di configurazione con replica geografica

Per creare una replica dell'archivio di configurazione, è possibile usare l'interfaccia della riga di comando di Azure o il portale di Azure. L'esempio seguente usa l'Azure CLI per creare una replica nell'area East US 2:

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

Valori chiave

Azure App Configuration supporta più tipi di coppie chiave-valore, alcune delle quali dispongono di funzionalità speciali integrate. Azure App Configuration include il supporto predefinito per il tipo di contenuto JSON, i segnaposto Spring e i riferimenti a Key Vault.

Rimozione delle chiavi

Per impostazione predefinita, durante il caricamento delle chiavi dalla Configurazione app di Azure, la libreria taglia il prefisso definito dalla chiave spring.cloud.azure.appconfiguration.stores[0].selects[0].key-filter. Ad esempio, se si dispone di una chiave denominata /application/config.message e di un filtro di chiave di /application/*, la libreria taglia il prefisso /application/ e carica la chiave come config.message. Questo taglio del codice rende più semplice fare riferimento alle chiavi nel codice.

Questo comportamento può essere sottoposto a override impostando spring.cloud.azure.appconfiguration.stores[0].trim-key-prefix[0] su un valore diverso. L'impostazione di questa proprietà su una stringa vuota disabilita il comportamento di taglio e la chiave viene caricata con il nome completo.

Segnaposto

La libreria supporta le configurazioni con segnaposto ambiente in stile ${}. Quando si fa riferimento a una chiave di configurazione di Azure App con un segnaposto, rimuovere i prefissi dal riferimento. Ad esempio, /application/config.message viene fatto riferimento come ${config.message}.

JSON (JavaScript Object Notation)

È possibile creare valori chiave JSON in Configurazione app. Quando si caricano valori chiave da Configurazione app di Azure, il provider di configurazione converte automaticamente le impostazioni di configurazione in oggetti complessi all'interno di un oggetto @ConfigurationProperties. Si consideri ad esempio la chiave /application/config.colors JSON con il valore seguente:

{
    "key": "font",
    "label": null,
    "value": "{\r\n\t\"size\": 12,\r\n\t\"color\": \"red\"\r\n}",
    "content_type": "application/json"
}

Questo contenuto JSON comporta il caricamento del valore chiave come { size: 12, color: "red" }.

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

    private Font font;

}

Riferimenti a Key Vault

Azure App Configuration e le relative librerie supportano il fare riferimento ai segreti archiviati in Key Vault. Nella Configurazione dell'app, è possibile creare chiavi con valori che si mappano a segreti archiviati in un Key Vault. I segreti rimangono protetti in Key Vault, ma è possibile accedervi nello stesso modo di qualsiasi altra configurazione durante il caricamento dell'app.

L'applicazione usa il provider client per recuperare i riferimenti a Key Vault, esattamente come per qualsiasi altra chiave archiviata in Configurazione app. Poiché il client riconosce le chiavi come riferimenti a Key Vault, queste hanno un tipo di contenuto univoco e il client si connette al Key Vault per recuperare i loro valori per te.

Creazione di riferimenti a Key Vault

È possibile creare un riferimento a Key Vault nel portale di Azure passando a Esplora configurazioni>Crea>riferimento a Key Vault. È quindi possibile selezionare un segreto a cui fare riferimento da uno qualsiasi degli insiemi di credenziali delle chiavi a cui si ha accesso. È anche possibile creare riferimenti arbitrari a Key Vault dalla scheda Input . Nel portale di Azure immettere un URI valido.

È anche possibile creare un riferimento a Key Vault tramite l'interfaccia della riga di comando di Azure usando il comando seguente:

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

È possibile creare qualsiasi identificatore segreto tramite l'interfaccia della riga di comando di Azure. Gli identificatori dei segreti richiedono solo il formato {vault}/{collection}/{name}/{version?}, in cui la sezione "versione" è facoltativa.

Uso dei riferimenti a Key Vault

È possibile usare la configurazione di Spring Cloud Azure per configurare la libreria. È possibile usare le stesse credenziali usate per connettersi a Configurazione app per connettersi ad Azure Key Vault.

È anche possibile creare un SecretClientCustomizer allo stesso modo in cui si crea un ConfigurationClientCustomizer per offrire un metodo di autenticazione personalizzato.

Risolvere i segreti non di Key Vault

La Libreria di Configurazione App fornisce un metodo per eseguire l'override della risoluzione dei riferimenti al Key Vault. Ad esempio, è possibile usarlo per risolvere i segreti in locale in un ambiente di sviluppo. Questa risoluzione viene eseguita tramite il KeyVaultSecretProvider. Il KeyVaultSecretProvider, se specificato, viene chiamato su ogni riferimento al Key Vault. Se getSecret restituisce un valore non Null, viene usato come valore del segreto. In caso contrario, il riferimento a Key Vault viene risolto normalmente.

public class MySecretProvider implements KeyVaultSecretProvider {

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

}

Gestione delle funzionalità

La gestione delle funzionalità consente alle applicazioni Spring Boot di accedere dinamicamente al contenuto. La gestione delle funzionalità include diverse funzioni, ad esempio quelle seguenti:

• Flag di funzionalità che possono abilitare o disabilitare il contenuto
• Filtri delle funzionalità per la destinazione quando viene visualizzato il contenuto
• Filtri delle funzionalità personalizzati
• Meccanismi di abilitazione per l'attivazione dinamica degli endpoint

È possibile abilitare i flag di funzionalità tramite la configurazione seguente:

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

I flag di funzionalità abilitati vengono caricati nel sistema di configurazione Spring con il prefisso feature-management. È anche possibile registrare i flag di funzionalità nel file di configurazione locale. Per ulteriori informazioni, vedere la sezione Dichiarazione dei flag delle funzionalità.

Il modo più semplice per usare la gestione delle funzionalità consiste nell'usare le spring-cloud-azure-feature-management librerie e spring-cloud-azure-feature-management-web . La differenza tra le due librerie è che spring-cloud-azure-feature-management-web dipende dalle librerie spring-web e spring-webmvc per aggiungere altre funzionalità, ad esempio gestione delle funzionalità.

Per impostazione predefinita, vengono caricati tutti i flag di funzionalità con un'etichetta \0, come (No Label). È possibile configurare i flag di funzionalità caricati impostando un filtro etichetta, come illustrato nell'esempio seguente:

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

Telemetria dei segnali di funzionalità

Quando i dati di telemetria dei flag di funzionalità sono abilitati, il provider di Configurazione app di Azure inserisce proprietà aggiuntive nei dati di telemetria dei flag di funzionalità. Queste proprietà forniscono più contesto sul flag di funzionalità e sulla relativa valutazione:

• AllocationID: identificatore univoco che rappresenta lo stato dell'allocazione del flag di funzionalità.
• ETag: L'ETag corrente per il feature flag.
• FeatureFlagReference: riferimento al flag di funzionalità nel formato di <your_store_endpoint>kv/<feature_flag_key>. Quando è presente un'etichetta, il riferimento lo include come parametro di query: <your_store_endpoint>kv/<feature_flag_key>?label=<feature_flag_label>.

Nozioni di base sulla gestione delle funzionalità

Flag di funzionalità

I flag di funzionalità sono costituiti da più parti, tra cui un nome e un elenco di filtri di funzionalità usati per attivare la funzionalità. I flag di funzionalità possono avere uno stato booleano attivato o disattivato oppure possono avere un elenco di filtri di funzionalità. Gli indicatori di funzionalità valutano i filtri di funzionalità fino a quando non viene restituito true. Se nessun filtro di funzionalità restituisce true, allora il flag di funzionalità restituisce false.

Filtri di funzionalità

I filtri di funzionalità definiscono uno scenario per il momento in cui è necessario abilitare una funzionalità. I filtri delle funzionalità vengono valutati in modo sincrono.

La libreria di gestione delle funzionalità include quattro filtri predefiniti: AlwaysOnFilter, PercentageFilter, TimeWindowFilter e TargetingFilter.

È possibile creare filtri di funzionalità personalizzati. Ad esempio, è possibile usare un filtro di funzionalità per offrire un'esperienza personalizzata per i clienti che usano un browser Microsoft Edge. È possibile personalizzare le funzionalità in questo filtro di funzionalità, ad esempio, per visualizzare un'intestazione specifica per il gruppo di destinatari del browser Microsoft Edge.

Dichiarazione del feature flag

La libreria di gestione delle funzionalità supporta la Configurazione app di Azure insieme a application.yml o application.properties come origini per i flag di funzionalità. Ecco un esempio del formato usato per configurare i flag di funzionalità in un file application.yml :

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

  - id: feature-w
    evaluate: false
    conditions:
      client_filters:
      - name: AlwaysOnFilter

In questo esempio sono presenti i flag di funzionalità seguenti:

• feature-t è impostato su false. Questa impostazione restituisce sempre il valore del flag di funzionalità.
• feature-u viene usato con i filtri delle funzionalità. Questi filtri vengono definiti nella enabled-for proprietà . In questo caso, feature-u dispone di un filtro di funzionalità denominato Random, che non richiede alcuna configurazione, quindi è necessaria solo la proprietà name.
• feature-v specifica un filtro di funzionalità denominato TimeWindowFilter. Questo filtro di funzionalità può essere passato ai parametri da usare come configurazione. In questo esempio, un TimeWindowFilter oggetto fornisce i tempi di inizio e di fine durante i quali la funzionalità è attiva.
• feature-w viene utilizzato per il AlwaysOnFilter, che restituisce sempre true. Il campo evaluate viene usato per arrestare la valutazione dei filtri delle funzionalità e il filtro delle funzionalità restituisce sempre false.

Valutazione dei flag di funzionalità

La spring-cloud-azure-feature-management libreria fornisce FeatureManager per determinare se è abilitato un flag di funzionalità. FeatureManager fornisce un modo asincrono per controllare lo stato del flag.

spring-cloud-azure-feature-management-web, insieme a FeatureManager, contiene FeatureManagerSnapshot, che memorizza nella cache lo stato dei flag di funzionalità valutati in precedenza in @RequestScope per garantire che tutte le richieste restituiscono lo stesso valore. Inoltre, la libreria Web fornisce @FeatureGate, che può bloccare o reindirizzare le richieste Web a endpoint diversi.

Controllo dei flag di funzionalità

FeatureManager è un @Bean che può essere @Autowired o inserito in oggetti di tipo @Component. FeatureManager ha un metodo isEnabled che, quando viene passato il nome di un flag di funzionalità, restituisce il relativo stato.

@Autowired
FeatureManager featureManager;

...

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

Senza la configurazione della gestione delle funzionalità o quando il flag di funzionalità non esiste, isEnabled restituisce sempre false. Se un flag di funzionalità esistente è configurato con un filtro di funzionalità sconosciuto, viene generata un'eccezione FilterNotFoundException . È possibile modificare questo comportamento in modo da restituire false configurando fail-fast su false. La tabella seguente descrive fail-fast:

L'unica differenza tra FeatureManagerSnapshot e FeatureManager è la memorizzazione nella cache dei risultati in @RequestScope.

Interruttore delle funzionalità

Con la libreria Web di gestione delle funzionalità, è possibile richiedere che una determinata funzionalità sia abilitata per eseguire un endpoint. È possibile configurare questo requisito usando l'annotazione @FeatureGate , come illustrato nell'esempio seguente:

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

È possibile accedere all'endpoint featureT solo se "feature-t" è abilitato.

Gestione delle azioni disabilitata

Quando un endpoint viene bloccato perché la funzionalità specificata è disabilitata, DisabledFeaturesHandler viene richiamata. Per impostazione predefinita, viene restituito un http 404. È possibile eseguire l'override di questo comportamento implementando DisabledFeaturesHandler, come illustrato nell'esempio seguente:

@Component
public class MyDisabledFeaturesHandler implements DisabledFeaturesHandler {

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

}

Indirizzamento

Le funzionalità possono limitare determinate route che espongono le capacità dell'applicazione. Se una funzionalità è disabilitata, è possibile reindirizzare queste route a un altro endpoint, come illustrato nell'esempio seguente:

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

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

Filtri di funzionalità predefiniti

Esistono alcuni filtri di funzionalità disponibili con il spring-cloud-azure-feature-management pacchetto. Questi filtri di funzionalità vengono aggiunti automaticamente.

Filtro sempre attivo

Questo filtro restituisce sempre true. Per un esempio di utilizzo, vedere la sezione dichiarazione del flag di funzionalità.

Filtro percentuale

PercentageFilter può restituire un risultato diverso in ogni controllo. È possibile aggirare questa incoerenza usando FeatureManagementSnapshot, che memorizza nella cache il risultato del flag di funzionalità per ogni richiesta.

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

Filtro Finestra Temporale

Questo filtro offre la possibilità di abilitare una funzionalità in base a una finestra temporale. Se si specifica solo End, la funzionalità viene considerata attiva fino a quel momento. Se si specifica solo Start, la funzionalità viene considerata attiva in tutti i punti dopo tale momento. Se si specificano entrambi, la funzionalità viene considerata valida tra le due volte.

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"

Questo filtro supporta anche filtri di intervallo temporale ricorrenti. Supporta ricorrenze giornaliere e settimanali, insieme a una scadenza.

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

Questo modello di ricorrenza si verifica ogni settimana lunedì e mercoledì dalle 00:00:00 GMT alle 12:00:00 GMT e non scade.

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"

Questo modello di ricorrenza si verifica ogni altro giorno dalle 00:00:00 GMT alle 12:00:00 GMT fino alla data di fine.

Filtro di targeting

Questo filtro offre la possibilità di abilitare una funzionalità per un pubblico di destinazione. Per una spiegazione approfondita del targeting, vedere la sezione targeting. I parametri di filtro includono un oggetto audience che descrive utenti, gruppi e una percentuale predefinita della base utente che deve avere accesso alla funzionalità. Per ogni oggetto gruppo elencato nel gruppo di destinatari, è necessaria una percentuale che definisce la percentuale dei membri del gruppo che hanno accesso alla funzionalità. Un utente ha la funzionalità abilitata nei casi seguenti:

• L'utente viene specificato direttamente nella sezione degli utenti.
• L'utente è nella percentuale inclusa di una delle implementazioni del gruppo.
• L'utente rientra nella percentuale di implementazione predefinita.

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

Filtri di funzionalità personalizzati

La creazione di un filtro di funzionalità personalizzato consente di abilitare le funzionalità in base ai criteri definiti dall'utente. Per creare un filtro di funzionalità personalizzato, è necessario implementare l'interfaccia FeatureFilter . FeatureFilter ha un singolo metodo evaluate. Quando una funzionalità specifica che può essere abilitata con un filtro di funzionalità, viene chiamato il evaluate metodo . Se evaluate restituisce true, significa che la funzionalità deve essere abilitata. Se restituisce false, continua a valutare i filtri delle funzionalità fino a quando non ne restituisce trueuno. Se tutti i filtri restituiscono false, la funzionalità è disattivata.

I filtri di funzionalità sono definiti come Spring Beans, quindi sono definiti come @Component o definiti in un oggetto @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;
    }

}

Filtri delle funzionalità con parametri

Alcuni filtri di funzionalità richiedono parametri per determinare se una funzionalità deve essere attivata. Ad esempio, un filtro di funzionalità del browser potrebbe attivare una funzionalità per un determinato set di browser. Potrebbe essere necessario abilitare una funzionalità per i browser Microsoft Edge e Chrome, ma non per Firefox. Per configurare questa situazione, è possibile progettare un filtro di funzionalità per prevedere i parametri. Questi parametri verranno specificati nella configurazione della funzionalità e nel codice e sarebbero accessibili tramite il FeatureFilterEvaluationContext parametro di evaluate. FeatureFilterEvaluationContext ha una proprietà parameters, che è un oggetto Map<String, Object>.

Targetizzazione

Il targeting è una strategia di gestione delle funzionalità che consente agli sviluppatori di implementare progressivamente nuove funzionalità alla propria base di utenti. La strategia si basa sul concetto di destinazione di un set di utenti noto come gruppo di destinatari. Un gruppo di destinatari è costituito da utenti, gruppi e una percentuale designata dell'intera base utenti. I gruppi inclusi nel gruppo di destinatari possono essere suddivisi ulteriormente in percentuali dei membri totali.

I passaggi seguenti illustrano un esempio di implementazione progressiva per una nuova funzionalità "Beta":

1. Ai singoli utenti Jeff e Alicia viene concesso l'accesso alla versione Beta.
2. Un altro utente, Mark, chiede di aderire ed è incluso.
3. Il venti percento di un gruppo noto come utenti "Ring1" è incluso nella Beta.
4. Il numero di utenti "Ring1" inclusi nella Beta è salito fino al 100%.
5. Il 5% della base di utenti è incluso nella versione Beta.
6. La percentuale di implementazione viene incrementata fino al 100% e la funzionalità viene implementata completamente.

Questa strategia per l'implementazione di una funzionalità è integrata nella libreria tramite il filtro delle funzionalità incluso TargetingFilter .

Destinazione in un'applicazione

Nel progetto di esempio è disponibile un'applicazione Web di esempio che usa il filtro di funzionalità di destinazione.

Per iniziare a usare il TargetingFilter in un'applicazione, è necessario aggiungerlo come si farebbe con qualsiasi altro filtro di funzionalità. TargetingFilter si basa su un altro @Bean oggetto da aggiungere all'applicazione TargetingContextAccessor. TargetingContextAccessor consente di definire l'oggetto corrente TargetingContext da usare per definire l'ID utente e i gruppi correnti, come illustrato nell'esempio seguente:

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

}

Opzioni per la valutazione degli obiettivi

Le opzioni sono disponibili per personalizzare la modalità di esecuzione della valutazione del targeting in un determinato TargetingFilter oggetto. È possibile impostare un parametro facoltativo, TargetingEvaluationOptions, durante la TargetingFilter creazione.

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

Aggiornamento della configurazione

L'abilitazione dell'aggiornamento della configurazione consente di estrarre i valori più recenti dall'archivio delle configurazioni dell'app o dagli archivi senza dover riavviare l'applicazione.

Per abilitare l'aggiornamento, è necessario abilitare il monitoraggio insieme ai trigger di monitoraggio. Un trigger di monitoraggio è una chiave con un'etichetta facoltativa monitorata dal sistema per verificare le modifiche apportate ai valori per attivare gli aggiornamenti. Il valore del trigger di monitoraggio può essere qualsiasi valore, purché venga modificato quando è necessario un aggiornamento.

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

Per attivare un aggiornamento della configurazione, modificare il valore di una chiave nell'archivio di configurazione. Quindi, aggiornare uno delle chiavi di monitoraggio con un nuovo valore. Questa modifica attiva la creazione di un log. Ad esempio, la modifica del valore di /application/config.message attiva il seguente messaggio di log:

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

Dopo aver generato il log, l'applicazione aggiorna tutti gli @Beanelementi nell'ambito di aggiornamento.

Aggiornamento basato su richiesta

Le librerie di Spring App Configuration supportano il controllo periodico delle modifiche ai trigger di monitoraggio in base a un intervallo di aggiornamento. Per impostazione predefinita, l'intervallo di aggiornamento è impostato su 30 secondi. Al termine dell'intervallo di aggiornamento, quando viene effettuato un tentativo di aggiornamento, tutti i trigger vengono archiviati nell'archivio specificato per verificare la presenza di modifiche. Qualsiasi modifica apportata alla chiave provoca un aggiornamento. Poiché le librerie si integrano con il sistema di aggiornamento Spring, qualsiasi aggiornamento ricarica tutte le configurazioni da tutti gli archivi. È possibile impostare l'intervallo di aggiornamento su qualsiasi intervallo superiore a 1 secondo. Le unità supportate per l'intervallo di aggiornamento sono srispettivamente , m, he d per secondi, minuti, ore e giorni. L'esempio seguente imposta l'intervallo di aggiornamento su 5 minuti:

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

Automatizzato

Quando si usa la spring-cloud-azure-appconfiguration-config-web libreria, l'applicazione verifica automaticamente la presenza di un aggiornamento ogni volta che si verifica una richiesta servlet, in particolare ServletRequestHandledEvent. Il modo più comune in cui questo evento viene inviato è da richieste agli endpoint in un oggetto @RestController.

Manuale

Nelle applicazioni che usano solo spring-cloud-azure-appconfiguration-config, ad esempio le applicazioni console, è possibile attivare manualmente un aggiornamento chiamando AppConfigurationRefreshil metodo di refreshConfiguration . AppConfigurationRefresh è un oggetto @Bean che è possibile inserire in qualsiasi @Componentoggetto .

Inoltre, poiché la libreria usa il sistema di configurazione di Spring, l'attivazione di un aggiornamento causa un aggiornamento di tutte le configurazioni, non solo un ricaricamento di quelli dall'archivio di Configurazione app di Azure.

Aggiornamento basato su push (non consigliato)

È possibile configurare la spring-cloud-azure-appconfiguration-config-web libreria per ricevere notifiche push dall'archivio di Configurazione app di Azure per aggiornare i valori di configurazione. È possibile configurare questa configurazione tramite un web hook di Griglia di eventi di Azure, che è possibile configurare per inviare notifiche di modifiche alle chiavi specificate. Aggiungendo la libreria Spring Actuator come dipendenza, è possibile esporre gli endpoint di aggiornamento di App Configuration. Esistono due endpoint diversi: appconfiguration-refresh e appconfiguration-refresh-bus. Questi endpoint funzionano in modo analogo alle controparti refresh e refresh-bus, in cui gli endpoint di configurazione dell'app scadono l'intervallo di aggiornamento anziché forzare un aggiornamento al momento della ricezione. È comunque possibile usare e refreshrefresh-bus, ma non è possibile connetterli direttamente a Griglia di eventi di Azure con un Web Hook perché richiedono una risposta nella configurazione.

La appconfiguration-refresh proprietà annulla l'intervallo di aggiornamento, quindi non si attende l'intervallo di aggiornamento rimanente prima del successivo controllo di aggiornamento. La appconfiguration-refresh-bus proprietà invia una notifica a un servizio di messaggistica connesso, ad esempio il bus di servizio di Azure, per inviare una notifica a tutte le istanze di un'applicazione da aggiornare. In entrambi i casi, non scade completamente all'intervallo di aggiornamento, ma presenta una lieve variazione di temporizzazione. Questa variazione temporale garantisce che ogni istanza dell'applicazione non tenti di aggiornarsi contemporaneamente.

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

Oltre a esporre gli endpoint di aggiornamento, la libreria richiede un parametro di query per la sicurezza. Per impostazione predefinita, non esiste alcun nome o valore del token, ma è necessario impostarne uno per l'uso degli endpoint, come illustrato nell'esempio seguente:

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]

Configurazione di web hook

Per configurare un webhook, aprire l'archivio di Configurazione app di Azure e aprire Eventi dal menu di navigazione. Selezionare quindi Sottoscrizione di eventi. Impostare il nome dell'evento e selezionare il tipo di endpoint come Web Hook. Se si seleziona Web Hook, viene visualizzata un'opzione Endpoint . Selezionare un endpoint. L'endpoint dovrebbe essere simile all'esempio seguente: https://www.myaplication.com/actuator/appconfiguration-refresh?myTokenName=mySecret.

Conferma selezione invia una notifica di configurazione all'URI specificato e si aspetta una risposta. Se non viene restituita alcuna risposta, l'installazione non riesce. La azure-spring-cloud-appconfiguration-web configurazione della libreria per gli endpoint restituisce la risposta corretta se l'archivio di configurazione delle app di Azure è configurato per l'applicazione. Questa conferma può essere inviata in altri modi. Per ulteriori informazioni sulla consegna dei webhook, vedere Consegna degli eventi webhook.

È consigliabile configurare i filtri perché in caso contrario, viene attivato un aggiornamento dopo ogni creazione e modifica della chiave.

Aggiornamento client forzato

È possibile configurare la libreria per forzare un aggiornamento di tutte le configurazioni a un intervallo di aggiornamento. Nella tabella seguente viene descritta la refresh-interval proprietà :

L'aggiornamento con spring.cloud.azure.appconfiguration.refresh-interval non controlla le chiavi di controllo configurate. Questa proprietà viene usata per assicurarsi che i segreti dell'Archivio chiavi siano aggiornati perché Azure App Configuration non è in grado di indicare quando vengono aggiornati.

Poiché Azure Key Vault archivia la coppia di chiavi pubblica e privata di un certificato come segreto, l'applicazione può recuperare qualsiasi certificato come riferimento a Key Vault in Configurazione app. Poiché i certificati devono essere ruotati periodicamente, le applicazioni client devono eseguire l'aggiornamento altrettanto frequentemente, operazione che può essere eseguita usando l'intervallo di aggiornamento client.

Aggiornamento dei flag di funzionalità

Se i flag di funzionalità e il monitoraggio sono entrambi abilitati, per impostazione predefinita l'intervallo di aggiornamento per i flag di funzionalità è impostato su 30 secondi. Al termine dell'intervallo di aggiornamento, il sistema controlla tutti i flag di funzionalità nell'archivio specificato per verificare la presenza di modifiche. Qualsiasi modifica apportata alla chiave provoca un aggiornamento. Poiché le librerie si integrano con il sistema di aggiornamento Spring, qualsiasi aggiornamento ricarica tutte le configurazioni da tutti gli archivi. È possibile impostare l'intervallo di aggiornamento su qualsiasi intervallo superiore a 1 secondo. Le unità supportate per l'intervallo di aggiornamento sono srispettivamente , m, he d per secondi, minuti, ore e giorni. L'esempio seguente imposta l'intervallo di aggiornamento su 5 minuti:

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

Indicatore di salute

La libreria client include un indicatore di integrità che controlla se la connessione all’archivio o agli archivi di configurazione delle app Azure è funzionante. Se abilitato per ogni negozio, fornisce uno dei valori di stato seguenti:

• UP: l'ultima connessione è riuscita.
• DOWN- L'ultima connessione ha generato un codice di errore non 200. Questo stato potrebbe essere dovuto a problemi che vanno dalla scadenza delle credenziali a un problema del servizio. La libreria client riprova automaticamente a connettersi al negozio al successivo intervallo di aggiornamento.
• NOT LOADED: l'archivio di configurazione è elencato nel file di configurazione locale, ma l'archivio di configurazione non è stato caricato dal file all'avvio. L'archivio di configurazione è disabilitato nel file di configurazione oppure la configurazione o le configurazioni non sono state caricate all'avvio mentre la fail-fast configurazione per l'archivio è stata impostata su false.

È possibile abilitare l'indicatore di integrità impostando management.health.azure-app-configuration.enabled=true.

Personalizzazione del client

La libreria App Configuration utilizza l'Azure SDK per Java per connettersi ad App Configuration di Azure e ad Azure Key Vault. Sono fornite due interfacce, ConfigurationClientCustomizer e SecretClientCustomizer, per modificare i client. Ogni interfaccia ha un customize metodo che accetta i rispettivi generatori insieme al String valore dell'URI per cui viene configurato il client, come illustrato nelle definizioni di interfaccia seguenti:

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

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

Queste interfacce consentono la personalizzazione del client HTTP e delle relative configurazioni. L'esempio seguente sostituisce l'impostazione predefinita HttpClient con un'altra che usa un proxy per tutto il traffico indirizzato a Configurazione app e 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();
    }

}