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 seu repositório da 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>5.19.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 bootstrap.properties contém a seguinte linha:

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

CONFIG_STORE_CONNECTION_STRING é uma variável de ambiente com a cadeia de conexão para o Repositório de Configuração de Aplicativos do Azure. Você pode acessar sua cadeia de conexão usando o seguinte comando:

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

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 perfil de mola seja definido, caso em que o rótulo padrão é seu perfil de mola. Como o repositório está vazio, nenhuma configuração é carregada, mas a Origem da Propriedade da Configuração de Aplicativos do Azure ainda é gerada.

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, carregar todos os repositórios resulta no carregamento da configuração de repositórios de prioridade mais alta. O último vence. Esse processo é ilustrado no exemplo a seguir:

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

No exemplo, se o primeiro e o segundo repositórios tiverem a mesma configuração, a configuração no segundo repositório terá a prioridade mais alta e o último vencerá.

Selecionando configurações

As configurações são carregadas por 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 é ${spring.profiles.active}. Se ${spring.profiles.active} não estiver definido, as configurações com o null rótulo serão carregadas. O null rótulo aparece como (No Label) no portal do Azure.

Você pode definir as configurações carregadas selecionando diferentes filtros de chave e rótulo, conforme mostrado no exemplo a seguir:

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:

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

Se você estiver usando YAML com filtros de rótulo e precisar começar com null, o filtro de rótulo precisará ser cercado por aspas simples, conforme mostrado no exemplo a seguir:

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

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-filtero . Você pode usar os perfis de mola label-filter no ${spring.profiles.active}usando , 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, todas as configurações com o null rótulo são carregadas, seguidas por todas as configurações que correspondem aos perfis de mola. Os perfis Spring têm prioridade sobre as null configurações, porque estão no final.

No segundo label-filter, a string _local é anexada ao final dos perfis de mola, embora apenas ao último perfil de mola.

Lojas desativadas

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.

Além de desabilitar repositórios, você pode configurar repositórios para serem desativados se eles não forem carregados. Para essa configuração, use spring.cloud.azure.appconfiguration.stores[0].fail-fast. Quando fail-fast é desabilitado definindo-o como false, a RuntimeException resulta na desativação do repositório de aplicativos sem nenhuma configuração de carregamento. Se um repositório de configuração estiver desabilitado na inicialização, ele não será verificado quanto a alterações na atualização. Além disso, não há nenhuma tentativa de carregar valores dele se as configurações forem atualizadas.

Se ocorrer um erro que resulte em um RuntimeException durante uma verificação de atualização ou durante a tentativa de recarregar as configurações, a tentativa de atualização será encerrada e tentada novamente após a refresh-interval passagem.

Autenticação

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

Cadeia de conexão

A autenticação por meio da cadeia de conexão é a forma mais simples de configurar. 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. É 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 clientes usa o DefaultAzureCredential para autenticar. O usa DefaultAzureCredential os seguintes métodos para autenticar:

• Credencial de ambiente
• Credencial de identidade gerenciada
• Credencial da CLI do Desenvolvedor do Azure
• Credencial do IntelliJ
• Credencial da CLI do Azure
• Credencial do Azure PowerShell

Você precisa atribuir uma identidade, como uma identidade atribuída pelo sistema, 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>

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.

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 limitadas (código de status HTTP 429).

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]

Usando a réplica do repositório de configuração

Depois de criar uma réplica, você pode usá-la em seu aplicativo. Assim como o repositório de origem, você pode se conectar à réplica usando a ID do Microsoft Entra ou uma cadeia de conexão.

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

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

Valores da chave

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. A Configuração de Aplicativos 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 ${}espaços reservados de ambiente no estilo -style. Ao fazer referência a uma chave da Configuração de Aplicativos do Azure com um espaço reservado, remova os prefixos da referência. Por exemplo, /application/config.message é referenciado como ${config.message}.

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 são armazenados com segurança no Key Vault, mas podem ser acessados da mesma forma que qualquer outra configuração depois de carregados.

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

Criando referências do Key Vault

Você pode criar uma referência do Key Vault no portal do Azure acessando Configuration Explorer>Create>Key Vault reference. 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.

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

A biblioteca da Configuração de Aplicativos fornece um método para resolver localmente segredos que não têm um Key Vault associado a eles. Esta resolução é feita através do KeyVaultSecretProvider. O KeyVaultSecretProvider é chamado quando a TokenCredential não é fornecido para uma referência do Key Vault. O URI da referência do Key Vault é fornecido e o valor retornado se torna o valor do segredo.

public class MySecretProvider implements KeyVaultSecretProvider {

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

}

Gerenciamento de recursos

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 segmentação quando o conteúdo é exibido
• Filtros de recursos personalizados
• Portas de recursos para habilitar endpoints 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 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 é preciso spring-cloud-azure-feature-management-web uma dependência das spring-web bibliotecas and spring-webmvc para adicionar mais recursos, como portões de recursos.

Você pode habilitar sinalizadores de recursos usando filtros de chave/rótulo. Por padrão, um null rótulo, visto como (No Label), é atribuído. Você pode configurar os sinalizadores de recursos 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 gerenciamento de recursos

Sinalizadores de recurso

Os sinalizadores de recursos são compostos por duas partes: um nome e uma lista de filtros de recursos usados para ativar o recurso. Os sinalizadores de recursos podem ter um estado booleano de ativado/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 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 junto com application.yml ou bootstrap.yml 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-t: false
  feature-u:
    enabled-for:
    - name: Random
  feature-v:
    enabled-for:
    - name: TimeWindowFilter
      parameters:
        Start: "Wed, 01 May 2019 13:59:59 GMT"
        End: "Mon, 01 July 2019 00:00:00 GMT"
  feature-w:
    evaluate: false
    enabled-for:
    - name: AlwaysOnFilter

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 recurso pode receber parâmetros para usar como 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.

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 FeatureManagerde , contains 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 da Web para diferentes pontos de extremidade.

Verificação do sinalizador de recurso

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

Se você não configurou o gerenciamento de recursos ou 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, a FilterNotFoundException será lançado. Você pode alterar esse comportamento para retornar false configurando fail-fast para false. A tabela a seguir descreve fail-fast:

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

Portão de recursos

Com a biblioteca da Web de gerenciamento de recursos, você pode exigir que um determinado recurso esteja habilitado para executar um ponto de extremidade. 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 se " featureT feature-t" estiver ativado.

Tratamento de ação desabilitado

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 recursos de aplicativo que são restritos 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

Existem alguns filtros de recursos que acompanham o spring-cloud-azure-feature-management pacote. Esses filtros de recursos não são adicionados automaticamente, mas você pode configurá-los em um @Configuration.

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 um usuário faz uma solicitação, a avaliação de 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 usuário. Esse recurso garante que um usuário tenha uma experiência consistente, mesmo que precise reenviar a solicitação.

feature-management:
  feature-v:
    enabled-for:
    - 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-v:
    enabled-for:
    - name: TimeWindowFilter
      parameters:
        Start: "Wed, 01 May 2019 13:59:59 GMT",
        End: "Mon, 01 July 2019 00:00:00 GMT"

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: 
  target:
    enabled-for:
    - 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 ativado. Se ele 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 recursos são definidos como Spring Beans, portanto, eles 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 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 recurso para esperar parâmetros. Esses parâmetros seriam especificados na configuração do recurso e no código, e seriam acessíveis por meio do FeatureFilterEvaluationContext parâmetro .evaluate FeatureFilterEvaluationContext tem uma propriedade parameters, que é um HashMap<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 recurso 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 getContextAsync(TargetingContext context) {
        context.setUserId("Jeff");
        ArrayList<String> groups = new ArrayList<String>();
        groups.add("Ring0");
        context.setGroups(groups);
    }

}

Opções de avaliação de segmentação

As opções estão 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 é verificado quanto a 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.

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 teclas de inspeção para um novo valor. Essa alteração aciona a criação de um log. Por exemplo, alterar o valor de aciona a seguinte mensagem de /application/config.message log:

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.

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 tiver passado, todos os gatilhos serão verificados no repositório fornecido para alterações. Qualquer alteração na chave faz com que uma atualização seja disparada. 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 se há uma atualização sempre que ocorre uma solicitação de servlet, especificamente ServletRequestHandledEvent. A maneira mais comum de enviar esse evento é por meio de solicitações para pontos de extremidade 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 AppConfigurationRefresho método do refreshConfiguration . AppConfigurationRefresh é um @Bean que você pode injetar em qualquer @Componentarquivo .

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 suas configurações, não apenas um recarregamento das configurações do repositório da Configuração de Aplicativos do Azure.

Atualização baseada em push

Você pode configurar a spring-cloud-azure-appconfiguration-config-web biblioteca para receber notificações por push do repositório da Configuração de Aplicativos do Azure para atualizar seus valores de configuração. Você pode definir 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 em chaves especificadas. Ao adicionar a biblioteca Spring Actuator como uma dependência, você pode expor os pontos de extremidade de atualização da Configuração de Aplicativos. 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 appconfiguration-refresh-bus propriedade envia uma notificação a um serviço de mensagens conectado, como o Barramento de Serviço do Azure, para notificar todas as instâncias de um aplicativo a serem atualizadas. Em ambos os casos, ele não expira completamente no intervalo de atualização, mas está desativado por uma pequena quantidade de jitter. Essa tremulação garante que todas as instâncias do seu aplicativo não tentem ser atualizadas ao mesmo tempo.

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

Além de expor os pontos de extremidade de atualização, um parâmetro de consulta necessário foi adicionado para segurança. Nenhum nome ou valor de token é definido por padrão, mas a configuração de um é necessária 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 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 azure-spring-cloud-appconfiguration-web configuração da biblioteca para pontos de extremidade retornará a resposta correta se o repositório da Configuração de Aplicativos 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 webhooks, consulte Entrega de eventos de webhook.

É 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:

Atualizar com spring.cloud.azure.appconfiguration.refresh-interval não verifica nenhuma tecla de inspeção 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.

Atualização do 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. Depois que o intervalo de atualização tiver passado, todos os sinalizadores de recursos serão verificados no repositório fornecido para alterações. Qualquer alteração na chave faz com que uma atualização seja disparada. 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 de clientes 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á íntegra. 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 de cliente tenta automaticamente se conectar 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á 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 customize método que usa seu respectivo construtor junto com o String valor do URI para o qual o cliente está sendo configurado, conforme mostrado nas seguintes definições de interface:

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

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

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

}