Suporte à configuração de aplicativos

Este artigo descreve a biblioteca de Configuração de Aplicativos do Azure do Spring Cloud. Essa biblioteca carrega configurações e sinalizadores de recursos do serviço de Configuração de Aplicativos 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 aplicativo de software livre desenvolvida pela VMware que oferece uma abordagem simplificada e modular para a criação de aplicativos Java. O Spring Cloud Azure é um projeto de software livre 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 sua loja de configuração de aplicativos

Use o seguinte comando para criar seu repositório da Configuração de Aplicativos do Azure:

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

Esse 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 de cliente.

Uso 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 Spring Boot starter com.azure.spring:spring-cloud-azure-starter-appconfiguration-config. O arquivo pom.xml exemplo 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 básico do Spring Boot usando a Configuração de Aplicativos:

@SpringBootApplication
@RestController
public class Application {

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

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

Para este 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 o Repositório de Configuração de Aplicativos do Azure.

Observação

A Microsoft recomenda usar o fluxo de autenticação mais seguro disponível. O fluxo de autenticação descrito neste procedimento, como 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 computador 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/ serão carregadas com um rótulo padrão de (No Label), a menos que um Spring Profile seja definido, caso em que o rótulo padrão é o seu Spring Profile.

Uma fonte de propriedade chamada /application/https://<name-of-your-store>.azconfig.io/ é criada contendo as propriedades desse repositório. 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.

Configuração de carregamento

A biblioteca dá suporte ao carregamento de um ou vários repositórios da Configuração de Aplicativos. Na situação em que uma chave é duplicada em vários repositórios, 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.

Observação

Você pode usar as definições da Configuração de Aplicativos do Azure como qualquer outra Configuração do Spring. Para obter mais informações, consulte Principais recursos na documentação do Spring Boot ou Início Rápido: Criar um aplicativo Java Spring com a Configuração de Aplicativos do Azure.

Selecionando 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 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 dá suporte aos seguintes filtros:

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

A label-filter propriedade dá suporte aos seguintes filtros:

Etiqueta	Descrição
*	Corresponde a qualquer rótulo, incluindo \0.
\0	Corresponde aos rótulos null, que aparecem como (No Label) no portal do Azure.
1.0.0	Corresponde exatamente ao rótulo 1.0.0.
1.0.*	Corresponde aos 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 você estiver usando YAML com filtros de rótulo e quiser carregar configurações sem rótulo e mais configurações com outros rótulos, será necessário incluir um vazio ,. Por exemplo, ,dev correspondências \0 e dev. Nesse caso, cerque o filtro de rótulo com aspas simples. Esse valor permite carregar a configuração sem rótulo primeiro, seguido por configurações com rótulos específicos, no mesmo filtro:

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

Observação

Você não pode combinar * com , nos filtros. Nesse caso, você precisa usar um valor de seleção adicional.

Quando você usa * no filtro de rótulo e várias configurações com a mesma chave são carregadas, elas são carregadas em ordem alfabética e o rótulo último em ordem alfabética é usado.

Perfis de Spring

Por padrão, spring.profiles.active é definido como o padrão label-filter para todas as configurações selecionadas. Você pode substituir essa funcionalidade usando label-filter. Você pode usar os Perfis do Spring no label-filter usando o ${spring.profiles.active}, como 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 primeiro carrega todas as configurações com o \0 rótulo, seguido por todas as configurações correspondentes aos Perfis do Spring. Os perfis Spring têm prioridade sobre as \0 configurações, porque estão no final.

No segundo label-filter, a cadeia de caracteres _local é acrescentada ao final dos Perfis de Primavera, embora somente para o último Perfil do Spring se houver mais de um.

Lojas desabilitadas

Usando a configuração spring.cloud.azure.appconfiguration.enabled, você pode desabilitar o carregamento para todos os armazenamentos de configuração. Com a spring.cloud.azure.appconfiguration.stores[0].enabled configuração, você pode desabilitar um repositório individual.

Observação

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, elas ainda aparecem listadas, mas não contêm valores. Esse comportamento ocorre 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 de cadeias de conexão e identidade gerenciada.

Observação

A Microsoft recomenda usar o fluxo de autenticação mais seguro disponível. O fluxo de autenticação descrito neste procedimento, como 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 computador local, prefira identidades de usuário para conexões sem senha ou sem chave.

Cadeia de conexão (não recomendada)

A autenticação por meio da string de conexão é a forma mais simples de configurar, embora não seja recomendada. Você pode acessar as cadeias de conexão de um repositório 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 como 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 mapeado 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 clientes 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>

Observação

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 corresponder, poderá usar ConfigurationClientCustomizer para modificar os ConfigurationClientBuilder métodos diferentes.

Observação

A Microsoft recomenda usar o fluxo de autenticação mais seguro disponível. O fluxo de autenticação descrito neste procedimento, como 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 computador local, prefira identidades de usuário para conexões sem senha ou sem chave.

Replicação geográfica

A biblioteca dá suporte ao recurso de replicação geográfica da Configuração de Aplicativos 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 que você cria tem um ponto de extremidade dedicado. Se o seu aplicativo residir em várias localizações geográficas, você poderá atualizar cada implantação do aplicativo em um local para se conectar com a réplica mais próxima desse local, o que ajuda a minimizar a latência de rede entre o seu aplicativo e a Configuração de Aplicativos. Como cada réplica tem sua cota de solicitação separada, essa configuração também ajuda na escalabilidade do 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 que existem para um repositório de configuração. Quando uma solicitação é feita ao repositório fornecido e falha, a biblioteca tenta automaticamente a solicitação em relação às réplicas disponíveis.

O failover poderá 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 restritas (código de status HTTP 429).

Depois que o repositório fornecido voltar a ficar online, a biblioteca repetirá automaticamente a solicitação no repositório fornecido.

Se você quiser controlar o comportamento de failover, poderá fornecer manualmente uma lista de repositórios a serem usados 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]

or

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 repositório 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 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 principais

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

Espaços reservados

A biblioteca suporta configurações com marcadores de ambiente no estilo ${}. Ao referenciar uma chave de Configuração de Aplicativo do Azure com um placeholder, remova os prefixos da referência. Por exemplo, /application/config.message é referenciado como ${config.message}.

Observação

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 @ConfigurationProperties. 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]
 }
}

Essa chave é mapeada para o seguinte código:

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

    private Map<String, Color> colors;

}

Referências de Key Vault

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

Seu aplicativo usa o provedor de cliente para recuperar referências do Key Vault, assim como faz para qualquer outra chave armazenada na Configuração de Aplicativos. Como o cliente reconhece as chaves como referências do Key Vault, elas têm um tipo de conteúdo exclusivo e o cliente se conecta ao Key Vault para recuperar seus valores para você.

Observação

O Key Vault permite apenas a recuperação de um segredo por vez, portanto, cada referência do Key Vault armazenada na Configuração de Aplicativos resulta em uma solicitação ao Key Vault.

Criando referências do Key Vault

Você pode criar uma referência de Key Vault no portal do Azure acessando Configuration Explorer>Criar> Referência de Key Vault. Em seguida, você pode selecionar um segredo para referência em qualquer um dos Key Vaults aos quais você tem acesso. Você também pode criar referências arbitrárias do Key Vault na guia Entrada . No portal do Azure, insira um URI válido.

Você também pode criar uma referência do Key Vault 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 secreto por meio da CLI do Azure. Os identificadores secretos exigem apenas o formato {vault}/{collection}/{name}/{version?} em que a seçã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 de Aplicativos para se conectar ao Azure Key Vault.

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

Resolver segredos que não são do Key Vault

A biblioteca de Configuração de Aplicativos fornece um método para substituir a resolução de referências do cofre de chaves. 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 do segredo. Caso contrário, a Referência do Key Vault é resolvida normalmente.

public class MySecretProvider implements KeyVaultSecretProvider {

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

}

Gerenciamento 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 recursos para direcionar quando o conteúdo é exibido
• Filtros de recursos personalizados
• Portas de recursos para ativar dinamicamente os pontos de extremidade

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 habilitados são carregados no sistema de configuração do 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 recurso.

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 bibliotecas spring-web e spring-webmvc para adicionar mais recursos, como filtros de recursos.

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

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 gerenciamento de funcionalidades

Sinalizadores de recursos

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

Filtros de recursos

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 recurso para fornecer uma experiência personalizada para clientes que estão usando um navegador Microsoft Edge. Você pode personalizar os recursos nesse filtro de recursos, por exemplo, para mostrar um cabeçalho específico para o público do navegador Microsoft Edge.

Declaração do sinalizador de recurso

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

• feature-t é definido como false. Essa configuração sempre retorna o valor do sinalizador de recurso.
• feature-u é usado com filtros de recursos. Esses filtros são definidos na enabled-for propriedade. Nesse caso, feature-u tem um filtro de recurso chamado Random, que não requer nenhuma configuração, portanto, somente a propriedade name é necessária.
• feature-v especifica um filtro de recurso chamado TimeWindowFilter. Esse filtro de funcionalidades pode receber parâmetros para configuração. Neste exemplo, um TimeWindowFilter, passa os horários de início e término durante os quais o recurso está ativo.
• feature-w é usado para o AlwaysOnFilter, que sempre é avaliado como true. O evaluate campo é usado para interromper a avaliação dos filtros de recursos e faz com que o filtro de recursos sempre retorne false.

Avaliar sinalizadores de recursos

A biblioteca spring-cloud-azure-feature-management 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 FeatureManager, contém FeatureManagerSnapshot, que armazena em cache o estado dos sinalizadores de recursos avaliados anteriormente dentro do @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 para diferentes destinos.

Verificação do sinalizador de recurso

FeatureManager é um @Bean que pode ser @Autowired ou injetado em objetos do tipo @Component. 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
}

Observação

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

Sem a 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, uma FilterNotFoundException será gerada. Você pode alterar esse comportamento para retornar false configurando fail-fast para false. A tabela a seguir descreve fail-fast:

Nome	Descrição	Obrigatório	Padrão
spring.cloud.azure.feature.management.fail-fast	Se ocorrer uma exceção, um RuntimeException será gerado. Se essa propriedade for 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.

Porta de recursos

Com a biblioteca web de gerenciamento de funcionalidades, você 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 acessar o endpoint featureT se "feature-t" estiver ativado.

Manuseio de ações desabilitadas

Quando um ponto de extremidade é bloqueado porque o recurso especificado está desabilitado, 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;
    }

}

Roteamento

Determinadas rotas podem expor os recursos do aplicativo que são fechados 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 recurso internos

O pacote spring-cloud-azure-feature-management vem com alguns filtros de funcionalidades. Esses filtros de recursos são adicionados automaticamente.

Filtro AlwaysOn

Esse filtro sempre retorna true. Para obter um exemplo de uso, consulte a seção de declaração de sinalizador de recurso.

Filtro de porcentagem

Cada vez que ele é verificado, a avaliação PercentageFilter pode retornar um resultado diferente. Você pode contornar essa 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 de Tempo

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

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"

Esse filtro também dá suporte a filtros de janela de tempo recorrentes. Ele dá suporte a 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

Esse padrão de recorrência acontece toda semana na segunda e quarta-feira 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"

Esse padrão de recorrência acontece a cada dois dias das 00:00:00 GMT às 12:00:00 GMT até a data de término.

Filtro de segmentação

Esse filtro fornece a capacidade de habilitar um recurso para um público-alvo. Para obter uma explicação detalhada sobre a segmentação, consulte a seção de segmentação . Os parâmetros de filtro incluem um objeto de público-alvo 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 habilitado nos seguintes casos:

• O usuário é especificado diretamente na seção de usuários.
• O usuário está na porcentagem incluída de qualquer uma das distribuições de grupo.
• O usuário se enquadra na porcentagem de implantaçã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 feição customizado fornece uma maneira de habilitar feições com base nos critérios que você define. 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 ele pode ser habilitado com um filtro de recurso, o evaluate método é chamado. Se evaluate retornar true, significa que o recurso deve ser habilitado. Se retornar false, ele continua avaliando os filtros de recursos até que um retorne true. Se todos os filtros retornarem false, o recurso está desativado.

Os filtros de funcionalidades são definidos como Spring Beans, portanto, eles são definidos como @Component ou 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 recurso 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 essa situação, você pode criar um filtro de recursos para receber parâmetros. Esses parâmetros seriam especificados na configuração do recurso e no código, e seriam acessíveis por meio do parâmetro FeatureFilterEvaluationContext de evaluate. FeatureFilterEvaluationContext tem uma propriedade parameters, que é um Map<String, Object>.

Direcionamento

A segmentação é uma estratégia de gerenciamento de recursos que permite aos desenvolvedores implementar progressivamente novos recursos para sua base de usuários. A estratégia baseia-se no conceito de atingir um conjunto de usuários conhecido como público-alvo. Um público é composto por usuários, grupos específicos e uma porcentagem designada de toda a base de usuários. Os grupos incluídos na audiência podem ser divididos ainda mais em percentuais de 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 usuário, Mark, pede para aceitar e é incluído.
3. Vinte por cento de um grupo conhecido como usuários "Ring1" estão incluídos no Beta.
4. O número de usuários "Ring1" incluídos no beta é aumentado para 100%.
5. Cinco por cento da base de usuários está incluída na versão beta.
6. O percentual de distribuição é aumentado em até 100% e o recurso é completamente distribuído.

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

Direcionamento em um aplicativo

Um exemplo de aplicativo web que usa o filtro de funcionalidade de direcionamento está disponível no projeto de exemplo.

Para começar a usar o TargetingFilter em um aplicativo, você deve adicioná-lo como um filtro de recurso como qualquer @Bean outro. TargetingFilter depende de outro @Bean para ser adicionado ao aplicativo TargetingContextAccessor. O TargetingContextAccessor permite definir o atual TargetingContext a ser usado para definir o ID do usuário e os grupos atuais, 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);
    }

}

Opções de avaliação de direcionamento

Existem opções disponíveis para personalizar como a avaliação de direcionamento é 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

Habilitar a atualização de configuração para suas configurações permite que você extraia seus valores mais recentes do repositório ou repositórios da Configuração de Aplicativos sem precisar reiniciar o aplicativo.

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 disparar atualizações. O valor do gatilho de monitoramento pode ser qualquer valor, desde que seja alterado quando uma atualização for necessária.

Observação

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 disparar uma atualização de configuração, altere o valor de uma chave em seu repositório de configuração. Em seguida, atualize uma das chaves de monitoramento para um novo valor. Essa alteração aciona a criação de um log. Por exemplo, ao alterar o valor de /application/config.message, a seguinte mensagem de log é acionada:

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

Depois que o aplicativo gera o log, ele atualiza todos os @Beans no escopo de atualização.

Observação

Por padrão, @ConfigurationProperties os beans anotados são incluídos nesse escopo.

Atualização baseada em pull

As bibliotecas do Spring da Configuração de Aplicativos dão suporte à capacidade de verificar periodicamente um intervalo de atualização para 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 for aprovado, quando uma tentativa de atualização for feita, todos os gatilhos serão verificados no repositório específico para obter alterações. Qualquer alteração na chave faz com que uma atualização seja iniciada. Como as bibliotecas se integram ao sistema de atualização do Spring, qualquer atualização recarrega todas as configurações de todas as lojas. Você pode definir o intervalo de atualização para qualquer intervalo maior que 1 segundo. As unidades com suporte para o intervalo de atualização são s, m, he d para 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 uma atualização sempre que uma solicitação de servlet ocorre, especificamente ServletRequestHandledEvent. A maneira mais comum de esse evento ser enviado é por solicitações para endpoints em um @RestController.

Manual

Em aplicativos que usam apenas spring-cloud-azure-appconfiguration-config, como aplicativos de console, você pode disparar manualmente uma atualização chamando o método AppConfigurationRefresh de refreshConfiguration. AppConfigurationRefresh é um @Bean que você pode injetar em qualquer @Component.

Além disso, como a biblioteca usa o sistema de configuração do Spring, disparar uma atualização causa uma atualização de todas as configurações, não apenas uma recarga das do repositório de Configuração de Aplicativos do Azure.

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

Observação

Esse método não é mais recomendado, mas atualmente ainda tem suporte.

Você pode configurar a spring-cloud-azure-appconfiguration-config-web biblioteca para receber notificações por push do repositório de Configuração de Aplicativos do Azure para atualizar seus valores de configuração. Você pode configurar essa configuração por meio de um Web Hook da Grade de Eventos do Azure, que pode ser configurado para enviar notificações de alterações para chaves especificadas. Ao adicionar a biblioteca do Spring Actuator como uma dependência, você pode expor os pontos de extremidade de atualização da Configuração de Aplicativo. Há dois pontos de extremidade diferentes: appconfiguration-refresh e appconfiguration-refresh-bus. Esses pontos de extremidade funcionam de forma semelhante aos seus equivalentes refresh e refresh-bus, em que 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 Web Hook porque eles exigem uma resposta na instalação.

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

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

Além de expor os pontos de extremidade 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]

Configurar web hooks

Para configurar um web hook, abra o repositório da Configuração de Aplicativos do Azure e abra Eventos no menu de navegação. Em seguida, selecione Assinatura de Evento. Defina o nome do seu evento e selecione o tipo de ponto de extremidade como Web Hook. Selecionar Web Hook faz com que uma opção Endpoint apareça. Selecione Selecionar um ponto de extremidade. Seu endpoint deve ser semelhante ao 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 configuração falhará. A configuração da biblioteca azure-spring-cloud-appconfiguration-web de pontos de extremidade retorna a resposta correta se o repositório de Configuração de Aplicações do Azure estiver configurado para o aplicativo. Esta confirmação pode ser enviada de outras maneiras. Para obter mais informações sobre a entrega de web hook, consulte Entrega de eventos de webhook.

Observação

Essa validação ocorre somente após a criação ou modificação do ponto de extremidade.

É altamente recomendável que você configure filtros porque, caso contrário, uma atualização será 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	Obrigatório	Padrão
spring.cloud.azure.appconfiguration.refresh-interval	A quantidade padrão de tempo entre as atualizações. É um Duration.	Não	nulo

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 Key Vault sejam mantidos atualizados porque a Configuração de Aplicativos 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 Key Vault na Configuração de Aplicativos. Como os certificados precisam ser girados 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.

Atualizar sinalizador de recurso

Se os sinalizadores de recursos e o monitoramento estiverem habilitados, por padrão, o intervalo de atualização para sinalizadores de recursos será definido como 30 segundos. Quando o intervalo de atualização termina, o sistema verifica todos os sinalizadores de recursos no repositório especificado em busca de alterações. Qualquer alteração na chave faz com que uma atualização seja iniciada. Como as bibliotecas se integram ao sistema de atualização do Spring, qualquer atualização recarrega todas as configurações de todas as lojas. Você pode definir o intervalo de atualização para qualquer intervalo maior que 1 segundo. As unidades com suporte para o intervalo de atualização são s, m, he d para 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 do cliente vem com um indicador de integridade que verifica se a conexão com o repositório ou repositórios da Configuração de Aplicativos do Azure está íntegro. Se habilitado para cada loja, ele fornece um dos seguintes valores de status:

• UP - A última conexão foi bem-sucedida.
• DOWN- A última conexão resultou em um código de erro diferente de 200. Esse status pode ser devido a problemas que vão desde credenciais expirando até um problema de serviço. A biblioteca cliente tenta automaticamente se conectar novamente ao armazenamento 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á desabilitado no arquivo de configuração ou a configuração ou as configurações não foram carregadas na inicialização enquanto a fail-fast configuração do repositório foi definida como false.

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

Personalização do cliente

A biblioteca da Configuração de Aplicativos usa o SDK do Azure para Java para se conectar à Configuração de Aplicativos do Azure e ao Azure Key Vault. Duas interfaces ConfigurationClientCustomizer e SecretClientCustomizer, são fornecidas para modificar os clientes. Cada interface tem um método customize que usa seu respectivo construtor junto com o valor String do URI para o qual o cliente está sendo 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 de Aplicativos e ao Key Vault.

Observação

O ConfigurationClientBuilder e SecretClientBuilder já estão configurados para uso quando passados para customize. Todas as alterações nos clientes, incluindo as credenciais e a política de repetição, substituem os padrões já em vigor.

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

}