Поддержка конфигурации приложений

В этой статье описывается библиотека Конфигурация приложений Azure Spring Cloud. Эта библиотека загружает конфигурации и флаги компонентов из службы Конфигурация приложений Azure. Библиотека создает PropertySource абстракции для сопоставления абстракций, уже созданных средой Spring, таких как переменные среды, конфигурации командной строки, локальные файлы конфигурации конфигурации и т. д.

Spring — это платформа приложений с открытым кодом, разработанная компанией VMware. Она предлагает упрощенный модульный подход к созданию приложений Java. Spring Cloud Azure — это проект с открытым исходным кодом, который обеспечивает простую интеграцию Spring со службами Azure.

Необходимые компоненты

• Подписка Azure — создайте бесплатную учетную запись.
• Пакет средств разработки Java (JDK) версии 8 или более поздней.
• Apache Maven
• Azure CLI

Настройка хранилища Конфигурация приложений

Чтобы создать хранилище Конфигурация приложений Azure, используйте следующую команду:

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

Эта команда создает новое пустое хранилище конфигурации. Конфигурации можно отправить с помощью следующей команды импорта:

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

Перед загрузкой проверьте конфигурации. Файлы YAML можно отправить, изменив формат на YAML. Поле префикса важно, так как это префикс по умолчанию, загруженный клиентской библиотекой.

Использование библиотеки

Чтобы использовать функцию в приложении, ее можно создать как приложение Spring Boot. Самый удобный способ добавления зависимостей — с помощью начального средства com.azure.spring:spring-cloud-azure-starter-appconfiguration-configSpring Boot. В следующем примере файла pom.xml используется Конфигурация приложений 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.12.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>

Примечание.

Если вы используете Spring Boot 2.x, обязательно установите для нее spring-cloud-azure-dependencies значение 4.18.0. Дополнительные сведения о версии, используемой для этого BOM, см. в статье "Какая версия Spring Cloud Azure должна использоваться".

В следующем примере показано базовое приложение Spring Boot с помощью Конфигурация приложений:

@SpringBootApplication
@RestController
public class Application {

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

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

В этом примере файл bootstrap.properties содержит следующую строку:

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

CONFIG_STORE_CONNECTION_STRING— это переменная среды с строка подключения в хранилище Конфигурация приложений Azure. Доступ к строка подключения можно получить с помощью следующей команды:

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

По умолчанию, если конфигурации не заданы, конфигурации, начиная с /application/ метки по умолчанию, загружаются с меткой (No Label) по умолчанию, если не задан профиль Spring, в этом случае метка по умолчанию — это spring Profile. Так как хранилище пусто, конфигурации не загружаются, но источник свойств Конфигурация приложений Azure по-прежнему создается.

Имя источника /application/https://<name-of-your-store>.azconfig.io/ свойств создается, содержащее свойства этого хранилища. Метка, используемая в запросе, добавляется в конец имени. Если метка не задана, символ \0 присутствует в виде пустого пространства.

Загрузка конфигурации

Библиотека поддерживает загрузку одного или нескольких хранилищ Конфигурация приложений. В ситуации, когда ключ дублируется в нескольких хранилищах, загрузка всех хранилищ приводит к загрузке конфигурации хранилища с наивысшим приоритетом. Последний победит. Этот процесс показан в следующем примере:

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

В примере, если оба первого и второго хранилищ имеют одну и ту же конфигурацию, конфигурация во втором хранилище имеет самый высокий приоритет, а последняя выигрывает.

Примечание.

Вы можете использовать параметры Конфигурация приложений Azure, например любую другую конфигурацию Spring. Дополнительные сведения см. в документации по Spring Boot или кратком руководстве по созданию приложения Java Spring с помощью Конфигурация приложений Azure.

Выбор конфигураций

Конфигурации загружаются по их ключу и меткам. По умолчанию загружаются конфигурации, начинающиеся с ключа /application/ . Метка по умолчанию .${spring.profiles.active} Если ${spring.profiles.active} не задано, загружаются конфигурации с null меткой. Метка null отображается как (No Label) в портал Azure.

Конфигурации, загруженные, можно настроить, выбрав различные фильтры ключей и меток, как показано в следующем примере:

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

Свойство key-filter поддерживает следующие фильтры:

Фильтр ключей	Действие
*	Соответствует любому ключу.
abc	Соответствует ключу с именем abc.
abc*	Соответствует именам ключей, начинающимся с abc.
abc,xyz	Соответствует именам ключей abc или xyz. Ограничено пятью разделенными запятыми значениями.

Свойство label-filter поддерживает следующие фильтры:

Label	Description
*	Соответствует любой метки, включая \0.
\0	Соответствует null меткам, которые отображаются в (No Label) портал Azure.
1.0.0	Точно соответствует метки 1.0.0 .
1.0.*	Соответствует меткам, начинающимся с 1.0.*.
,1.0.0	Соответствует меткам null и 1.0.0. Ограничено пятью разделенными запятыми значениями.

Если вы используете YAML с фильтрами меток, и вам нужно начать с null, то фильтр меток должен быть окружен одними кавычками, как показано в следующем примере:

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

Примечание.

Нельзя сочетать * с , фильтрами. В этом случае необходимо использовать дополнительное значение выбора.

профили Spring,

По умолчанию используется значение по умолчанию spring.profiles.activelabel-filter для всех выбранных конфигураций. Эту функцию можно переопределить с помощью label-filter. Профили Spring можно использовать с label-filter помощью ${spring.profiles.active}, как показано в следующем примере:

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

Во-первых label-filter, все конфигурации с null меткой загружаются, а затем все конфигурации, соответствующие Spring Profiles. Spring Profiles имеют приоритет над null конфигурациями, так как они в конце.

Во-вторых label-filter, строка _local добавляется к концу Spring Profiles, хотя только к последнему профилю Spring.

Отключенные магазины

С помощью конфигурации spring.cloud.azure.appconfiguration.enabledможно отключить загрузку для всех хранилищ конфигураций. spring.cloud.azure.appconfiguration.stores[0].enabled С помощью конфигурации можно отключить отдельное хранилище.

Помимо отключения хранилищ можно настроить отключение хранилищ, если они не загружаются. Для этой конфигурации используйте spring.cloud.azure.appconfiguration.stores[0].fail-fast. Если fail-fast параметр falseRuntimeException отключен, результаты в хранилище приложений отключены без конфигураций из него. Если хранилище конфигурации отключено при запуске, оно не проверка для изменений при обновлении. Кроме того, при обновлении конфигураций нет попытки загрузить значения из него.

Если произошла ошибка RuntimeException во время обновления проверка или при попытке перезагрузить конфигурации, попытка обновления завершается и возвращается после refresh-interval передачи.

Проверка подлинности

Библиотека поддерживает все формы удостоверений, поддерживаемые библиотекой удостоверений Azure. Вы можете выполнить проверку подлинности с помощью конфигурации для строка подключения и управляемого удостоверения.

Connection string

Проверка подлинности с помощью строка подключения является самой простой формой для настройки. Доступ к строка подключения магазина можно получить с помощью следующей команды:

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

Затем свойство можно задать spring.cloud.azure.appconfiguration.stores[0].connection-string для строка подключения. Настоятельно рекомендуется задать строка подключения в локальном файле конфигурации значение заполнителя, которое сопоставляется с переменной среды. Этот подход позволяет избежать добавления строка подключения в управление версиями.

Конфигурация Spring Cloud Azure

Для настройки библиотеки можно использовать конфигурацию Spring Cloud Azure. Для настройки библиотеки можно использовать следующие свойства:

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

Если задана только конечная точка, клиентская библиотека использует DefaultAzureCredential для проверки подлинности. Для DefaultAzureCredential проверки подлинности используются следующие методы:

• Учетные данные среды
• Учетные данные управляемого удостоверения
• Учетные данные интерфейса командной строки разработчика Azure
• Учетные данные для входа с помощью IntelliJ
• Учетные данные для входа с помощью Azure CLI
• Учетные данные Azure PowerShell

Для чтения конфигураций необходимо назначить удостоверение, например назначенное системой удостоверение. Это назначение можно создать с помощью следующей команды:

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>

Примечание.

Вы можете определить только один метод проверки подлинности для каждой конечной точки: строка подключения, назначенное пользователем удостоверение или учетные данные маркера. Если вам нужно смешивать и соответствовать, можно использовать ConfigurationClientCustomizer для изменения хранилищ, использующих другой метод.

Георепликация

Библиотека поддерживает функцию гео реплика Конфигурация приложений Azure. Эта функция позволяет реплика переносить данные в другие расположения. Эта функция полезна для обеспечения высокой доступности и аварийного восстановления.

Каждый реплика, который вы создаете, имеет выделенную конечную точку. Если ваше приложение находится в нескольких геолокациях, вы можете обновить каждое развертывание своего приложения в расположении, чтобы подключиться к реплике, находящейся ближе к этому расположении, что поможет минимизировать задержку в сети между вашим приложением и службой "Конфигурация приложений". Так как каждая реплика имеет отдельную квоту запроса, эта настройка также помогает масштабируемости приложения во время его роста до распределенной службы с несколькими регионами.

Отработка отказа может произойти, если библиотека наблюдает любое из следующих условий:

• Получает ответы с недоступным кодом состояния службы (HTTP 500 или более поздней версии) из конечной точки.
• Возникают проблемы с сетевым подключением.
• Запросы регулируются (код состояния HTTP 429).

Создание хранилища конфигураций с гео-реплика

Чтобы создать реплика хранилища конфигураций, можно использовать Azure CLI или портал Azure. В следующем примере azure CLI используется для создания реплика в регионе "Восточная часть США 2".

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

Использование хранилища конфигураций реплика

После создания реплика его можно использовать в приложении. Как и в хранилище источников, вы можете подключиться к реплика с помощью идентификатора Microsoft Entra или строка подключения.

Microsoft Entra ID

Чтобы использовать идентификатор Microsoft Entra для подключения к реплика, необходимо перечислить endpoints экземпляры хранилища конфигурации, как показано в следующем примере:

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

Вы можете перечислить столько конечных точек, сколько у вас есть реплика. Библиотека пытается подключиться к конечным точкам в том порядке, в который они указаны. Если библиотека не может подключиться к реплика, она пытается выполнить следующую попытку в списке. После прохождения периода времени библиотека пытается повторно подключиться к предпочитаемым конечным точкам.

строка подключения

Чтобы использовать строка подключения для подключения к реплика, необходимо указать connectionStrings экземпляры хранилища конфигурации, как показано в следующем примере:

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]

Вы можете перечислить столько строка подключения, сколько у вас реплика. Библиотека пытается подключиться к строка подключения в том порядке, в который они перечислены. Если библиотека не может подключиться к реплика, она пытается выполнить следующую попытку в списке. После прохождения периода времени библиотека пытается повторно подключиться к предпочитаемым строка подключения.

Значения ключей

Конфигурация приложений Azure поддерживает несколько типов ключевых значений, некоторые из которых имеют специальные функции, встроенные в них. Конфигурация приложений Azure имеет встроенную поддержку типа контента JSON, заполнителей Spring и ссылок Key Vault.

Заполнители

Библиотека поддерживает конфигурации с ${}заполнителями среды стилей. При ссылке на ключ Конфигурация приложений Azure с заполнителем удалите префиксы из ссылки. Например, /application/config.message на нее ссылаются ${config.message}.

Примечание.

Префикс, который удаляется, соответствует значению spring.cloud.azure.appconfiguration.stores[0].selects[0].key-filter.

JSON

Конфигурации с типом application/json контента обрабатываются как объекты JSON. Эта функция позволяет сопоставить одну конфигурацию с сложным объектом внутри @ConfigurationProperties. Например, рассмотрим ключ /application/config.colors JSON со следующим значением:

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

Этот ключ сопоставляется со следующим кодом:

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

    private Map<String, Color> colors;

}

Ссылки на Key Vault

Конфигурация приложений Azure и ее библиотеки поддерживают ссылки на секреты, хранящиеся в Key Vault. В Конфигурация приложений можно создать ключи со значениями, которые сопоставляют с секретами, хранящимися в Key Vault. Секреты безопасно хранятся в Key Vault, но их можно получить так же, как и любая другая конфигурация после загрузки.

Приложение использует поставщика клиента для получения ссылок Key Vault так же, как и для других ключей, хранящихся в Конфигурация приложений. Так как клиент распознает ключи как ссылки на Key Vault, у них есть уникальный тип контента, и клиент подключается к Key Vault, чтобы получить их значения.

Примечание.

Key Vault позволяет получать только один секрет за раз, поэтому каждая ссылка Key Vault, хранящуюся в Конфигурация приложений, приводит к извлечению ключей в Key Vault.

Создание ссылок на Key Vault

Вы можете создать ссылку key Vault в портал Azure, перейдя в раздел "Обозреватель>конфигурации" создать>ссылку Key Vault. Затем можно выбрать секрет для ссылки из любого из хранилищ ключей, к к которых у вас есть доступ. Вы также можете создавать произвольные ссылки Key Vault на вкладке "Входные данные". В портал Azure введите допустимый универсальный код ресурса (URI).

Вы также можете создать ссылку на Key Vault с помощью Azure CLI, выполнив следующую команду:

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

Вы можете создать любой секретный идентификатор с помощью Azure CLI. Идентификаторы секретов просто требуют формата {vault}/{collection}/{name}/{version?} , в котором раздел версии является необязательным.

Использование ссылок на Key Vault

Для настройки библиотеки можно использовать конфигурацию Spring Cloud Azure. Для подключения к Azure Key Vault можно использовать те же учетные данные, которые используются для подключения к Конфигурация приложений.

Разрешение секретов, отличных от Key Vault

Библиотека Конфигурация приложений предоставляет метод локального разрешения секретов, которые не связаны с Key Vault. Это разрешение выполняется с помощью KeyVaultSecretProvider. Вызывается, KeyVaultSecretProvider если TokenCredential ссылка на Key Vault не указана. Предоставляется универсальный код ресурса (URI) ссылки на Key Vault, а возвращаемое значение становится значением секрета.

Предупреждение

Использование KeyVaultSecretProvider переопределяет автоматическое использование управляемого удостоверения, назначаемого системой. Чтобы использовать оба, необходимо использовать KeyVaultCredentialProvider и возвращать null URI, необходимые для разрешения.

public class MySecretProvider implements KeyVaultSecretProvider {

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

}

Управление функциями

Управление функциями позволяет приложениям Spring Boot динамически получать доступ к содержимому. Управление функциями имеет различные функции, такие как следующие:

• Флаги компонентов, которые могут включать или отключать содержимое
• Фильтры компонентов для целевых объектов при отображении содержимого
• Настраиваемые фильтры компонентов
• Шлюзы функций для динамического включения конечных точек

Флаги компонентов можно включить с помощью следующей конфигурации:

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

Флаги компонентов включены загружаются в систему конфигурации Spring с префиксом feature-management. Вы также можете зарегистрировать флаги компонентов в локальном файле конфигурации. Дополнительные сведения см. в разделе объявления флага компонента.

Проще всего использовать управление функциями с помощью spring-cloud-azure-feature-management библиотек и spring-cloud-azure-feature-management-web библиотек. Разница между двумя библиотеками заключается в том, что spring-cloud-azure-feature-management-web требуется зависимость от spring-web библиотек и spring-webmvc библиотек для добавления дополнительных функций, таких как шлюзы функций.

Флаги функций можно включить с помощью фильтров ключей и меток. По умолчанию null назначается метка, как показано (No Label). Вы можете настроить флаги компонентов, загруженные, задав фильтр меток, как показано в следующем примере:

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

Основы управления функциями

Флаги функций

Флаги компонентов состоят из двух частей: имени и списка фильтров компонентов, которые используются для включения функции. Флаги компонентов могут иметь логическое состояние включено или выключено, или у них может быть список фильтров компонентов. Флаги компонентов оценивают фильтры компонентов до тех пор, пока не будет возвращено одно значение true. Если фильтр компонентов не возвращается true, флаг компонента возвращается false.

Фильтры компонентов

Фильтры функций определяют сценарий, в котором должна быть включена функция. Фильтры функций оцениваются синхронно.

Библиотека управления функциями поставляется с четырьмя предопределенными фильтрами: AlwaysOnFilter, PercentageFilter, TimeWindowFilter и TargetingFilter.

Можно создать настраиваемые фильтры функций. Например, можно использовать фильтр функций для предоставления пользовательского интерфейса для клиентов, использующих браузер Microsoft Edge. Вы можете настроить функции в этом фильтре функций, например, чтобы отобразить определенный заголовок для аудитории браузера Microsoft Edge.

Объявление флага функции

Библиотека управления функциями поддерживает Конфигурация приложений Azure вместе с application.yml или bootstrap.yml в качестве источников флагов компонентов. Ниже приведен пример формата, используемого для настройки флагов функций в файле 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

В этом примере имеются следующие флаги функций:

• feature-t задан как false. Этот параметр всегда возвращает значение флага функции.
• feature-u используется с фильтрами компонентов. Эти фильтры определяются в свойстве enabled-for . В этом случае feature-u имеет один фильтр функций, который Randomне требует какой-либо конфигурации, поэтому требуется только свойство имени.
• feature-v указывает фильтр признаков с именем TimeWindowFilter. Этот фильтр функций можно передать параметры для использования в качестве конфигурации. В этом примере параметр TimeWindowFilterпередает время начала и окончания, в течение которого функция активна.
• feature-w используется для AlwaysOnFilterпараметра , который всегда вычисляется true. Поле evaluate используется для остановки оценки фильтров компонентов и приводит к тому, что фильтр компонентов всегда возвращается false.

Оценка флагов компонентов

Библиотека spring-cloud-azure-feature-management предоставляет FeatureManager сведения о том, включен ли флаг компонента. FeatureManagerпредоставляет асинхронный способ проверка состояние флага.

spring-cloud-azure-feature-management-webвместе с предоставлением FeatureManagerсодержит FeatureManagerSnapshot, который кэширует состояние ранее оцененных флагов признаков в @RequestScope том, чтобы гарантировать, что все запросы возвращают одно и то же значение. Кроме того, веб-библиотека предоставляет @FeatureGate, которая может блокировать или перенаправлять веб-запросы на разные конечные точки.

Проверка флага функции

FeatureManager@Bean— это объект, который можно @Autowired внедрить или внедрить в @Component объекты типа. FeatureManager имеет метод isEnabled , который при передаче имени флага компонента возвращает его состояние.

@Autowired
FeatureManager featureManager;

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

Примечание.

FeatureManger также имеет асинхронную версию вызываемого isEnabledisEnabledAsync.

Если вы не настроили управление функциями или флаг компонента не существует, isEnabled всегда возвращается false. Если существующий флаг компонента настроен с помощью фильтра неизвестных компонентов, FilterNotFoundException создается исключение. Это поведение можно изменить, чтобы вернуться false , настроив fail-fast его false. В следующей таблице описано fail-fast:

Имя	Описание	Обязательное поле	По умолчанию.
spring.cloud.azure.feature.management.fail-fast	При возникновении RuntimeException исключения создается исключение. Если для этого свойства задано falseзначение, isEnabledfalse возвращается вместо него.	No	true

Единственное различие между FeatureManagerSnapshot и FeatureManager — кэширование результатов в @RequestScope.

Шлюз компонентов

С помощью веб-библиотеки управления функциями можно требовать, чтобы данная функция была включена для выполнения конечной точки. Это требование можно настроить с помощью заметки @FeatureGate , как показано в следующем примере:

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

Доступ к конечной точке featureT можно получить только в том случае, если включен параметр feature-t.

Обработка отключенных действий

Если конечная точка заблокирована, так как указанная функция отключена, DisabledFeaturesHandler вызывается. По умолчанию возвращается HTTP 404. Это поведение можно переопределить, реализуя DisabledFeaturesHandler, как показано в следующем примере:

@Component
public class MyDisabledFeaturesHandler implements DisabledFeaturesHandler {

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

}

Маршрутизация

Некоторые маршруты могут предоставлять возможности приложений, которые вставляются функциями. Если функция отключена, можно перенаправить эти маршруты в другую конечную точку, как показано в следующем примере:

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

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

Встроенные фильтры функций

Существует несколько фильтров функций, которые входят в spring-cloud-azure-feature-management пакет. Эти фильтры функций не добавляются автоматически, но их можно настроить в @Configuration.

AlwaysOnFilter

Этот фильтр всегда возвращается true. Пример использования см. в разделе объявления флага функции.

ПроцентFilter

Каждый раз, когда пользователь выполняет запрос, оценка PercentageFilter может возвращать другой результат. Это несоответствие можно обойти с помощью FeatureManagementSnapshotкэша результата флага компонента на пользователя. Эта возможность гарантирует, что пользователь имеет согласованный интерфейс, даже если он должен повторно отправить запрос.

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

TimeWindowFilter

Этот фильтр предоставляет возможность включить функцию на основе периода времени. Если указать только Endэту функцию, эта функция рассматривается до этого времени. Если указан только Startэтот параметр, функция рассматривается во всех точках после этого времени. Если указать оба параметра, функция считается допустимой между двумя разами.

feature-management:
  feature-v:
    enabled-for:
    - name: TimeWindowFilter
      parameters:
        Start: "Wed, 01 May 2019 13:59:59 GMT",
        End: "Mon, 01 July 2019 00:00:00 GMT"

TargetingFilter

Этот фильтр предоставляет возможность включить функцию для целевой аудитории. Подробное описание целевого объекта см. в разделе " Целевой раздел". Параметры фильтра включают объект аудитории, описывающий пользователей, групп и процент по умолчанию от пользовательской базы, которая должна иметь доступ к этой функции. Для каждого объекта группы, указанного в целевой аудитории, требуется процент, определяющий процент членов этой группы, имеющих доступ к функции. Пользователь включает функцию в следующих случаях:

• Пользователь указан непосредственно в разделе пользователей.
• Пользователь находится в процентах от любого развертывания группы.
• Пользователь попадает в процент развертывания по умолчанию.

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

Фильтры пользовательских функций

Создание настраиваемого фильтра функций позволяет включить функции на основе заданных критериев. Чтобы создать пользовательский фильтр компонентов, необходимо реализовать FeatureFilter интерфейс. FeatureFilter имеет один метод evaluate. Если компонент указывает, что его можно включить с помощью фильтра компонентов, evaluate вызывается метод. Если evaluate возвращается true, это означает, что эта функция должна быть включена. Если он возвращается false, он продолжает оценивать фильтры функций до тех пор, пока не будет возвращено одно значение true. Если возвращаются все фильтры false, функция отключена.

Фильтры функций определяются как Spring Beans, поэтому они определяются как @Component или определены в объекте @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;
    }

}

Параметризованные фильтры компонентов

Некоторые фильтры функций требуют параметров, чтобы определить, следует ли включить функцию. Например, фильтр функций браузера может включить функцию для определенного набора браузеров. Возможно, вы хотите включить функцию для браузеров Microsoft Edge и Chrome, но не Firefox. Чтобы настроить эту ситуацию, можно разработать фильтр функций для ожидания параметров. Эти параметры будут указаны в конфигурации компонентов и коде и будут доступны через FeatureFilterEvaluationContext параметр evaluate. FeatureFilterEvaluationContext имеет свойство parameters, которое является HashMap<String, Object>.

Таргетинг

Цель — это стратегия управления функциями, которая позволяет разработчикам постепенно развертывать новые функции в своей пользовательской базе. Стратегия основана на концепции целевой аудитории для набора пользователей, известных как целевая аудитория. Аудитория состоит из определенных пользователей, групп и указанного процента всей базы пользователей. Группы, включенные в аудиторию, могут быть разбиты дальше на проценты их общих членов.

Ниже приведен пример прогрессивного развертывания для новой функции Beta:

1. Отдельные пользователи Джефф и Алисия получают доступ к бета-версии.
2. Другой пользователь, Марк, просит принять участие и включен.
3. Двадцать процентов группы, известной как "Ring1", включены в бета-версию.
4. Число пользователей Ring1, включенных в бета-версию, составляет до 100 процентов.
5. Пять процентов пользовательской базы включены в бета-версию.
6. Процент развертывания вырос до 100 процентов, и функция полностью развернута.

Эта стратегия развертывания компонента встроена в библиотеку с помощью фильтра включенных TargetingFilter компонентов.

Назначение в приложении

Пример веб-приложения, использующего фильтр функций целевого объекта, доступен в примере проекта.

Чтобы начать использовать TargetingFilter приложение, необходимо добавить его как любой @Bean другой фильтр компонентов. TargetingFilterиспользуется для добавления в приложение TargetingContextAccessorдругого@Bean. Позволяет TargetingContextAccessor определить текущий идентификатор TargetingContext пользователя и группы, как показано в следующем примере:

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

}

Параметры оценки целевого объекта

Параметры доступны для настройки того, как выполняется оценка целевого объекта в заданном режиме TargetingFilter. При создании можно задать необязательный параметрTargetingEvaluationOptionsTargetingFilter.

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

Обновление конфигурации

Включение обновления конфигурации для конфигураций позволяет извлекать последние значения из хранилища Конфигурация приложений или хранилища без необходимости перезапускать приложение.

Чтобы включить обновление, необходимо включить мониторинг вместе с триггерами мониторинга. Триггер мониторинга — это ключ с необязательной меткой, проверка для изменений значений для активации обновлений. Значение триггера мониторинга может быть любым значением, если оно изменяется при необходимости обновления.

Примечание.

Любая операция, которая изменяет ETag триггера мониторинга, вызывает обновление, например изменение типа контента.

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

Чтобы активировать обновление конфигурации, измените значение ключа в хранилище конфигурации. Затем обновите один из ключей часов до нового значения. Это изменение активирует создание журнала. Например, изменение значения триггеров /application/config.message приводит к следующему сообщению журнала:

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

После создания журнала приложение обновляет все @Beans в область обновления.

Примечание.

По умолчанию @ConfigurationProperties в этот область включены аннотированные бобы.

Обновление на основе вытягивания

Библиотеки Конфигурация приложений Spring поддерживают возможность периодически проверка в интервале обновления для изменений, внесенных в триггеры мониторинга. По умолчанию интервал обновления имеет значение 30 секунд. После прохождения интервала обновления все триггеры проверка в указанном хранилище изменений. Любое изменение ключа приводит к активации обновления. Так как библиотеки интегрируются с системой обновления Spring, все обновления перезагружают все конфигурации из всех хранилищ. Интервал обновления можно задать для любого интервала, превышающего 1 секунду. Поддерживаемые единицы интервала обновления: s, mhи d в секундах, минутах, часах и днях соответственно. В следующем примере интервал обновления устанавливается на 5 минут:

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

Автоматизированный

При использовании spring-cloud-azure-appconfiguration-config-web библиотеки приложение автоматически проверка обновления при каждом возникновении запроса сервлета.ServletRequestHandledEvent Наиболее распространенный способ отправки этого события — запросы к конечным точкам в @RestController.

Руководство

В приложениях, использующих только spring-cloud-azure-appconfiguration-configконсольные приложения, можно вручную активировать обновление, вызвав AppConfigurationRefreshrefreshConfiguration метод. AppConfigurationRefresh — это то, что можно внедрить в любой @Bean@Component.

Кроме того, так как библиотека использует систему конфигурации Spring, активация обновления приводит к обновлению всех конфигураций, а не только перезагрузке из хранилища Конфигурация приложений Azure.

Обновление на основе push-уведомлений

Вы можете настроить библиотеку spring-cloud-azure-appconfiguration-config-web для получения push-уведомлений из хранилища Конфигурация приложений Azure для обновления значений конфигурации. Эту конфигурацию можно настроить с помощью Сетка событий Azure веб-перехватчика, который можно настроить для отправки уведомлений об изменениях в указанные ключи. Добавив библиотеку Spring Actuator в качестве зависимости, вы можете предоставлять конечные точки обновления Конфигурация приложений. Существует две разные конечные точки: appconfiguration-refresh и appconfiguration-refresh-bus. Эти конечные точки работают аналогично их коллегам refresh и refresh-bus, где конечные точки конфигурации приложения истекают интервал обновления вместо принудительного обновления при получении. Вы по-прежнему можете использовать refresh иrefresh-bus, но вы не можете подключить их напрямую к Сетка событий Azure с веб-перехватчиком, так как им требуется ответ в настройке.

Свойство appconfiguration-refresh истекает интервал обновления, поэтому оставшийся интервал обновления не ожидается до следующего обновления проверка. Свойство appconfiguration-refresh-bus отправляет уведомление в подключенную службу обмена сообщениями, например Служебная шина Azure, чтобы уведомить все экземпляры приложения для обновления. В обоих случаях срок действия истекает не полностью в интервале обновления, но отключается небольшим объемом дрожания. Это jitter гарантирует, что каждый экземпляр приложения не пытается одновременно обновляться.

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

Помимо предоставления конечных точек обновления, для обеспечения безопасности добавлен обязательный параметр запроса. По умолчанию имя или значение маркера не задано, но для использования конечных точек требуется установить одно из них, как показано в следующем примере:

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]

Настройка веб-перехватчиков

Чтобы настроить веб-перехватчик, откройте хранилище Конфигурация приложений Azure и откройте события из меню навигации. Затем выберите подписку на события. Задайте имя события и выберите тип конечной точки для веб-перехватчика. Выбор веб-перехватчика приводит к отображению параметра конечной точки . Выберите Выбрать конечную точку. Конечная точка должна выглядеть следующим образом: https://www.myaplication.com/actuator/appconfiguration-refresh?myTokenName=mySecret

Подтвердите, что выбор отправляет уведомление о настройке в указанный универсальный код ресурса (URI) и ожидает ответа. Если ответ не возвращается, программа установки завершается ошибкой. Настройка azure-spring-cloud-appconfiguration-web библиотеки для конечных точек возвращает правильный ответ, если для приложения настроено хранилище Конфигурация приложений Azure. Это подтверждение может быть отправлено другими способами. Дополнительные сведения о доставке веб-перехватчиков см. в разделе "Доставка событий веб-перехватчика".

Примечание.

Эта проверка выполняется только при создании или изменении конечной точки.

Настоятельно рекомендуется настроить фильтры, так как в противном случае обновление активируется после каждого создания и изменения ключа.

Принудительное обновление клиента

Библиотеку можно настроить для принудительного обновления всех конфигураций с интервалом обновления. В следующей таблице описано refresh-interval свойство:

Имя	Описание	Обязательное поле	По умолчанию.
spring.cloud.azure.appconfiguration.refresh-interval	Стандартный период времени между обновлениями. DurationЭто .	No	null

Обновление с spring.cloud.azure.appconfiguration.refresh-interval помощью не проверка каких-либо настроенных ключей часов. Это свойство используется для того, чтобы убедиться, что секреты Key Vault хранятся в актуальном состоянии, так как Конфигурация приложений Azure не могут узнать, когда они обновляются.

Так как Azure Key Vault хранит пару открытого и закрытого ключей сертификата в качестве секрета, приложение может получить любой сертификат в качестве ссылки на Key Vault в Конфигурация приложений. Так как сертификаты должны периодически меняться, клиентские приложения должны обновляться так же часто, что можно сделать с помощью интервала обновления клиента.

Обновление флага компонента

Если флаги компонентов и мониторинг включены, по умолчанию интервал обновления флагов компонентов имеет значение 30 секунд. После прохождения интервала обновления все флаги функций проверка в указанном хранилище изменений. Любое изменение ключа приводит к активации обновления. Так как библиотеки интегрируются с системой обновления Spring, все обновления перезагружают все конфигурации из всех хранилищ. Интервал обновления можно задать для любого интервала, превышающего 1 секунду. Поддерживаемые единицы интервала обновления: s, mhи d в секундах, минутах, часах и днях соответственно. В следующем примере интервал обновления устанавливается на 5 минут:

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

Индикатор работоспособности

Клиентская библиотека поставляется с индикатором работоспособности, который проверка указывает, является ли подключение к хранилищу Конфигурация приложений Azure или хранилищам работоспособно. Если он включен для каждого хранилища, он предоставляет одно из следующих значений состояния:

• UP — последнее подключение успешно выполнено.
• DOWN- Последнее подключение привело к ошибке, отличной от 200. Это состояние может быть вызвано проблемами, начиная от истечения срока действия учетных данных до проблемы со службой. Клиентская библиотека автоматически повторяет попытку подключения к хранилищу через следующий интервал обновления.
• NOT LOADED — хранилище конфигурации отображается в локальном файле конфигурации, но хранилище конфигурации не было загружено из файла при запуске. Хранилище конфигураций отключено в файле конфигурации, а конфигурация или конфигурации не загружены при запуске во время fail-fast настройки falseхранилища.

Индикатор работоспособности можно включить, задав параметр management.health.azure-app-configuration.enabled=true.

Настройка клиента

Библиотека Конфигурация приложений использует пакет SDK Azure для Java для подключения к Конфигурация приложений Azure и Azure Key Vault. Два интерфейса ConfigurationClientCustomizer и SecretClientCustomizerпредоставляются для изменения клиентов. Каждый интерфейс имеет customize метод, который принимает в соответствующих построителях, String а также значение URI клиента настраивается, как показано в следующих определениях интерфейса:

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

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

Эти интерфейсы позволяют настраивать HTTP-клиент и его конфигурации. В следующем примере по умолчанию HttpClient используется прокси-сервер для всего трафика, направленного на Конфигурация приложений и Key Vault.

Примечание.

И ConfigurationClientBuilderSecretClientBuilder уже настроены для использования при передаче customizeв . Все изменения клиентов, включая учетные данные и политику повторных попыток, переопределяют уже существующие.

Эту конфигурацию можно также сделать с помощью конфигурации 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();
    }

}