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 di configurazione app 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: creare un account gratuitamente.
• Java Development Kit (JDK) versione 8 o successiva.
• Apache Maven
• Interfaccia della riga di comando di Azure

Configurare l'archivio Configurazione app

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 consiste nell'utilità di avvio com.azure.spring:spring-cloud-azure-starter-appconfiguration-configSpring Boot. L'esempio seguente pom.xml file usa app Azure Configuration:

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

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

Nota

Se si usa Spring Boot 2.x, assicurarsi di impostare la spring-cloud-azure-dependencies versione su 4.19.0. Per altre informazioni sulla versione usata per questa distinta base, vedere La versione di Spring Cloud azure da usare.

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 bootstrap.properties contiene la riga seguente:

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

CONFIG_STORE_CONNECTION_STRINGè una variabile di ambiente con il stringa di connessione nell'archivio di configurazione di app Azure. È possibile accedere al stringa di connessione usando il comando seguente:

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

Nota

Microsoft consiglia di usare il flusso di autenticazione più sicuro disponibile. Il flusso di autenticazione descritto in questa procedura, ad esempio per database, cache, messaggistica o servizi di intelligenza artificiale, richiede un livello di attendibilità molto elevato nell'applicazione e comporta rischi non presenti in altri flussi. Usare questo flusso solo quando le opzioni più sicure, ad esempio le identità gestite per le connessioni senza password o senza chiave, non sono valide. Per le operazioni del computer locale, preferire le identità utente per le connessioni senza password o senza chiave.

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. Poiché l'archivio è vuoto, non vengono caricate configurazioni, ma l'origine della proprietà di configurazione app Azure viene ancora generata.

Viene creata un'origine di proprietà denominata /application/https://<name-of-your-store>.azconfig.io/ contenente 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 Configurazione app. Nella situazione in cui una chiave viene duplicata in più archivi, il caricamento di tutti gli archivi comporta il caricamento della configurazione degli archivi con priorità più alta. L'ultimo vince. Questo processo è illustrato nell'esempio seguente:

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

Nell'esempio, se i primi e i secondi archivi hanno la stessa configurazione, la configurazione nel secondo archivio ha la priorità più alta e l'ultima vince.

Nota

È possibile usare app Azure impostazioni di configurazione come qualsiasi altra configurazione spring. Per altre informazioni, vedere Funzionalità di base nella documentazione di Spring Boot o Avvio rapido: Creare un'app Java Spring con app Azure Configurazione.

Selezione delle configurazioni

Le configurazioni vengono caricate dalla chiave e dall'etichetta. Per impostazione predefinita, vengono caricate le configurazioni che iniziano con la chiave /application/ . L'etichetta predefinita è ${spring.profiles.active}. Se ${spring.profiles.active} non è impostato, le configurazioni con l'etichetta null vengono caricate. L'etichetta null viene visualizzata come (No Label) nel portale di Azure.

È possibile configurare le configurazioni caricate selezionando filtri di chiave e etichetta diversi, come illustrato nell'esempio seguente:

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

La key-filter proprietà supporta i filtri seguenti:

Filtro chiavi	Effetto
*	Trova la corrispondenza con qualsiasi chiave.
abc	Trova la corrispondenza con una chiave denominata abc.
abc*	Trova la corrispondenza con i nomi delle chiavi che iniziano con abc.
abc,xyz	Trova la corrispondenza con i nomi abc delle chiavi o xyz. Limitato a cinque valori delimitati da virgole.

La label-filter proprietà supporta i filtri seguenti:

Etichetta	Descrizione
*	Trova la corrispondenza con qualsiasi etichetta, incluso \0.
\0	Trova le null etichette visualizzate come (No Label) nel portale di Azure.
1.0.0	Corrisponde esattamente all'etichetta 1.0.0 .
1.0.*	Corrisponde alle etichette che iniziano con 1.0.*.
,1.0.0	Trova le etichette null e 1.0.0. Limitato a cinque valori delimitati da virgole.

Se si usa YAML con filtri etichetta ed è necessario iniziare con null, il filtro etichetta deve essere racchiuso tra virgolette singole, come illustrato nell'esempio seguente:

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

Nota

Non è possibile combinare * con , nei filtri. In tal caso, è necessario usare un valore di selezione aggiuntivo.

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, tutte le configurazioni con l'etichetta null vengono caricate, seguite da tutte le configurazioni corrispondenti ai profili Spring. I profili Spring hanno la priorità sulle null configurazioni, perché sono alla fine.

Nella seconda label-filterstringa _local viene aggiunta alla fine dei profili Spring, anche se solo all'ultimo profilo Spring.

Archivi 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 archivio.

Oltre a disabilitare gli archivi, è possibile configurare gli archivi in modo che vengano disabilitati se non vengono caricati. Per questa configurazione, usare spring.cloud.azure.appconfiguration.stores[0].fail-fast. Quando fail-fast è disabilitato impostandolo su false, l'archivio RuntimeException applicazioni viene disabilitato senza alcuna configurazione da caricare. Se un archivio di configurazione è disabilitato all'avvio, non viene verificata la presenza di modifiche al momento dell'aggiornamento. Inoltre, non viene eseguito alcun tentativo di caricare i valori da esso se le configurazioni vengono aggiornate.

Se si verifica un errore RuntimeException durante un controllo di aggiornamento o durante il tentativo di ricaricare le configurazioni, il tentativo di aggiornamento termina e viene ritentato dopo il refresh-interval superamento di .

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.

Nota

Microsoft consiglia di usare il flusso di autenticazione più sicuro disponibile. Il flusso di autenticazione descritto in questa procedura, ad esempio per database, cache, messaggistica o servizi di intelligenza artificiale, richiede un livello di attendibilità molto elevato nell'applicazione e comporta rischi non presenti in altri flussi. Usare questo flusso solo quando le opzioni più sicure, ad esempio le identità gestite per le connessioni senza password o senza chiave, non sono valide. Per le operazioni del computer locale, preferire le identità utente per le connessioni senza password o senza chiave.

Stringa di connessione

L'autenticazione tramite stringa di connessione è la forma più semplice da configurare. È 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. È consigliabile impostare il 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 il 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. DefaultAzureCredential Usa i metodi seguenti per l'autenticazione:

• Credenziali dell'ambiente
• Credenziali dell'identità gestita
• Credenziali dell'interfaccia della riga di comando per sviluppatori di Azure
• Credenziali intelliJ
• Credenziali dell'interfaccia della riga di comando di Azure
• Credenziali di Azure PowerShell

È necessario assegnare un'identità, ad esempio un'identità assegnata dal sistema, 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>

Nota

È possibile definire un solo metodo di autenticazione per endpoint: stringa di connessione, identità assegnata dall'utente o credenziali del token. Se è necessario combinare e trovare una corrispondenza, è possibile usare ConfigurationClientCustomizer per modificare gli archivi che usano un metodo diverso.

Nota

Microsoft consiglia di usare il flusso di autenticazione più sicuro disponibile. Il flusso di autenticazione descritto in questa procedura, ad esempio per database, cache, messaggistica o servizi di intelligenza artificiale, richiede un livello di attendibilità molto elevato nell'applicazione e comporta rischi non presenti in altri flussi. Usare questo flusso solo quando le opzioni più sicure, ad esempio le identità gestite per le connessioni senza password o senza chiave, non sono valide. Per le operazioni del computer locale, preferire le identità utente per le connessioni senza password o senza chiave.

Replica geografica

La libreria supporta la funzionalità di replica geografica di app Azure Configurazione. 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ù georilevazioni, è possibile aggiornare ogni distribuzione dell'applicazione in un percorso per connettersi alla replica più vicina a tale posizione, riducendo al minimo la latenza di rete tra l'applicazione e Configurazione app. 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.

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

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'interfaccia della riga di comando di Azure per creare una replica nell'area Stati Uniti orientali 2:

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

Uso della replica dell'archivio di configurazione

Dopo aver creato una replica, è possibile usarla nell'applicazione. Come l'archivio di origine, è possibile connettersi alla replica usando Microsoft Entra ID o un stringa di connessione.

Nota

Microsoft consiglia di usare il flusso di autenticazione più sicuro disponibile. Il flusso di autenticazione descritto in questa procedura, ad esempio per database, cache, messaggistica o servizi di intelligenza artificiale, richiede un livello di attendibilità molto elevato nell'applicazione e comporta rischi non presenti in altri flussi. Usare questo flusso solo quando le opzioni più sicure, ad esempio le identità gestite per le connessioni senza password o senza chiave, non sono valide. Per le operazioni del computer locale, preferire le identità utente per le connessioni senza password o senza chiave.

Microsoft Entra ID (scelta consigliata)

Per usare Microsoft Entra ID per connettersi alla replica, è necessario elencare le istanze dell'archivio endpoints di configurazione, come illustrato nell'esempio seguente:

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

È possibile elencare tutti gli endpoint presenti nelle repliche. La libreria tenta di connettersi agli endpoint nell'ordine in cui sono elencati. Se la libreria non è in grado di connettersi a una replica, prova quella successiva nell'elenco. Dopo il superamento di un periodo di tempo, la libreria tenta di riconnettersi agli endpoint preferiti.

stringa di connessione

Per usare un stringa di connessione per connettersi alla replica, è necessario elencare le istanze dell'archivio connectionStrings di configurazione, come illustrato nell'esempio seguente:

spring.cloud.azure.appconfiguration.stores[0].connectionStrings[0]=[your primary store connection string]
spring.cloud.azure.appconfiguration.stores[0].connectionStrings[1]=[your replica store connection string]

È possibile elencare il numero di stringa di connessione disponibili nelle repliche. La libreria tenta di connettersi ai stringa di connessione nell'ordine in cui sono elencati. Se la libreria non è in grado di connettersi a una replica, prova quella successiva nell'elenco. Al termine di un periodo di tempo, la libreria tenta di riconnettersi ai stringa di connessione preferiti.

Valori chiave

app Azure Configurazione supporta più tipi di valori chiave, alcuni dei quali dispongono di funzionalità speciali integrate. app Azure Configuration include il supporto predefinito per il tipo di contenuto JSON, i segnaposto Spring e i riferimenti a Key Vault.

Segnaposto

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

Nota

Il prefisso da rimuovere corrisponde al valore spring.cloud.azure.appconfiguration.stores[0].selects[0].key-filter.

JSON

Le configurazioni con un tipo di application/json contenuto vengono elaborate come oggetti JSON. Questa funzionalità consente di eseguire il mapping di una configurazione a un oggetto complesso all'interno di un oggetto @ConfigurationProperties. Si consideri ad esempio la chiave /application/config.colors JSON con il valore seguente:

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

Questa chiave esegue il mapping al codice seguente:

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

    private Map<String, Color> colors;

}

Riferimenti a Key Vault

app Azure Configurazione e le relative librerie supportano il riferimento ai segreti archiviati in Key Vault. In Configurazione app è possibile creare chiavi con valori mappati ai segreti archiviati in un insieme di credenziali delle chiavi. I segreti vengono archiviati in modo sicuro in Key Vault, ma possono essere accessibili allo stesso modo di qualsiasi altra configurazione dopo il caricamento.

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, ha un tipo di contenuto univoco e il client si connette all'insieme di credenziali delle chiavi per recuperare automaticamente i valori.

Nota

Key Vault consente solo di recuperare i segreti uno alla volta, quindi ogni riferimento di Key Vault archiviato in Configurazione app genera un pull su Key Vault.

Creazione di riferimenti a Key Vault

È possibile creare un riferimento all'insieme di credenziali delle chiavi nella portale di Azure passando a Esplora configurazioniCreare informazioni di riferimento>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. Nella 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 version è 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.

Risolvere i segreti non di Key Vault

La libreria Configurazione app fornisce un metodo per risolvere in locale i segreti a cui non è associato un insieme di credenziali delle chiavi. Questa risoluzione viene eseguita tramite .KeyVaultSecretProvider Viene KeyVaultSecretProvider chiamato quando non viene fornito un TokenCredential oggetto per un riferimento a Key Vault. Viene fornito l'URI del riferimento a Key Vault e il valore restituito diventa il valore del segreto.

Avviso

L'uso di un KeyVaultSecretProvider oggetto esegue l'override dell'uso automatico dell'identità gestita assegnata dal sistema. Per usare entrambi, è necessario usare KeyVaultCredentialProvider e restituire null per gli URI che devono essere risolti.

public class MySecretProvider implements KeyVaultSecretProvider {

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

}

Gestione 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
• Controlli delle funzionalità per l'abilitazione 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 altre informazioni, vedere la sezione Dichiarazione di flag di 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 assume una dipendenza dalle spring-web librerie e spring-webmvc per aggiungere altre funzionalità, ad esempio i controlli delle funzionalità.

È possibile abilitare i flag di funzionalità usando filtri chiave/etichetta. Per impostazione predefinita, viene assegnata un'etichetta null , 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

Nozioni di base sulla gestione delle funzionalità

Flag di funzionalità

I flag di funzionalità sono costituiti da due parti: un nome e un elenco di filtri di funzionalità usati per attivare la funzionalità. I flag di funzionalità possono avere uno stato booleano on/off oppure possono avere un elenco di filtri di funzionalità. I flag di funzionalità valutano i filtri delle funzionalità fino a quando non viene restituito true. Se non viene restituito truealcun filtro di funzionalità, 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 flag di funzionalità

La libreria di gestione delle funzionalità supporta app Azure Configurazione insieme a application.yml o bootstrap.yml come origini per i flag di funzionalità. Di seguito è riportato un esempio del formato usato per configurare i flag di funzionalità in un file application.yml :

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

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 TimeWindowFilteroggetto passa l'ora di inizio e di fine durante la quale la funzionalità è attiva.
• feature-w viene usato per , AlwaysOnFilterche restituisce truesempre . Il evaluate campo viene usato per arrestare la valutazione dei filtri delle funzionalità e il filtro delle funzionalità restituisce falsesempre .

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 oggetto @Bean che può essere @Autowired o inserito in @Component oggetti di tipo. 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
}

Nota

FeatureManger ha anche una versione asincrona di isEnabled denominata isEnabledAsync.

Se la gestione delle funzionalità non è stata configurata o il flag di funzionalità non esiste, isEnabled restituisce falsesempre . 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:

Nome	Descrizione	Richiesto	Valore predefinito
spring.cloud.azure.feature.management.fail-fast	Se si verifica un'eccezione, viene generata un'eccezione RuntimeException . Se questa proprietà è impostata su false, restituisce isEnabledfalse invece .	No	true

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

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

}

Routing

Alcune route possono esporre funzionalità dell'applicazione gestite dalle funzionalità. 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à non vengono aggiunti automaticamente, ma è possibile configurarli in un oggetto @Configuration.

AlwaysOnFilter

Questo filtro restituisce truesempre . Per un esempio di utilizzo, vedere la sezione relativa alla dichiarazione del flag di funzionalità.

PercentageFilter

Ogni volta che un utente effettua una richiesta, la valutazione di PercentageFilter può restituire un risultato diverso. È possibile aggirare questa incoerenza usando , FeatureManagementSnapshotche memorizza nella cache il risultato del flag di funzionalità per utente. Questa funzionalità garantisce che un utente abbia un'esperienza coerente, anche se deve inviare nuovamente la richiesta.

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

TimeWindowFilter

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 in tutti i punti dopo tale periodo. Se si specificano entrambi, la funzionalità viene considerata valida tra le due volte.

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

Questo filtro offre la possibilità di abilitare una funzionalità per un pubblico di destinazione. Per una spiegazione approfondita della destinazione, vedere la sezione relativa alla destinazione. 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: 
  target:
    enabled-for:
    - 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 può 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 HashMap<String, Object>.

Selezione della destinazione

La destinazione è una strategia di gestione delle funzionalità che consente agli sviluppatori di implementare progressivamente nuove funzionalità alla base degli 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 acconsentire esplicitamente 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 in TargetingFilter un'applicazione, è necessario aggiungerlo come @Bean 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 getContextAsync(TargetingContext context) {
        context.setUserId("Jeff");
        ArrayList<String> groups = new ArrayList<String>();
        groups.add("Ring0");
        context.setGroups(groups);
    }

}

Opzioni di valutazione di destinazione

Le opzioni sono disponibili per personalizzare la modalità di esecuzione della valutazione della destinazione in un determinato TargetingFilteroggetto . È 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 per le configurazioni consente di estrarre i valori più recenti dall'archivio Configurazione 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 controllata per verificare la presenza di modifiche al valore per attivare gli aggiornamenti. Il valore del trigger di monitoraggio può essere qualsiasi valore, purché venga modificato quando è necessario un aggiornamento.

Nota

Qualsiasi operazione che modifica l'ETag di un trigger di monitoraggio provoca un aggiornamento, ad esempio una modifica del tipo di contenuto.

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. Aggiornare quindi una delle chiavi di controllo in un nuovo valore. Questa modifica attiva la creazione di un log. Ad esempio, la modifica del valore di attiva il messaggio di /application/config.message log seguente:

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.

Nota

Per impostazione predefinita, @ConfigurationProperties i fagioli annotati sono inclusi in questo ambito.

Aggiornamento basato sul pull

Le librerie Spring Configurazione app supportano la possibilità di controllare periodicamente in base a un intervallo di aggiornamento le modifiche apportate ai trigger di monitoraggio. Per impostazione predefinita, l'intervallo di aggiornamento è impostato su 30 secondi. Dopo aver superato l'intervallo di aggiornamento, tutti i trigger vengono archiviati nell'archivio specificato per verificare la presenza di modifiche. Qualsiasi modifica apportata alla chiave determina l'attivazione di 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 di app Azure.

Aggiornamento basato sul push

È possibile configurare la spring-cloud-azure-appconfiguration-config-web libreria per ricevere notifiche push dall'archivio di configurazione app Azure per aggiornare i valori di configurazione. È possibile configurare questa configurazione tramite un web hook Griglia di eventi di Azure, che è possibile configurare per inviare notifiche di modifiche alle chiavi specificate. Aggiungendo la libreria di attuatori Spring come dipendenza, è possibile esporre gli endpoint di aggiornamento di Configurazione app. 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à scade l'intervallo di aggiornamento, quindi l'intervallo di aggiornamento rimanente non viene atteso prima del controllo dell'aggiornamento successivo. La appconfiguration-refresh-bus proprietà invia una notifica a un servizio di messaggistica connesso, ad esempio 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 è disattivato da una piccola quantità di instabilità. Questo instabilità garantisce che ogni istanza dell'applicazione non tenti di aggiornare contemporaneamente.

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

Oltre a esporre gli endpoint di aggiornamento, è stato aggiunto un parametro di query obbligatorio per la sicurezza. Per impostazione predefinita, non è impostato alcun nome o valore del token, ma è necessario impostarne uno per usare gli 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 web hook, aprire l'archivio di configurazione app Azure e aprire Eventi dal menu di spostamento. 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 Seleziona endpoint. L'endpoint dovrebbe essere simile all'esempio seguente: https://www.myaplication.com/actuator/appconfiguration-refresh?myTokenName=mySecret.

Confermare che Selection invia una notifica di installazione all'URI specificato e prevede 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 app Azure è configurato per l'applicazione. Questa conferma può essere inviata in altri modi. Per altre informazioni sul recapito di web hook, vedere Recapito di eventi webhook.

Nota

Questa convalida viene eseguita solo dopo la creazione o la modifica dell'endpoint.

È 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à :

Nome	Descrizione	Richiesto	Valore predefinito
spring.cloud.azure.appconfiguration.refresh-interval	Intervallo di tempo standard tra gli aggiornamenti. È un oggetto Duration.	No	Null

L'aggiornamento con spring.cloud.azure.appconfiguration.refresh-interval non controlla le chiavi dell'espressione di controllo configurate. Questa proprietà viene usata per assicurarsi che i segreti dell'insieme di credenziali delle chiavi vengano mantenuti aggiornati perché app Azure Configurazione 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. Dopo aver superato l'intervallo di aggiornamento, tutti i flag di funzionalità vengono archiviati nell'archivio specificato per verificare la presenza di modifiche. Qualsiasi modifica apportata alla chiave determina l'attivazione di 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 integrità

La libreria client include un indicatore di integrità che controlla se la connessione all'archivio di configurazione di app Azure o gli archivi è integra. Se abilitato per ogni archivio, 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 ritenta automaticamente la connessione all'archivio 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 Configurazione app usa Azure SDK per Java per la connessione a configurazione app Azure e Azure Key Vault. Per modificare i client, vengono fornite due interfacce e ConfigurationClientCustomizerSecretClientCustomizer. 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 setup(ConfigurationClientBuilder builder, String endpoint);
}

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

Nota

e ConfigurationClientBuilderSecretClientBuilder sono già configurati per l'uso quando vengono passati a customize. Tutte le modifiche apportate ai client, incluse le credenziali e i criteri di ripetizione dei tentativi, sostituiscono quelle già presenti.

È anche possibile eseguire questa configurazione usando la configurazione di Spring Cloud Azure.

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

}