應用程式設定支援

本文說明 Spring Cloud Azure 應用程式組態 連結庫。 此連結庫會從 Azure 應用程式組態服務載入組態和功能旗標。 連結庫會產生 PropertySource 抽象概念，以符合 Spring 環境已經產生的抽象概念，例如環境變數、命令行組態、本機組態檔等等。

Spring 是由 VMware 開發的開放原始碼應用程式架構，可提供簡化的模組化方法來建立 Java 應用程式。 Spring Cloud Azure 是開放原始碼專案，可將 Spring 和 Azure 服務無縫整合。

必要條件

• Azure 訂用帳戶 - 免費建立一個訂用帳戶。
• Java Development Kit （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 應用程式。 要新增相依性，最方便的方式是使用 Spring Boot 起始套件com.azure.spring:spring-cloud-azure-starter-appconfiguration-config。 下列 範例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>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>

下列範例示範使用 應用程式組態 的基本 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);
    }
}

在此範例中， application.properties 檔案包含下列行：

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

CONFIG_STORE_ENDPOINT 是環境變數，其端點 URL 位於 Azure App Configuration 存放區。

注意

Microsoft 建議您使用最安全的可用驗證流程。 此程式中所述的驗證流程，例如資料庫、快取、傳訊或 AI 服務，在應用程式中需要高度的信任，而且不會在其他流程中帶來風險。 只有在更安全的選項（如用於無密碼或無密鑰連線的受控識別）不可行的情況下，才能使用此流程。 針對本機計算機作業，偏好使用無密碼或無密鑰連線的使用者身分識別。

預設情況下，如果未設定任何組態，則開頭為 /application/ 的組態將會以默認標籤 (No Label) 載入，除非已設定 Spring Profile，在此情況下，默認標籤將會是您的 Spring Profile。

建立名為 /application/https://<name-of-your-store>.azconfig.io/ 的屬性來源，其中包含該存放區的屬性。 要求中使用的標籤會附加至名稱的結尾。 如果未設定標籤，字元 \0 會以空白空間呈現。

載入組態

連結庫支援載入一或多個 應用程式組態 存放區。 如果金鑰在多個商店之間重複，則最後一個金鑰獲勝。

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

在此範例中，如果兩個存放區具有相同的組態金鑰，則第二個存放區中的組態具有最高優先順序。

注意

您可以使用 Azure 應用程式組態 設定，就像任何其他 Spring Configuration 一樣。 如需詳細資訊，請參閱 Spring Boot 檔中 的核心功能 或 快速入門：使用 Azure 應用程式組態建立 Java Spring 應用程式。

選取組態

程式庫會使用其索引鍵和標籤載入組態。 根據預設，會載入以金鑰 /application/ 開頭的組態。 預設標籤是 \0，其顯示方式 (No Label) 為 Azure 入口網站。 如果已設定彈簧設定檔，且未提供任何標籤，則預設標籤是您的彈匣設定檔，即 ${spring.profiles.active}。

您可以選取不同的索引鍵和標籤篩選器來設定載入的組態：

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 支援下列篩選：

標籤	描述
*	符合任何標籤，包括 \0。
\0	如 Azure 入口網站中所示，比對 null 標籤，該標籤在 Azure 入口網站中顯示為 (No Label)。
1.0.0	完全符合標籤 1.0.0。
1.0.*	符合以 1.0.* 開頭的標籤。
,1.0.0	符合標籤 null 和 1.0.0。 限制為五個逗號分隔值。

如果您將 YAML 與標籤篩選器搭配使用，而且您想要載入沒有標籤的組態，以及具有其他標籤的更多組態，則必須包含空白 ,的 。 例如， ,dev 相符項 \0 和 dev。 在此情況下，請以單引號括住標籤篩選器。 此值可讓您先載入沒有標籤的組態，然後在相同的篩選器中載入具有特定標籤的組態：

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

注意

您無法在篩選中與 * 合併,。 在此情況下，您必須使用額外的選取值。

當您 * 在標籤篩選器中使用，並載入具有相同索引鍵的多個組態時，它們會依字母順序載入，並使用最後依字母順序排列的標籤。

彈簧型材

根據預設， spring.profiles.active 會設定為所有選取組態的預設值 label-filter 。 您可以使用 label-filter 來覆寫這項功能。 您可以透過在label-filter中使用${spring.profiles.active}來使用Spring Profiles，如下列範例所示：

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中，程式庫會先載入所有具有標籤的 \0 組態，然後載入符合 Spring 設定檔的所有組態。 Spring Profiles 的優先級高於 \0 的配置，因為它們放在最後。

在第二個 label-filter中，字串 _local 會附加到 Spring 設定檔的結尾，但如果有多個 Spring 設定檔，則只會附加到最後一個 Spring 設定檔。

停用的商店

使用 組態 spring.cloud.azure.appconfiguration.enabled，您可以停用所有組態存放區的載入。 透過設定 spring.cloud.azure.appconfiguration.stores[0].enabled ，您可以停用個別存放區。

注意

如果您使用健康指標，您仍然會看到您的商店列表，但其值為 NOT LOADED。 當您檢查載入的內容來源時，您仍會看到它們列出，但它們不包含任何值。 這種行為是由於spring.config.import屬性的設定所引起的。 如果未設定 azureAppConfiguration，則spring.config.import不會顯示任何值。

驗證

連結庫支援 Azure 身分識別連結庫支援的所有形式的身分識別。 您可以透過 連接字串和受控識別的設定來進行驗證。

注意

Microsoft 建議您使用最安全的可用驗證流程。 此程式中所述的驗證流程，例如資料庫、快取、傳訊或 AI 服務，在應用程式中需要高度的信任，而且不會在其他流程中帶來風險。 只有在更安全的選項（如用於無密碼或無密鑰連線的受控識別）不可行的情況下，才能使用此流程。 針對本機計算機作業，偏好使用無密碼或無密鑰連線的使用者身分識別。

連接字串（不推薦）

透過連接字串進行驗證是最簡單的設定形式，但不建議這樣做。 您可以使用下列命令來存取商店的 連接字串：

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 進行驗證。

您需要指派用來讀取組態的身分識別。 您可以使用下列命令來建立此指派：

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 修改， ConfigurationClientBuilder 使用不同的方法。

注意

Microsoft 建議您使用最安全的可用驗證流程。 此程式中所述的驗證流程，例如資料庫、快取、傳訊或 AI 服務，在應用程式中需要高度的信任，而且不會在其他流程中帶來風險。 只有在更安全的選項（如用於無密碼或無密鑰連線的受控識別）不可行的情況下，才能使用此流程。 針對本機計算機作業，偏好使用無密碼或無密鑰連線的使用者身分識別。

地理複寫

程式庫支援 Azure 應用程式設定的異地復寫功能。 此功能可讓您將資料復寫至其他位置。 這項功能適用於高可用性和災害復原。

您建立的每一個副本都有專用端點。 如果您的應用程式位於多個地理位置，您可以在位置更新應用程式的每個部署，以聯機到離該位置更接近該位置的複本，這有助於將應用程式與 應用程式組態 之間的網路等待時間降到最低。 由於每個復本都有其個別的要求配額，因此此設定也可協助應用程式的延展性，同時其成長為多區域分散式服務。

依預設，程式庫會自動探索配置存放區存在的所有抄本。 當向提供的存放區提出要求但失敗時，程式庫會自動針對可用的複本重試要求。

如果檔案庫觀察到下列任何條件，則可能會發生失效接手：

• 從端點接收服務不可用狀態碼（HTTP 500 或以上）的回應。
• 遇到網路連線問題。
• 請求被限制 (HTTP 狀態碼 429)。

在提供的存放區重新上線之後，程式庫會自動針對提供的存放區重試要求。

如果您想要控制容錯移轉行為，您可以手動提供要用於容錯移轉的存放區清單。

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].connection-strings[0]=[your primary store connection string]
spring.cloud.azure.appconfiguration.stores[0].connection-strings[1]=[your replica store connection string]

如果所有提供的複本端點都失敗，程式庫會嘗試連線到主要存放區的自動探索複本。

您可以使用設定 spring.cloud.azure.appconfiguration.stores[0].replica-discovery-enabled=false停用複寫。

使用異地復寫建立組態存放區

若要建立組態存放區的複本，您可以使用 Azure CLI 或 Azure 入口網站。 下列範例會使用 Azure CLI 在美國東部 2 區域中建立複本：

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

關鍵價值

Azure 應用程式組態 支援多種索引鍵值類型，其中有些有內建的特殊功能。 Azure 應用程式設定內建支援 JSON 內容類型、Spring 占位符和 Key Vault 參考。

預留位置

函式庫支援具有 ${} 格式環境佔位符的設定。 使用佔位元參考 Azure 應用程式組態 索引鍵時，請從參考中移除前置詞。 例如， /application/config.message 參考為 ${config.message}。

注意

要移除的前置詞符合 值 spring.cloud.azure.appconfiguration.stores[0].selects[0].key-filter。 您可以透過設定 的 spring.cloud.azure.appconfiguration.stores[0].trim-key-prefix[0]值來變更要修剪的字首。

JSON

具有內容類型 application/json 的組態會當做 JSON 對象處理。 這項功能可讓您將一個組態對應至 內的 @ConfigurationProperties複雜物件。 例如，請考慮具有下列值的 JSON 金鑰 /application/config.colors ：

{
 "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 中保持安全，但您可以在載入應用程式時，以與任何其他設定相同的方式存取它們。

您的應用程式會使用用戶端提供者來擷取 金鑰保存庫 參考，就像針對儲存在 應用程式組態 中的任何其他密鑰一樣。 因為用戶端會將索引鍵辨識為 金鑰保存庫 參考，所以它們具有唯一的內容類型，而用戶端會連線到 金鑰保存庫 來為您擷取其值。

注意

金鑰保存庫 只允許一次擷取秘密，因此儲存在 應用程式組態 中的每個 金鑰保存庫 參考都會對 金鑰保存庫 產生提取。

建立 金鑰保存庫 參考

您可以在 Azure 入口網站中，依序前往 組態瀏覽器，然後點選>並選擇Key Vault 參考，以建立 Key Vault 參考。 然後，您可以從您有權存取的任何 金鑰保存庫 選取要參考的秘密。 您也可以從 [ 輸入 ] 索引標籤建立任意的 Key Vault 參考。在 Azure 入口網站中，輸入有效的 URI。

您也可以使用下列命令，透過 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?}，其中版本區段是可選的。

使用 金鑰保存庫 參考

您可以使用 Spring Cloud Azure 設定 來配置程式庫。 您可以使用用來連線到 應用程式組態 的相同認證來連線到 Azure 金鑰保存庫。

您也可以建立與 SecretClientCustomizer 建立相同的 ConfigurationClientCustomizer 方式，以提供您自己的驗證方法。

解決非 金鑰保存庫 秘密

應用程式設定程式庫提供覆寫金鑰保存庫參考解析的方法。 例如，您可以使用它來在本機解析開發環境中的秘密。 這個解析是透過KeyVaultSecretProvider來完成的。 KeyVaultSecretProvider如果提供，則會在每個金鑰保存庫參考上呼叫。 如果傳回非 Null 值，則 getSecret 會將其用作秘密值。 否則，金鑰保存庫參考會正常解析。

public class MySecretProvider implements KeyVaultSecretProvider {

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

}

功能管理

功能管理為 Spring Boot 應用程式提供動態存取內容的方式。 功能管理具有各種功能，例如下列功能：

• 可啟用或停用內容的功能旗標
• 顯示內容時的目標功能篩選
• 自定義功能篩選
• 動態啟用端點的功能閘道

您可以透過下列設定來啟用功能旗標：

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

已啟用的功能旗標會載入具有前置詞 feature-management的 Spring 組態系統中。 您也可以在本機組態檔中註冊功能旗標。 如需詳細資訊，請參閱 功能旗標宣告 一節。

使用功能管理最簡單的方式是使用 spring-cloud-azure-feature-management 和 spring-cloud-azure-feature-management-web 連結庫。 這兩個連結庫之間的差異在於相 spring-cloud-azure-feature-management-web 依於 spring-web 和 spring-webmvc 連結庫，以新增更多功能，例如 功能閘道。

依預設，會載入所有具有 \0 標籤 （視為 (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 或 application.properties 作為功能旗標的來源。 以下是用來在 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

此範例具有下列功能旗標：

• feature-t 設定為 false。 此設定一律會傳回功能旗標的值。
• feature-u 與功能篩選搭配使用。 這些篩選條件定義於 enabled-for 屬性底下。 在此情況下， feature-u 有一個稱為 Random的功能篩選器，不需要任何設定，因此只需要name屬性。
• 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 中快取先前評估過的功能旗標狀態，以確保所有請求都返回相同的值。 此外，Web 連結庫也提供 @FeatureGate，它可以封鎖或將 Web 要求重新導向至不同的端點。

功能旗標檢查

FeatureManager @Bean是可以@Autowired或插入@Component型別物件的 。 FeatureManager 具有方法 isEnabled ，當傳遞功能旗標的名稱時，會傳回其狀態。

@Autowired
FeatureManager featureManager;

...

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

注意

FeatureManager也有稱為isEnabled的isEnabledAsync異步版本。

如果沒有功能管理設定，或當功能旗標不存在時， isEnabled 一律會傳回 false。 如果現有的功能旗標已設定為未知的功能篩選器，則會拋出 FilterNotFoundException。 您可以藉由將false設定為fail-fast來變更此行為並傳回false。 下表描述 fail-fast：

名稱	描述	必填	預設
spring.cloud.azure.feature.management.fail-fast	發生例外狀況時會擲出 RuntimeException。 如果此屬性設定為 false，則會 isEnabled 改為傳 false 回 。	否	true

與FeatureManagerSnapshot和FeatureManager之間的唯一差異是@RequestScope中的結果快取。

功能閘道

使用功能管理 Web 連結庫，您可以要求啟用指定的功能，才能執行端點。 您可以使用 註解來設定此需求 @FeatureGate ，如下列範例所示：

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

只有在啟用 「feature-t」 時，您才能存取 featureT 端點。

已停用的動作處理

當端點因為指定的功能已停用而遭到封鎖時， 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套件隨附一些過濾功能。 這些功能篩選器會自動新增。

AlwaysOnFilter （永遠在線篩檢程式）

此篩選一律會傳 true回 。 如需使用範例，請參閱 功能旗標宣告 一節。

百分比過濾器

每次檢查時，的 PercentageFilter 評估都會傳回不同的結果。 您可以使用 來規避此不一致 FeatureManagementSnapshot，它會快取每個要求的功能旗標結果。

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

時間窗過濾器

此篩選提供根據時間範圍啟用功能的功能。 如果您只指定End ，則該功能會在指定時間前保持開啟。 如果您只 Start指定 ，則會在該時間之後的所有時間點將功能視為開啟。 如果您同時指定這兩項，此功能會在兩次之間視為有效。

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"

此篩選器也支援週期性時間範圍篩選器。 它支援每日和每週重複，以及到期時間。

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

這種重複模式每週一和週三的 00：00：00 GMT 至 12：00：00 GMT 都會發生，並且不會過期。

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"

這種重複模式每隔一天發生一次，從 00：00：00 GMT 到 12：00：00 GMT，直到結束日期。

目標篩選器

此篩選提供為目標對象啟用功能的功能。 如需目標的深入說明，請參閱 目標一節 。 篩選參數包含物件物件，描述使用者、群組，以及應該具有功能存取權之使用者基底的預設百分比。 針對目標物件中列出的每個群組物件，需要一個百分比來定義該群組成員可存取此功能的百分比。 在下列情況下，使用者已啟用此功能：

• 使用者直接在用戶的 區段中指定。
• 用戶位於任何群組推出中所包含的百分比範圍內。
• 用戶屬於預設首度發行百分比。

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

自定義功能篩選

建立自訂功能篩選可讓您根據您定義的準則來啟用功能。 若要建立自定義功能篩選器，您必須實作 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，也就是 Map<String, Object>。

目標設定

目標是功能管理策略，可讓開發人員逐漸向使用者群推出新功能。 此策略是建立在以一組稱為目標「對象」的使用者為目標的概念之上。 受眾是由特定使用者、群組和整個用戶群的指定百分比組成。 在觀眾中所包含的群組，可以進一步按各群組成員的比例進行細分。

下列步驟示範新 'Beta' 功能的漸進式推出範例：

1. 個別使用者 Jeff 和 Alicia 會被授與 Beta 的存取權。
2. 另一位使用者 Mark 要求加入並包含在內。
3. 在 Beta 中包含了一個名為「Ring1」使用者群組的 20%。
4. Beta 中包含的「Ring1」使用者數目高達 100%。
5. Beta 中包含 5% 的使用者群。
6. 部署百分比增加到 100%，且功能已完全部署完成。

此功能推出的策略是透過包含 TargetingFilter 的功能篩選器內建於程式庫中。

應用程式中的目標設定

範例 專案中提供使用目標功能篩選的範例 Web 應用程式。

若要開始在應用程式中使用 TargetingFilter ，您必須將其新增為 @Bean 與任何其他功能篩選條件一樣。 TargetingFilter 依賴另一個 @Bean 被加入到應用程式 TargetingContextAccessor。 TargetingContextAccessor可以用來定義目前欲使用的 TargetingContext，以設置使用者識別碼和群組，如下列範例所示：

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

}

目標評估選項

選項可用來自定義如何在指定的 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]

在應用程式產生記錄檔後，它會重新整理範圍內的所有@Bean。

注意

根據預設， @ConfigurationProperties 批注的豆類會包含在此範圍中。

拉動刷新

應用程式配置的 Spring 庫支持定期在重新整理間隔檢查監控觸發器進行的變更。 根據預設，重新整理間隔會設定為30秒。 重新整理間隔過去之後，當嘗試重新整理時，會在指定的存放區中檢查所有觸發程式是否有變更。 金鑰的任何變更都會觸發更新。 由於連結庫會與 Spring refresh 系統整合，因此任何重新整理都會重載所有存放區的所有組態。 您可以將重新整理間隔設定為超過 1 秒的任何間隔。 重新整理間隔的支持單位分別為 s、 m、 h和 d 秒、分鐘、小時和天。 下列範例會將重新整理間隔設定為 5 分鐘：

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

自動化

當您使用 spring-cloud-azure-appconfiguration-config-web 程式庫時，每當發生 servlet 請求時，應用程式都會自動檢查是否需要重新整理，特別是 ServletRequestHandledEvent。 此事件最常見的傳送方式是透過對 @RestController 端點的請求。

說明書

在僅使用spring-cloud-azure-appconfiguration-config的應用程式中，例如主控台應用程式，您可以透過呼叫AppConfigurationRefresh的refreshConfiguration方法來手動觸發重新整理。 AppConfigurationRefresh 是一個可以注入到任何 @Bean 的 @Component。

此外，由於程式庫使用 Spring 的組態系統，因此觸發重新整理會導致重新整理所有組態，而不只是重新載入 Azure App Configuration 存放區中的組態。

推送式刷新（不建議）

注意

不再建議使用此方法，但目前仍受支援。

您可以設定 spring-cloud-azure-appconfiguration-config-web 程式庫，以接收來自 Azure App Configuration 存放區的推播通知，以重新整理您的組態值。 您可以透過 Azure 事件方格 Web 勾點來設定此設定，您可以設定為傳送指定索引鍵變更的通知。 藉由將 Spring Actuator 程式庫新增為相依性，您可以公開 App Configuration 的重新整理端點。 有兩個不同的端點： appconfiguration-refresh 和 appconfiguration-refresh-bus。 這些端點的運作方式與其對應端refresh和refresh-bus類似，其中，應用程式組態端點會讓重新整理間隔自然到期，而不是在接收時強制觸發重新整理。 您仍然可以使用refresh和refresh-bus，但無法使用 Web Hook 將它們直接連接到 Azure 事件方格，因為它們在設置過程中需要回應。

屬性 appconfiguration-refresh 會使重新整理間隔到期，因此在下一次重新整理檢查之前不會等候剩餘的重新整理間隔。 屬性 appconfiguration-refresh-bus 會將通知傳送到連線的傳訊服務，例如 Azure 服務匯流排，以便所有應用程式執行個體接收重新整理的通知。 在這兩種情況下，它都不會在重新整理間隔時完全過期，但會以少量抖動量關閉。 此抖動可確保應用程式的每個執行個體都不會嘗試同時重新整理。

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]

設定 Web 勾點

若要設定 Web 勾點，請開啟您的 Azure 應用程式組態存放區，然後從導覽功能表開啟 [事件 ]。 然後，選取 事件訂閱。 設定事件的名稱，然後選擇端點類型為 Web Hook。 選取 [Web Hook] 會使 [端點] 選項出現。 選取 [選取端點]。 您的端點看起來應該像下列範例： https://www.myaplication.com/actuator/appconfiguration-refresh?myTokenName=mySecret。

確認 Selection 會將設定通知傳送至指定的 URI，且預期會有回應。 如果未傳回任何回應，安裝程式就會失敗。 azure-spring-cloud-appconfiguration-web如果為應用程式設定了 Azure 應用程式組態 存放區，端點的連結庫設定會傳回正確的回應。 此確認可以透過其他方式傳送。 如需有關 webhook 傳遞的詳細資訊，請參閱 webhook 事件傳遞。

注意

此驗證只會在建立或修改端點時發生。

強烈建議您設定篩選，因為否則會在每次建立和修改密鑰之後觸發重新整理。

強制用戶端重新整理

您可以設定連結庫，以強制重新整理間隔重新整理所有設定。 下表描述 refresh-interval 屬性：

名稱	描述	必填	預設
spring.cloud.azure.appconfiguration.refresh-interval	重新整理之間的標準時間量。 Duration是 。	否	null

使用 spring.cloud.azure.appconfiguration.refresh-interval 重新整理時，不會檢查任何已設定的監看鍵。 此屬性是用來確保 金鑰保存庫 秘密保持最新狀態，因為 Azure 應用程式組態 無法得知何時更新秘密。

由於 Azure Key Vault 會將憑證的公開和私鑰組儲存為秘密，因此您的應用程式可以在應用程式組態中擷取任何憑證作為 Key Vault 參考 。 因為憑證需要定期輪替，用戶端應用程式需要同樣頻繁地更新，這可以使用用戶端重新整理間隔來完成。

功能旗標重新整理

如果同時啟用功能旗標和監視，則功能旗標的重新整理間隔預設會設定為 30 秒。 當重新整理間隔結束時，系統會檢查指定存放區中的所有功能旗標是否有變更。 金鑰的任何變更都會觸發更新。 由於連結庫會與 Spring refresh 系統整合，因此任何重新整理都會重載所有存放區的所有組態。 您可以將重新整理間隔設定為超過 1 秒的任何間隔。 重新整理間隔的支持單位分別為 s、 m、 h和 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來啟用健康情況指標。

用戶端自定義

應用程式組態連結庫會使用 適用於 Java 的 Azure SDK 來連線到 Azure 應用程式組態和 Azure Key Vault。 提供兩個介面 ConfigurationClientCustomizer 和 SecretClientCustomizer，以修改用戶端。 每個介面都有一個 customize 方法，其採用其各自的產生器，以及 String 客戶端設定的 URI 值，如下列介面定義所示：

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

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

這些介面允許自定義 HTTP 用戶端及其設定。 下列範例會將預設值HttpClient取代為另一個預設值，以針對導向至 應用程式組態 和 金鑰保存庫 的所有流量使用 Proxy。

注意

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

}