Suporte à configuração de aplicativos

Este artigo descreve a biblioteca de Configuração de Aplicativo do Azure do Spring Cloud. Esta biblioteca carrega configurações e sinalizadores de recursos do serviço de Configuração de Aplicativo do Azure. A biblioteca gera PropertySource abstrações para corresponder às abstrações já geradas pelo ambiente Spring, como variáveis de ambiente, configurações de linha de comando, arquivos de configuração local e assim por diante.

O Spring é uma estrutura de aplicativos de código aberto desenvolvida pela VMware que fornece uma abordagem simplificada e modular para a criação de aplicativos Java. O Spring Cloud Azure é um projeto de código aberto que fornece integração perfeita do Spring com os serviços do Azure.

Pré-requisitos

• Uma assinatura do Azure - crie uma gratuitamente.
• Java Development Kit (JDK) versão 8 ou superior.
• Apache Maven
• CLI do Azure

Configurar a sua loja de Configuração de Aplicações

Use o seguinte comando para criar sua loja de Configuração de Aplicativo do Azure:

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

Este comando cria um novo repositório de configuração vazio. Você pode carregar suas configurações usando o seguinte comando de importação:

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

Confirme suas configurações antes de carregá-las. Você pode carregar arquivos YAML alterando o formato para YAML. O campo de prefixo é importante porque é o prefixo padrão carregado pela biblioteca do cliente.

Utilização da biblioteca

Para usar o recurso em um aplicativo, você pode criá-lo como um aplicativo Spring Boot. A maneira mais conveniente de adicionar a dependência é com o starter do Spring Boot com.azure.spring:spring-cloud-azure-starter-appconfiguration-config. O arquivo pom.xml a seguir usa a Configuração de Aplicativos do Azure:

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

O exemplo a seguir mostra um aplicativo Spring Boot básico usando a Configuração do aplicativo:

@SpringBootApplication
@RestController
public class Application {

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

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

Neste exemplo, o arquivo application.properties contém a seguinte linha:

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

CONFIG_STORE_ENDPOINT é uma variável de ambiente com a URL do ponto de extremidade para sua Loja de Configuração de Aplicativos do Azure.

Nota

A Microsoft recomenda o uso do fluxo de autenticação mais seguro disponível. O fluxo de autenticação descrito neste procedimento, como para bancos de dados, caches, mensagens ou serviços de IA, requer um grau muito alto de confiança no aplicativo e traz riscos não presentes em outros fluxos. Use esse fluxo somente quando opções mais seguras, como identidades gerenciadas para conexões sem senha ou sem chave, não forem viáveis. Para operações de máquina local, prefira identidades de usuário para conexões sem senha ou sem chave.

Por padrão, se nenhuma configuração for definida, as configurações que começam com /application/ são carregadas com um rótulo padrão de (No Label) a menos que um Perfil Spring seja definido. Nesse caso, o rótulo padrão é o seu Perfil Spring.

Uma fonte de propriedades chamada /application/https://<name-of-your-store>.azconfig.io/ é criada contendo as propriedades dessa store. O rótulo usado na solicitação é anexado ao final do nome. Se nenhum rótulo for definido, o caractere \0 estará presente como um espaço vazio.

Carregando configuração

A biblioteca suporta a integração de um ou vários repositórios de Configuração de Aplicações. Na situação em que uma chave é duplicada em várias lojas, a última vence.

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

Neste exemplo, se ambos os repositórios tiverem a mesma chave de configuração, a configuração no segundo repositório terá a prioridade mais alta.

Nota

Você pode usar as definições de Configuração do Aplicativo do Azure como qualquer outra Configuração do Spring. Para obter mais informações, consulte Recursos principais na documentação do Spring Boot ou Guia de início rápido: criar um aplicativo Java Spring com a Configuração do Aplicativo do Azure.

Seleção de configurações

A biblioteca carrega configurações usando sua chave e rótulo. Por padrão, as configurações que começam com a chave /application/ são carregadas. O rótulo padrão é \0, que aparece como (No Label) no portal do Azure. Se um perfil Spring estiver definido e nenhum rótulo for fornecido, o rótulo padrão será o seu Perfil Spring, que é ${spring.profiles.active}.

Você pode configurar quais configurações são carregadas selecionando diferentes filtros de chave e rótulo:

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

A key-filter propriedade suporta os seguintes filtros:

Filtro principal	Efeito
*	Corresponde a qualquer tecla.
abc	Corresponde a uma chave chamada abc.
abc*	Corresponde a nomes de chaves que começam com abc.
abc,xyz	Corresponde a nomes de chave abc ou xyz. Limitado a cinco valores separados por vírgula.

A label-filter propriedade suporta os seguintes filtros:

Etiqueta	Descrição
*	Corresponde a qualquer rótulo, incluindo \0.
\0	Corresponde a null rótulos, que aparecem como (No Label) no portal do Azure.
1.0.0	Corresponde exatamente ao rótulo 1.0.0 .
1.0.*	Corresponde a rótulos que começam com 1.0.*.
,1.0.0	Corresponde a rótulos null e 1.0.0. Limitado a cinco valores separados por vírgula.

Se estiveres a usar YAML com filtros de rótulo e quiseres carregar configurações sem rótulo, bem como outras configurações com diferentes rótulos, precisarás de incluir um , vazio. Por exemplo, ,dev corresponde a \0 e dev. Neste caso, envolva o filtro de etiquetas com aspas simples. Esse valor permite que você carregue a configuração sem rótulo primeiro, seguida por configurações com rótulos específicos, no mesmo filtro:

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

Nota

Não é possível combinar * com , em filtros. Nesse caso, você precisa usar um valor de seleção adicional.

Quando utilizas * no filtro de rótulo, e várias configurações com a mesma chave são carregadas, estas são carregadas em ordem alfabética, e o rótulo que aparece por último na ordem alfabética é utilizado.

Spring Perfis

Por padrão, spring.profiles.active é definido como padrão label-filter para todas as configurações selecionadas. Você pode substituir essa funcionalidade usando label-filter. Pode usar os Perfis Spring no label-filter usando ${spring.profiles.active}, conforme mostrado no exemplo a seguir:

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

No primeiro label-filter, a biblioteca carrega primeiro todas as configurações com a etiqueta \0, seguidas por todas as configurações correspondentes aos Spring Profiles. Os perfis Spring têm prioridade sobre as \0 configurações, porque estão no final.

No segundo label-filter, a string _local é anexada ao final dos Perfis Spring, embora apenas ao último Perfil Spring se houver mais de um.

Lojas para deficientes

Usando a configuração spring.cloud.azure.appconfiguration.enabled, você pode desativar o carregamento para todos os armazenamentos de configuração. Com a spring.cloud.azure.appconfiguration.stores[0].enabled configuração, você pode desativar uma loja individual.

Nota

Se você usar métricas de saúde, ainda verá suas lojas listadas, mas com o valor NOT LOADED. Quando você verifica as fontes de propriedade carregadas, ainda as vê listadas, mas elas não contêm valores. Esse comportamento é devido à spring.config.import propriedade que está sendo definida. Se azureAppConfiguration não estiver definido para spring.config.import, nenhum valor será mostrado.

Autenticação

A biblioteca dá suporte a todas as formas de identidade suportadas pela Biblioteca de Identidades do Azure. Você pode fazer a autenticação por meio da configuração para cadeias de conexão e identidade gerenciada.

Nota

A Microsoft recomenda o uso do fluxo de autenticação mais seguro disponível. O fluxo de autenticação descrito neste procedimento, como para bancos de dados, caches, mensagens ou serviços de IA, requer um grau muito alto de confiança no aplicativo e traz riscos não presentes em outros fluxos. Use esse fluxo somente quando opções mais seguras, como identidades gerenciadas para conexões sem senha ou sem chave, não forem viáveis. Para operações de máquina local, prefira identidades de usuário para conexões sem senha ou sem chave.

Cadeia de conexão (não recomendado)

A autenticação por meio da cadeia de conexão é a forma mais simples de configurar, embora não seja recomendada. Você pode acessar as cadeias de conexão de uma loja usando o seguinte comando:

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

Em seguida, você pode definir a spring.cloud.azure.appconfiguration.stores[0].connection-string propriedade para a cadeia de conexão. Ao usar essa abordagem, é altamente recomendável definir a cadeia de conexão no arquivo de configuração local como um valor de espaço reservado que mapeia para uma variável de ambiente. Essa abordagem permite que você evite adicionar a cadeia de conexão ao controle do código-fonte.

Configuração do Spring Cloud Azure

Você pode usar a configuração do Spring Cloud Azure para configurar a biblioteca. Você pode usar as seguintes propriedades para configurar a biblioteca:

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

Quando apenas o ponto de extremidade é definido, a biblioteca de cliente usa o DefaultAzureCredential para autenticar.

Você precisa atribuir a identidade usada para ler as configurações. Você pode criar essa atribuição usando o seguinte comando:

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

Você pode definir apenas um método de autenticação por ponto de extremidade: cadeia de conexão, identidade atribuída pelo usuário ou credencial de token. Se você precisar misturar e combinar, você pode usar ConfigurationClientCustomizer para modificar o ConfigurationClientBuilder para usar métodos diferentes.

Nota

A Microsoft recomenda o uso do fluxo de autenticação mais seguro disponível. O fluxo de autenticação descrito neste procedimento, como para bancos de dados, caches, mensagens ou serviços de IA, requer um grau muito alto de confiança no aplicativo e traz riscos não presentes em outros fluxos. Use esse fluxo somente quando opções mais seguras, como identidades gerenciadas para conexões sem senha ou sem chave, não forem viáveis. Para operações de máquina local, prefira identidades de usuário para conexões sem senha ou sem chave.

Georreplicação

A biblioteca dá suporte ao recurso de replicação geográfica da Configuração de Aplicativo do Azure. Esse recurso permite que você replique seus dados para outros locais. Esse recurso é útil para alta disponibilidade e recuperação de desastres.

Cada réplica criada tem um ponto de extremidade dedicado. Se seu aplicativo reside em várias geolocalizações, você pode atualizar cada implantação de seu aplicativo em um local para se conectar à réplica mais próxima desse local, o que ajuda a minimizar a latência de rede entre seu aplicativo e a Configuração do aplicativo. Como cada réplica tem sua cota de solicitação separada, essa configuração também ajuda a escalabilidade do seu aplicativo enquanto ele cresce para um serviço distribuído de várias regiões.

Por padrão, a biblioteca descobre automaticamente todas as réplicas existentes para um repositório de configuração. Quando uma solicitação é feita ao armazenamento fornecido e falha, a biblioteca tenta automaticamente a solicitação novamente em relação às réplicas disponíveis.

O failover pode ocorrer se a biblioteca observar qualquer uma das seguintes condições:

• Recebe respostas com código de status de serviço indisponível (HTTP 500 ou superior) de um ponto de extremidade.
• Enfrenta problemas de conectividade de rede.
• As solicitações são restringidas (código de status HTTP 429).

Depois que a loja fornecida fica on-line novamente, a biblioteca reprocessa automaticamente o pedido na loja fornecida.

Se pretender controlar o comportamento de failover, pode fornecer manualmente uma lista de lojas a serem usadas para 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]

ou

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 todos os pontos de extremidade de réplica fornecidos falharem, a biblioteca tentará se conectar a réplicas descobertas automaticamente do armazenamento primário.

Você pode desabilitar a replicação com a configuração spring.cloud.azure.appconfiguration.stores[0].replica-discovery-enabled=false.

Criando um repositório de configuração com replicação geográfica

Para criar uma réplica do seu repositório de configuração, você pode usar a CLI do Azure ou o portal do Azure. O exemplo a seguir usa a CLI do Azure para criar uma réplica na região Leste dos EUA 2:

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

Valores-chave

A Configuração de Aplicativo do Azure dá suporte a vários tipos de valores de chave, alguns dos quais têm recursos especiais incorporados a eles. Configuração de Aplicativo Azure tem suporte embutido para o tipo de conteúdo JSON, espaços reservados Spring e referências do Key Vault.

Marcadores de Posição

A biblioteca suporta configurações com espaços reservados para ambientes do tipo ${}. Ao referenciar uma chave da Configuração de Aplicações do Azure com um espaço reservado, remova os prefixos da referência. Por exemplo, /application/config.message é referenciado como ${config.message}.

Nota

O prefixo que está sendo removido corresponde ao valor spring.cloud.azure.appconfiguration.stores[0].selects[0].key-filter. O prefixo que está sendo cortado pode ser alterado definindo um valor para spring.cloud.azure.appconfiguration.stores[0].trim-key-prefix[0].

JSON

As configurações que têm um tipo application/json de conteúdo são processadas como objetos JSON. Esse recurso permite mapear uma configuração para um objeto complexo dentro de um @ConfigurationPropertiesarquivo . Por exemplo, considere a chave /application/config.colors JSON com o seguinte valor:

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

Esta chave corresponde ao seguinte código:

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

    private Map<String, Color> colors;

}

Referências do Key Vault

A Configuração de Aplicativo do Azure e suas bibliotecas dão suporte à referência de segredos armazenados no Cofre da Chave. Na Configuração do Aplicativo, você pode criar chaves com valores mapeados para segredos armazenados em um Cofre de Chaves. Os segredos permanecem seguros no Cofre da Chave, mas você pode acessá-los da mesma forma que qualquer outra configuração ao carregar o aplicativo.

O seu aplicativo usa o provedor do cliente para recuperar referências do Azure Key Vault, assim como faz para quaisquer outras chaves armazenadas no App Configuration. Como o cliente reconhece as chaves como referências do Cofre da Chave, elas têm um tipo de conteúdo exclusivo e o cliente se conecta ao Cofre da Chave para recuperar seus valores para você.

Nota

O Key Vault só permite que os segredos sejam recuperados um de cada vez, portanto, cada referência do Key Vault armazenada na Configuração do Aplicativo resulta em uma consulta ao Key Vault.

Criando referências do Key Vault

Você pode criar uma referência do Cofre de Chaves no portal do Azure indo para Gerenciador de configurações>Criar>referência do Cofre de Chaves. Em seguida, você pode selecionar um segredo para referência em qualquer um dos Cofres de Chaves aos quais você tem acesso. Você também pode criar referências arbitrárias do Cofre de Chaves na guia Entrada. No portal do Azure, insira um URI válido.

Você também pode criar uma referência do Cofre da Chave por meio da CLI do Azure usando o seguinte comando:

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

Você pode criar qualquer identificador de segredo por meio da CLI do Azure. Os identificadores secretos requerem apenas o formato {vault}/{collection}/{name}/{version?} em que a secção de versão é opcional.

Usando referências do Key Vault

Você pode usar a configuração do Spring Cloud Azure para configurar a biblioteca. Você pode usar a mesma credencial usada para se conectar à Configuração do Aplicativo para se conectar ao Cofre da Chave do Azure.

Você também pode criar um SecretClientCustomizer da mesma maneira que criaria um ConfigurationClientCustomizer para fornecer seu próprio método de autenticação.

Resolver segredos que não sejam do Cofre da Chave

A biblioteca de Configuração de Aplicações fornece um método para substituir a resolução de referências do Key Vault. Por exemplo, você pode usá-lo para resolver segredos localmente em um ambiente de desenvolvimento. Esta resolução é feita através do KeyVaultSecretProvider. O KeyVaultSecretProvider, se fornecido, é chamado em todas as referências do cofre de chaves. Se getSecret retornar um valor não nulo, ele será usado como o valor secreto. Caso contrário, a Referência do Cofre da Chave será resolvida normalmente.

public class MySecretProvider implements KeyVaultSecretProvider {

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

}

Gestão de funcionalidades

O gerenciamento de recursos fornece uma maneira para os aplicativos Spring Boot acessarem dinamicamente o conteúdo. O gerenciamento de recursos tem várias funções, como as seguintes:

• Sinalizadores de recursos que podem habilitar ou desabilitar conteúdo
• Filtros de funcionalidades para segmentação quando o conteúdo é mostrado
• Filtros de recursos personalizados
• Portões de recursos para habilitar pontos de extremidade dinamicamente

Você pode habilitar sinalizadores de recursos por meio da seguinte configuração:

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

Os sinalizadores de recursos ativados são carregados no sistema de configuração Spring com o prefixo feature-management. Você também pode registrar sinalizadores de recursos no arquivo de configuração local. Para obter mais informações, consulte a seção Declaração de sinalizador de funcionalidade.

A maneira mais fácil de usar o gerenciamento de recursos é usando as spring-cloud-azure-feature-management bibliotecas e spring-cloud-azure-feature-management-web . A diferença entre as duas bibliotecas é que spring-cloud-azure-feature-management-web depende das spring-web bibliotecas e spring-webmvc para adicionar mais recursos, como portas de recursos.

Por padrão, todos os sinalizadores de recursos com um \0 rótulo, visto como (No Label), são carregados. Você pode configurar os sinalizadores de recursos que são carregados definindo um filtro de rótulo, conforme mostrado no exemplo a seguir:

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

Noções básicas de gestão de funcionalidades

Marcas de funcionalidades

Os sinalizadores de recursos são compostos por várias partes, incluindo um nome e uma lista de filtros de recursos que são usados para ativar o recurso. Os sinalizadores de recursos podem ter um estado booleano de ativado ou desativado ou podem ter uma lista de filtros de recursos. Os sinalizadores de recursos avaliam os filtros de recursos até que um retorne true. Se nenhum filtro de recurso retornar true, o sinalizador de recurso retornará false.

Filtros de funcionalidades

Os filtros de recursos definem um cenário para quando um recurso deve ser habilitado. Os filtros de recursos são avaliados de forma síncrona.

A biblioteca de gerenciamento de recursos vem com quatro filtros predefinidos: AlwaysOnFilter, PercentageFilter, TimeWindowFilter e TargetingFilter.

Você pode criar filtros de recursos personalizados. Por exemplo, você pode usar um filtro de recursos para fornecer uma experiência personalizada para clientes que estão usando um navegador Microsoft Edge. Você pode personalizar os recursos desse filtro de recursos, por exemplo, para mostrar um cabeçalho específico para o público do navegador Microsoft Edge.

Declaração de sinalizador de recurso

A biblioteca de gerenciamento de funcionalidades dá suporte à Configuração de Aplicativos do Azure, juntamente com application.yml ou application.properties como fontes para sinalizadores de funcionalidades. Aqui está um exemplo do formato usado para configurar sinalizadores de recursos em um arquivo de 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

Este exemplo tem os seguintes flags de funcionalidades:

• feature-t está definido como false. Essa configuração sempre retorna o valor do sinalizador de recurso.
• feature-u é usado com filtros de funcionalidades. Esses filtros são definidos sob a enabled-for propriedade. Nesse caso, feature-u tem um filtro de recurso chamado Random, que não requer nenhuma configuração, portanto, apenas a propriedade name é necessária.
• feature-v Especifica um filtro de recurso chamado TimeWindowFilter. Este filtro de recurso pode receber parâmetros para usar como configuração. Neste exemplo, um TimeWindowFilter define as horas de início e término durante as quais o recurso está ativo.
• feature-w é usado para o AlwaysOnFilter, que sempre resulta em true. O evaluate campo é usado para interromper a avaliação dos filtros de funcionalidades e resulta no filtro de funcionalidade sempre retornando false.

Avaliando sinalizadores de recursos

A spring-cloud-azure-feature-management biblioteca fornece FeatureManager para determinar se um sinalizador de recurso está habilitado. FeatureManager Fornece uma maneira assíncrona de verificar o estado do sinalizador.

spring-cloud-azure-feature-management-web, juntamente com o fornecimento FeatureManager, contém FeatureManagerSnapshot, que armazena em cache o estado dos sinalizadores de recursos avaliados anteriormente no @RequestScope para garantir que todas as solicitações retornem o mesmo valor. Além disso, a biblioteca da Web fornece @FeatureGate, que pode bloquear ou redirecionar solicitações Web para diferentes endereços.

Verificação do sinalizador de recursos

FeatureManager é um @Bean que pode ser @Autowired ou injetado em @Component objetos tipo. FeatureManager tem um método isEnabled que, quando passado o nome de um sinalizador de recurso, retorna seu estado.

@Autowired
FeatureManager featureManager;

...

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

Nota

FeatureManager também tem uma versão assíncrona do isEnabled chamado isEnabledAsync.

Sem configuração de gerenciamento de recursos ou quando o sinalizador de recurso não existe, isEnabled sempre retorna false. Se um sinalizador de recurso existente estiver configurado com um filtro de recurso desconhecido, um FilterNotFoundException será lançado. Você pode alterar esse comportamento para retornar false configurando fail-fast como false. A tabela a seguir descreve fail-fast:

Nome	Descrição	Necessário	Predefinição
spring.cloud.azure.feature.management.fail-fast	Se ocorrer uma exceção, um RuntimeException é gerado. Se essa propriedade estiver definida como false, então isEnabled retornará false em vez disso.	Não	true

A única diferença entre FeatureManagerSnapshot e FeatureManager é o armazenamento em cache dos resultados no @RequestScope.

Gate de funcionalidades

Com a biblioteca web de gestão de funcionalidades, pode exigir que uma determinada funcionalidade esteja habilitada para executar um endpoint. Você pode configurar esse requisito usando a @FeatureGate anotação, conforme mostrado no exemplo a seguir:

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

Você só pode aceder ao featureT endpoint se "feature-t" estiver ativado.

Gestão de ações desativada

Quando um ponto de extremidade é bloqueado porque o recurso especificado está desativado, DisabledFeaturesHandler é invocado. Por padrão, um HTTP 404 é retornado. Você pode substituir esse comportamento implementando DisabledFeaturesHandler, conforme mostrado no exemplo a seguir:

@Component
public class MyDisabledFeaturesHandler implements DisabledFeaturesHandler {

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

}

Encaminhamento

Determinadas rotas podem expor as capacidades do aplicativo que são controladas por recursos. Se um recurso estiver desabilitado, você poderá redirecionar essas rotas para outro ponto de extremidade, conforme mostrado no exemplo a seguir:

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

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

Filtros de funcionalidades incorporadas

Há alguns filtros de funcionalidades que acompanham o pacote spring-cloud-azure-feature-management. Esses filtros de recursos são adicionados automaticamente.

AlwaysOnFilter

Este filtro sempre retorna true. Para obter um exemplo de uso, consulte a seção Declaração de feature flag.

Filtro de Percentagem

Cada vez que é verificado, a avaliação de PercentageFilter pode retornar um resultado diferente. Você pode contornar esta inconsistência usando o FeatureManagementSnapshot, que armazena em cache o resultado do sinalizador de recurso por solicitação.

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

Filtro de Janela Temporal

Esse filtro fornece a capacidade de habilitar um recurso com base em uma janela de tempo. Se você especificar apenas End, o recurso será considerado ativado até esse momento. Se você especificar apenas Start, o recurso será considerado ativado em todos os pontos após esse período. Se você especificar ambos, o recurso será considerado válido entre as duas vezes.

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"

Este filtro também suporta filtros de janela de tempo recorrentes. Ele suporta recorrências diárias e semanais, juntamente com um tempo de expiração.

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

Este padrão de recorrência acontece todas as semanas às segundas e quartas-feiras das 00:00:00 GMT às 12:00:00 GMT e não expira.

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"

Este padrão de recorrência acontece em dias alternados das 00:00:00 GMT às 12:00:00 GMT até à data final.

TargetingFilter

Esse filtro fornece a capacidade de habilitar um recurso para um público-alvo. Para obter uma explicação detalhada da segmentação, consulte a seção de segmentação . Os parâmetros de filtro incluem um objeto de audiência que descreve usuários, grupos e uma porcentagem padrão da base de usuários que deve ter acesso ao recurso. Para cada objeto de grupo listado no público-alvo, é necessária uma porcentagem que define a porcentagem de membros desse grupo que têm acesso ao recurso. Um usuário tem o recurso ativado nos seguintes casos:

• O usuário é especificado na seção de usuários diretamente.
• O utilizador está incluído na percentagem de qualquer uma das implementações do grupo.
• O usuário cai na porcentagem de distribuição padrão.

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

Filtros de recursos personalizados

A criação de um filtro de recursos personalizado fornece uma maneira de habilitar recursos com base em critérios definidos por você. Para criar um filtro de recurso personalizado, você deve implementar a FeatureFilter interface. FeatureFilter tem um único método evaluate. Quando um recurso especifica que pode ser habilitado com um filtro de recurso, o evaluate método é chamado. Se evaluate retornar true, significa que o recurso deve ser ativado. Se retornar false, continuará a avaliar filtros de características até que um retorne true. Se todos os filtros retornarem false, o recurso estará desativado.

Os filtros de funcionalidade são definidos como Spring Beans, portanto, são definidos como @Component ou definidos em um @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;
    }

}

Filtros de recursos parametrizados

Alguns filtros de recursos exigem parâmetros para determinar se um recurso deve ser ativado. Por exemplo, um filtro de recursos do navegador pode ativar um recurso para um determinado conjunto de navegadores. Você pode querer um recurso ativado para os navegadores Microsoft Edge e Chrome, mas não para o Firefox. Para configurar esta situação, pode criar um filtro de funcionalidade para aceitar parâmetros. Esses parâmetros seriam especificados na configuração do recurso e no código, e seriam acessíveis através do FeatureFilterEvaluationContext parâmetro de evaluate. FeatureFilterEvaluationContext tem uma propriedade parameters, que é um Map<String, Object>.

Segmentação

A segmentação é uma estratégia de gerenciamento de recursos que permite que os desenvolvedores implementem progressivamente novos recursos em sua base de usuários. A estratégia baseia-se no conceito de segmentação de um conjunto de utilizadores conhecido como público-alvo. Um público é composto por usuários específicos, grupos e uma porcentagem designada de toda a base de usuários. Os grupos que estão incluídos no público-alvo podem ser divididos em porcentagens dos seus membros totais.

As etapas a seguir demonstram um exemplo de uma distribuição progressiva para um novo recurso 'Beta':

1. Os usuários individuais Jeff e Alicia têm acesso ao Beta.
2. Outro utilizador, Mark, pede para aderir e é incluído.
3. Vinte por cento dos utilizadores de um grupo conhecido como "Ring1" estão incluídos na Beta.
4. O número de usuários "Ring1" incluídos na versão beta é aumentado para 100%.
5. Cinco por cento da base de utilizadores está incluída na versão beta.
6. A porcentagem de lançamento é aumentada para 100% e o recurso é completamente implementado.

Essa estratégia para implantar um recurso é incorporada à biblioteca por meio do filtro de recursos incluído TargetingFilter .

Segmentação numa aplicação

Uma aplicação web de exemplo que usa o filtro de funcionalidade de direcionamento está disponível no projeto de exemplo.

Para começar a usar o TargetingFilter numa aplicação, deve adicioná-lo como um filtro de recurso, tal como qualquer outro. TargetingFilter depende de outro @Bean para ser adicionado ao aplicativo TargetingContextAccessor. O TargetingContextAccessor permite definir a TargetingContext atual para ser usada para definir a identificação do utilizador atual e grupos, conforme mostrado no exemplo a seguir:

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

}

Direcionar as opções de avaliação

Estão disponíveis opções para personalizar a forma como a avaliação de segmentação é realizada em um determinado TargetingFilter. Você pode definir um parâmetro opcional, TargetingEvaluationOptions, durante a TargetingFilter criação.

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

Atualização de configuração

Ativar a atualização de configuração para as suas configurações permite-lhe extrair os valores mais recentes da sua loja ou lojas de Configuração de Aplicações sem ter de reiniciar a aplicação.

Para habilitar a atualização, você precisa habilitar o monitoramento junto com os gatilhos de monitoramento. Um gatilho de monitoramento é uma chave com um rótulo opcional que o sistema monitora para alterações de valor para acionar atualizações. O valor do gatilho de monitoramento pode ser qualquer valor, desde que seja alterado quando uma atualização é necessária.

Nota

Qualquer operação que altere a ETag de um gatilho de monitoramento causa uma atualização, como uma alteração de tipo de conteúdo.

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

Para acionar uma atualização de configuração, altere o valor de uma chave no repositório de configuração. Em seguida, atualize uma das chaves de observação para um novo valor. Essa alteração dispara a criação de um log. Por exemplo, alterar o valor de /application/config.message aciona a seguinte mensagem de log:

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

Após o aplicativo gerar o log, ele atualiza todos os @Beans no escopo de atualização.

Nota

Por predefinição, @ConfigurationProperties componentes anotados são incluídos nesse escopo.

Atualização baseada em solicitação

As bibliotecas do App Configuration Spring suportam a capacidade de verificar periodicamente em um intervalo de atualização as alterações feitas nos gatilhos de monitoramento. Por padrão, o intervalo de atualização é definido como 30 segundos. Depois que o intervalo de atualização passa, quando uma tentativa de atualização é feita, todos os gatilhos são verificados no armazenamento fornecido para alterações. Qualquer alteração na chave faz com que uma atualização seja acionada. Como as bibliotecas se integram ao sistema de atualização Spring, qualquer atualização recarrega todas as configurações de todas as lojas. Você pode definir o intervalo de atualização para qualquer intervalo superior a 1 segundo. As unidades suportadas para o intervalo de atualização são s, m, h, e d por segundos, minutos, horas e dias, respectivamente. O exemplo a seguir define o intervalo de atualização como 5 minutos:

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

Automatizado

Quando você usa a spring-cloud-azure-appconfiguration-config-web biblioteca, o aplicativo verifica automaticamente se há uma atualização sempre que ocorre uma solicitação de servlet, especificamente ServletRequestHandledEvent. A maneira mais comum de enviar este evento é por solicitações para endpoints em @RestController.

Manual

Em aplicações que usam apenas spring-cloud-azure-appconfiguration-config, como aplicações de console, pode acionar uma atualização manual chamando o método de AppConfigurationRefresh do refreshConfiguration. AppConfigurationRefresh é um @Bean que pode ser injetado em qualquer @Component.

Além disso, como a biblioteca usa o sistema de configuração do Spring, acionar uma atualização causa uma atualização de todas as suas configurações, não apenas uma recarga das da sua loja de Configuração de Aplicativos do Azure.

Atualização baseada em push (não recomendada)

Nota

Este método não é mais recomendado, mas ainda é suportado.

Você pode configurar a spring-cloud-azure-appconfiguration-config-web biblioteca para receber notificações por push da sua loja de Configuração de Aplicativo do Azure para atualizar seus valores de configuração. Você pode configurar essa configuração por meio de um Gancho da Web da Grade de Eventos do Azure, que pode ser configurado para enviar notificações de alterações em chaves especificadas. Ao adicionar a biblioteca Spring Actuator como uma dependência, é possível expor os endpoints de atualização da Configuração de Aplicação. Existem dois pontos finais diferentes: appconfiguration-refresh e appconfiguration-refresh-bus. Esses pontos de extremidade funcionam de forma semelhante aos seus homólogos refresh e refresh-bus, onde os pontos de extremidade de configuração do aplicativo expiram o intervalo de atualização em vez de forçar uma atualização ao receber. Você ainda pode usar o refresh e refresh-bus, mas não pode conectá-los diretamente à Grade de Eventos do Azure com um Gancho da Web porque eles exigem uma resposta na instalação.

A propriedade appconfiguration-refresh termina o intervalo de atualização, de modo que o tempo restante do intervalo de atualização não é considerado antes da próxima verificação de atualização. A appconfiguration-refresh-bus propriedade envia uma notificação para um serviço de mensagens conectado, como o Service Bus do Azure, para notificar todas as instâncias de uma aplicação para atualizar. Em ambos os casos, ele não expira completamente no intervalo de atualização, mas é desativado por uma pequena quantidade de jitter. Esse desvio garante que todas as instâncias do seu aplicativo não tentem atualizar ao mesmo tempo.

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

Além de expor os endpoints de atualização, a biblioteca requer um parâmetro de consulta para segurança. Nenhum nome ou valor de token existe por padrão, mas você deve definir um para usar os pontos de extremidade, conforme mostrado no exemplo a seguir:

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]

Configurando ganchos da Web

Para configurar um gancho da Web, abra sua loja de Configuração de Aplicativo do Azure e abra Eventos no menu de navegação. Em seguida, selecione Assinatura do evento. Defina o nome do seu evento e selecione o tipo de endpoint para ser Web Hook. Selecionar Web Hook faz com que uma opção Endpoint apareça. Selecione Selecionar um ponto final. Seu ponto de extremidade deve se parecer com o exemplo a seguir: https://www.myaplication.com/actuator/appconfiguration-refresh?myTokenName=mySecret.

Confirmar seleção envia uma notificação de configuração para o URI fornecido e espera uma resposta. Se nenhuma resposta for retornada, a instalação falhará. A azure-spring-cloud-appconfiguration-web configuração da biblioteca para pontos de extremidade retorna a resposta correta se o repositório de Configuração de Aplicativo do Azure estiver configurado para o aplicativo. Esta confirmação pode ser enviada de outras formas. Para obter mais informações sobre a entrega de webhooks, consulte Entrega de eventos do Webhook.

Nota

Essa validação acontece apenas aquando da criação ou modificação do endpoint.

É altamente recomendável que você configure filtros porque, caso contrário, uma atualização é acionada após cada criação e modificação de chave.

Atualização forçada do cliente

Você pode configurar a biblioteca para forçar uma atualização de todas as configurações em um intervalo de atualização. A tabela a seguir descreve a refresh-interval propriedade:

Nome	Descrição	Necessário	Predefinição
spring.cloud.azure.appconfiguration.refresh-interval	A quantidade padrão de tempo entre as atualizações. É um Duration.	Não	null

Atualizar com spring.cloud.azure.appconfiguration.refresh-interval não verifica nenhuma chave de monitoramento configurada. Essa propriedade é usada para garantir que os segredos do Cofre da Chave sejam mantidos atualizados porque a Configuração do Aplicativo do Azure não pode dizer quando eles são atualizados.

Como o Azure Key Vault armazena o par de chaves pública e privada de um certificado como um segredo, seu aplicativo pode recuperar qualquer certificado como uma referência do Cofre da Chave na Configuração do Aplicativo. Como os certificados precisam ser alternados periodicamente, os aplicativos cliente precisam ser atualizados com a mesma frequência, o que pode ser feito usando o intervalo de atualização do cliente.

Atualização do sinalizador de recursos

Se os sinalizadores de recursos e o monitoramento estiverem habilitados, por padrão, o intervalo de atualização dos sinalizadores de recursos será definido como 30 segundos. Quando o intervalo de atualização termina, o sistema verifica se há alterações em todos os sinalizadores de recursos no armazenamento fornecido. Qualquer alteração na chave faz com que uma atualização seja acionada. Como as bibliotecas se integram ao sistema de atualização Spring, qualquer atualização recarrega todas as configurações de todas as lojas. Você pode definir o intervalo de atualização para qualquer intervalo superior a 1 segundo. As unidades suportadas para o intervalo de atualização são s, m, h, e d por segundos, minutos, horas e dias, respectivamente. O exemplo a seguir define o intervalo de atualização como 5 minutos:

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

Indicador de saúde

A biblioteca de cliente vem com um indicador de integridade que verifica se a conexão com a loja ou lojas de Configuração de Aplicativo do Azure está íntegra. Se habilitado para cada loja, ele fornece um dos seguintes valores de status:

• UP - A última ligação foi bem sucedida.
• DOWN- A última ligação resultou num código de erro não-200. Esse status pode ser devido a problemas que variam de credenciais expirando a um problema de serviço. A biblioteca de cliente automaticamente tenta conectar-se ao repositório no próximo intervalo de atualização.
• NOT LOADED - O repositório de configuração está listado no arquivo de configuração local, mas o repositório de configuração não foi carregado do arquivo na inicialização. O repositório de configuração está desativado no arquivo de configuração ou a configuração ou configurações falharam ao carregarem no arranque enquanto a configuração para o repositório estava definida como fail-fast.

Você pode ativar o indicador de integridade definindo management.health.azure-app-configuration.enabled=true.

Personalização do cliente

A biblioteca de Configuração de Aplicativo usa o SDK do Azure para Java para se conectar à Configuração de Aplicativo do Azure e ao Cofre da Chave do Azure. Duas interfaces, ConfigurationClientCustomizer e SecretClientCustomizer, são fornecidas para modificar os clientes. Cada interface tem um customize método que inclui o respetivo construtor juntamente com o String valor do URI para o qual o cliente será configurado, conforme mostrado nas seguintes definições de interface.

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

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

Essas interfaces permitem a personalização do cliente HTTP e suas configurações. O exemplo a seguir substitui o padrão HttpClient por outro que usa um proxy para todo o tráfego direcionado à Configuração do Aplicativo e ao Cofre da Chave.

Nota

Os ConfigurationClientBuilder e SecretClientBuilder já estão configurados para uso quando passados para customize. Qualquer alteração nos clientes, incluindo as credenciais e a política de novas tentativas, substitui os padrões já estabelecidos.

Você também pode fazer essa configuração usando a configuração do 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();
    }

}