應用程式設定支援

本文說明 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>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/ 為 的組態會以的默認標籤，除非已設定 Spring Profile，在此情況下，默認卷標 (No Label) 是 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 Configuration 一樣。 如需詳細資訊，請參閱 Spring Boot 檔案中的核心功能或快速入門：使用 Azure 應用程式組態 建立 Java Spring 應用程式。

選取組態

組態會依索引鍵和標籤載入。 根據預設，會載入以金鑰 /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	描述
*	符合任何標籤，包括 \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 Profiles

根據預設， 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中，會載入具有 null 卷標的所有組態，後面接著符合 Spring Profiles 的所有設定。 Spring Profiles 優先於組 null 態，因為它們位於結尾。

在第二個 label-filter中，字串 _local 會附加至 Spring Profiles 的結尾，不過只會附加至最後一個 Spring Profile。

已停用的存放區

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

除了停用存放區之外，您也可以設定如果存放區無法載入，則會停用存放區。 針對此組態，請使用 spring.cloud.azure.appconfiguration.stores[0].fail-fast。 將它設定為 false來停用 時fail-fast，RuntimeException會導致應用程式存放區停用，而且不會載入任何組態。 如果在啟動時停用組態存放區，則不會在重新整理時檢查是否有變更。 此外，如果已更新組態，則不會嘗試從中載入值。

如果在重新整理檢查期間或 RuntimeException 嘗試重載組態時發生錯誤，則重新整理嘗試會在 通過之後 refresh-interval 結束並重試。

驗證

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

連接字串

透過 連接字串 驗證是最簡單的設定形式。 您可以使用下列命令來存取市集的 連接字串：

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 開發人員 CLI 認證
• 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 ID 或 連接字串 連線到您的複本。

Microsoft Entra ID

若要使用 Microsoft Entra ID 連線到您的復本，您需要列出 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 佔位元元和 金鑰保存庫 參考。

預留位置

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

注意

要移除的前置詞符合 值 spring.cloud.azure.appconfiguration.stores[0].selects[0].key-filter。

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 應用程式組態 及其連結庫支持參考儲存在 金鑰保存庫 中的秘密。 在 應用程式組態 中，您可以使用對應至儲存在 金鑰保存庫 中秘密的值來建立索引鍵。 秘密會安全地儲存在 金鑰保存庫 中，但可以和載入之後的任何其他組態一樣存取。

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

注意

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

建立 金鑰保存庫 參考

若要在 Azure 入口網站 中建立 金鑰保存庫 參考，請移至 [組態>總管建立> 金鑰保存庫 參考]。 然後，您可以從您有權存取的任何 金鑰保存庫 選取要參考的秘密。 您也可以從 [輸入] 索引標籤建立任意 金鑰保存庫 參考。在 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 金鑰保存庫。

解決非 金鑰保存庫 秘密

應用程式組態 連結庫提供方法，在本機解析沒有與其相關聯的 金鑰保存庫 秘密。 這個解析是透過來完成。KeyVaultSecretProvider KeyVaultSecretProvider未針對 金鑰保存庫 參考提供 時TokenCredential，會呼叫 。 會提供 金鑰保存庫 參考的 URI，且傳回的值會變成秘密的值。

警告

使用 KeyVaultSecretProvider 會覆寫自動使用系統指派的受控識別。 若要同時使用這兩者，您必須針對需要解析的 URI 使用 KeyVaultCredentialProvider 並傳回 null 。

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 連結庫，以新增更多功能，例如 功能閘道。

您可以使用索引鍵/標籤篩選來啟用功能旗標。 根據預設， 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的功能篩選器，不需要任何設定，因此只需要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
}

注意

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

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

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

和 FeatureManager 之間的FeatureManagerSnapshot唯一差異是 中結果的@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 一些功能篩選條件。 這些功能篩選不會自動新增，但您可以在 中 @Configuration設定它們。

AlwaysOnFilter

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

PercentageFilter

每次使用者提出要求時，評估 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. 個別使用者 Jeff 和 Alicia 會被授與 Beta 的存取權。
2. 另一位使用者 Mark 會要求加入 並包含。
3. Beta 版中包含 20% 稱為 「Ring1」 使用者的群組。
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 getContextAsync(TargetingContext context) {
        context.setUserId("Jeff");
        ArrayList<String> groups = new ArrayList<String>();
        groups.add("Ring0");
        context.setGroups(groups);
    }

}

目標評估選項

選項可用來自定義在指定 TargetingFilter之間執行目標評估的方式。 您可以在建立期間TargetingFilter設定選擇性參數 TargetingEvaluationOptions。

    @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 應用程式組態 存放區重載這些設定。

推送式重新整理

您可以設定連結spring-cloud-azure-appconfiguration-config-web庫以接收來自 Azure 應用程式組態 存放區的推播通知，以重新整理您的組態值。 您可以透過 Azure 事件方格 Web Hook 來設定此組態，您可以設定為將變更通知傳送至指定的金鑰。 藉由將 Spring Agent 連結庫新增為相依性，您可以公開 應用程式組態 的重新整理端點。 有兩個不同的端點： 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 攔截] 會導致 [端點] 選項出現。 選取 [選取端點]。 您的端點看起來應該像下列範例： https://www.myaplication.com/actuator/appconfiguration-refresh?myTokenName=mySecret。

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

注意

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

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

強制用戶端重新整理

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

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

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

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

功能旗標重新整理

如果同時啟用功能旗標和監視，則功能旗標的重新整理間隔預設會設定為 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 金鑰保存庫。 提供兩個介面 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取代為另一個預設值，以針對導向至 應用程式組態 和 金鑰保存庫 的所有流量使用 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();
    }

}