Java 用Azure App Configuration クライアントライブラリ - バージョン 1.4.10

[アーティクル]
10/21/2023

Azure App Configuration は、開発者がアプリケーション構成を単純かつ安全に一元化するのに役立つマネージドサービスです。

近年のプログラム、特にクラウドで実行されるプログラムは、その性質上、分散されたコンポーネントが多数存在するのが一般的です。これらのコンポーネント全体に構成設定を分散させることは、トラブルシューティングすることの難しいエラーがアプリケーションのデプロイ中に発生する原因となります。 App Configuration を使用すると、アプリケーションのすべての設定を 1 か所に格納して、そのアクセスをセキュリティで保護することができます。

App Configuration用のクライアントライブラリを使用して、アプリケーション構成設定を作成および管理します。

ソースコード | パッケージ (Maven) | API リファレンスドキュメント | 製品ドキュメント | サンプル

作業の開始

前提条件

パッケージをインクルードする

BOM ファイルを含める

ライブラリの一般提供 (GA) バージョンに依存するには、azure-sdk-bom をプロジェクトに含めてください。次のスニペットでは、{bom_version_to_target} プレースホルダーをバージョン番号に置き換えます。 BOM の詳細については、 AZURE SDK BOM README に関するページを参照してください。

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

次に、次に示すようにバージョンタグを使用せずに、依存関係セクションに直接依存関係を含めます。

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-data-appconfiguration</artifactId>
  </dependency>
</dependencies>

直接依存関係を含める

BOM に存在しないライブラリの特定のバージョンに依存する場合は、次のように直接依存関係をプロジェクトに追加します。

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-data-appconfiguration</artifactId>
  <version>1.4.10</version>
</dependency>

App Configuration ストアを作成する

構成ストアを作成するには、Azure Portal または Azure CLI を使用できます。

最初に次のコマンドを実行して Azure App Configuration CLI の拡張機能をインストールする必要があります。

az extension add -n appconfig

その後、構成ストアを作成します。

az appconfig create --name <config-store-name> --resource-group <resource-group-name> --location eastus

クライアントを認証する

App Configuration サービスを操作するには、Configuration Client クラスのインスタンスを作成する必要があります。これを可能にするには、構成ストアの接続文字列が必要です。または、AAD トークンを使用してサービスに接続します。

接続文字列の使用

資格情報の取得

次の Azure CLI スニペットを使用して、構成ストアから接続文字列を取得します。

az appconfig credential list --name <config-store-name>

または、Azure Portal から接続文字列を取得します。

構成クライアントを作成する

接続文字列の値を取得したら、構成クライアントを作成できます。

ConfigurationClient configurationClient = new ConfigurationClientBuilder()
    .connectionString(connectionString)
    .buildClient();

または

ConfigurationAsyncClient configurationClient = new ConfigurationClientBuilder()
    .connectionString(connectionString)
    .buildAsyncClient();

AAD トークンを使用する

ここでは、 DefaultAzureCredential を使用してサービスプリンシパルとして認証する方法を示します。ただし、構成クライアントは任意の azure-identity 資格情報を受け入れます。その他の資格情報の詳細については、 azure-identity のドキュメントを参照してください。

サービスプリンシパルを作成する (省略可能)

この Azure CLI スニペットは、新しいサービスプリンシパルを作成する方法を示しています。使用する前に、"your-application-name" をサービスプリンシパルの適切な名前に置き換えます。

サービスプリンシパルを作成します。

az ad sp create-for-rbac --name http://my-application --skip-assignment

出力:

 {
     "appId": "generated app id",
     "displayName": "my-application",
     "name": "http://my-application",
     "password": "random password",
     "tenant": "tenant id"
 }

出力を使用して 、AZURE_CLIENT_ID (上記の "appId")、AZURE_CLIENT_SECRET (上記 の " パスワード")、および AZURE_TENANT_ID (上記の "テナント" ) 環境変数を設定します。次の例は、Bash でこれを行う方法を示しています。

export AZURE_CLIENT_ID="generated app id"
export AZURE_CLIENT_SECRET="random password"
export AZURE_TENANT_ID="tenant id"

該当するApp Configurationロールの 1 つをサービスプリンシパルに割り当てます。

クライアントの作成

AZURE_CLIENT_ID、AZURE_CLIENT_SECRET、AZURE_TENANT_ID環境変数が設定されると、DefaultAzureCredential は構成クライアントを認証できるようになります。

クライアントを構築するには、構成ストアの URL も必要です。構成ストアの URL は、Azure CLI または Azure Portal から取得できます。 Azure Portal では、URL がサービス "エンドポイント" として一覧表示されます。

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
ConfigurationClient configurationClient = new ConfigurationClientBuilder()
    .credential(credential)
    .endpoint(endpoint)
    .buildClient();

主要な概念

構成設定

構成設定は、構成ストア内の基本的なリソースです。最も単純な形式では、キーと値です。ただし、変更可能なコンテンツタイプやタグフィールドなどの追加のプロパティがあり、値をさまざまな方法で解釈または関連付けることができます。

構成設定の Label プロパティを使用すると、構成設定を異なるディメンションに分割できます。これらのディメンションはユーザー定義であり、任意の形式を使用できます。ラベルに使用するディメンションの一般的な例としては、リージョン、セマンティックバージョン、環境などがあります。多くのアプリケーションには、異なるディメンション間でアプリケーションが存在する場合に、さまざまな値を持つ必要な構成キーのセットがあります。たとえば、MaxRequests は "NorthAmerica" では 100、"WestEurope" では 200 にすることができます。 "NorthAmerica" というラベルを持つ MaxRequests という名前の構成設定を作成し、別の構成設定を "WestEurope" ラベルの別の値でのみ作成することで、この 2 つのディメンションで実行される構成設定をアプリケーションがシームレスに取得できるようにするソリューションを実現できます。

構成クライアント

クライアントは、App Configuration サービスとの対話、構成設定の取得、設定、削除、選択を実行します。非同期、、 ConfigurationAsyncClientおよび同期のクライアントが SDK に存在し、 ConfigurationClientアプリケーションのユースケースに基づいてクライアントを選択できます。

スタートアップ構成を取得する必要があるアプリケーションは、同期クライアント (SQL 接続の設定など) を使用する方が適しています。

ConfigurationClient configurationClient = new ConfigurationClientBuilder()
    .connectionString(connectionString)
    .buildClient();

// urlLabel is optional
String url = configurationClient.getConfigurationSetting(urlKey, urlLabel).getValue();
Connection conn = null;
try {
    conn = DriverManager.getConnection(url);
} catch (SQLException ex) {
    System.out.printf("Failed to get connection using url %s", url);
} finally {
    if (conn != null) {
        try {
            conn.close();
        } catch (SQLException ex) {
            System.out.printf("Failed to close connection, url %s", url);
        }
    }
}

定期的に更新する必要がある構成の大規模なセットを持つアプリケーションは、非同期クライアントを使用する方が適しています。たとえば、特定のラベルを持つすべての設定が定期的に更新されます。

ConfigurationAsyncClient configurationClient = new ConfigurationClientBuilder()
    .connectionString(connectionString)
    .buildAsyncClient();

configurationClient.listConfigurationSettings(new SettingSelector().setLabelFilter(periodicUpdateLabel))
    .subscribe(setting -> updateConfiguration(setting));

例

次のセクションでは、最も一般的な構成サービスタスクの一部をカバーするいくつかのコードスニペットを示します。「機能フラグ」と「シークレットリファレンス」の構成設定については、サンプルを参照してください。

構成クライアントを作成する

を使用して構成クライアントをConfigurationClientBuilder作成し、接続文字列渡します。

ConfigurationClient configurationClient = new ConfigurationClientBuilder()
    .connectionString(connectionString)
    .buildClient();

構成設定を作成する

構成ストアに格納する構成設定を作成します。構成設定を格納するには、次の 2 つの方法があります。

addConfigurationSetting は、設定がストアにまだ存在しない場合にのみ設定を作成します。

ConfigurationSetting setting = configurationClient.addConfigurationSetting("new_key", "new_label", "new_value");

または

setConfigurationSetting は、設定が存在しない場合、または既存の設定をオーバーライドする場合に設定を作成します。

ConfigurationSetting setting = configurationClient.setConfigurationSetting("some_key", "some_label", "some_value");

構成ストアに格納する機能フラグ構成設定または Secrete Reference 構成設定を作成します。

String key = "some_key";
String filterName = "{filter_name}"; // such as "Microsoft.Percentage"
String filterParameterKey = "{filter_parameter_key}"; // "Value"
Object filterParameterValue = 30; // Any value. Could be String, primitive value, or Json Object
FeatureFlagFilter percentageFilter = new FeatureFlagFilter(filterName)
                                         .addParameter(filterParameterKey, filterParameterValue);
FeatureFlagConfigurationSetting featureFlagConfigurationSetting =
    new FeatureFlagConfigurationSetting(key, true)
        .setClientFilters(Arrays.asList(percentageFilter));

FeatureFlagConfigurationSetting setting = (FeatureFlagConfigurationSetting)
    configurationClient.addConfigurationSetting(featureFlagConfigurationSetting);

String key = "{some_key}";
String keyVaultReference = "{key_vault_reference}";

SecretReferenceConfigurationSetting referenceConfigurationSetting =
    new SecretReferenceConfigurationSetting(key, keyVaultReference);

SecretReferenceConfigurationSetting setting = (SecretReferenceConfigurationSetting)
    configurationClient.addConfigurationSetting(referenceConfigurationSetting);

構成設定を取得する

を呼び出 getConfigurationSettingして、以前に格納された構成設定を取得します。

ConfigurationSetting setting = configurationClient.setConfigurationSetting("some_key", "some_label", "some_value");
ConfigurationSetting retrievedSetting = configurationClient.getConfigurationSetting("some_key", "some_label");

条件付き要求の場合、条件付きで構成設定をフェッチする場合は、true に設定 ifChanged します。が true の場合 ifChanged 、構成設定は、指定 settingされたと異なる場合にのみ取得されます。これは、の ETag とサービス内の setting ETag を比較して、それらが同じかどうかを確認することによって決定されます。 ETag が同じでない場合は、構成設定が異なり、その値が取得されます。

ConfigurationSetting setting = configurationClient.setConfigurationSetting("some_key", "some_label", "some_value");
Response<ConfigurationSetting> settingResponse = configurationClient.getConfigurationSettingWithResponse(setting, null, true, Context.NONE);

構成ストアでフィーチャーフラグ構成設定または Secrete Reference 構成設定を取得します。

FeatureFlagConfigurationSetting setting = (FeatureFlagConfigurationSetting)
    configurationClient.getConfigurationSetting(featureFlagConfigurationSetting);

SecretReferenceConfigurationSetting setting = (SecretReferenceConfigurationSetting)
    configurationClient.getConfigurationSetting(referenceConfigurationSetting);

既存の構成設定を更新する

を呼び出 setConfigurationSettingして、既存の構成設定を更新します。

ConfigurationSetting setting = configurationClient.setConfigurationSetting("some_key", "some_label", "some_value");
ConfigurationSetting updatedSetting = configurationClient.setConfigurationSetting("some_key", "some_label", "new_value");

条件付き要求の場合、構成設定を条件付きで更新する場合は、パラメーターを ifUnchanged true に設定します。が true の場合 ifUnchanged 、構成設定は、指定 settingされたと同じ場合にのみ更新されます。これは、の ETag とサービス内の setting ETag を比較して、それらが同じかどうかを確認することによって決定されます。 ETag が同じ場合は、構成設定が同じであり、その値が更新されていることを意味します。

ConfigurationSetting setting = configurationClient.setConfigurationSetting("some_key", "some_label", "some_value");
Response<ConfigurationSetting> settingResponse = configurationClient.setConfigurationSettingWithResponse(setting, true, Context.NONE);

構成ストアの機能フラグ構成設定または Secrete Reference 構成設定を更新します。

FeatureFlagConfigurationSetting setting = (FeatureFlagConfigurationSetting)
    configurationClient.setConfigurationSetting(featureFlagConfigurationSetting);

SecretReferenceConfigurationSetting setting = (SecretReferenceConfigurationSetting)
    configurationClient.setConfigurationSetting(referenceConfigurationSetting);

構成設定を削除する

を呼び出 deleteConfigurationSettingして、既存の構成設定を削除します。

ConfigurationSetting setting = configurationClient.setConfigurationSetting("some_key", "some_label", "some_value");
ConfigurationSetting deletedSetting = configurationClient.deleteConfigurationSetting("some_key", "some_label");

条件付き要求の場合、条件付きで構成設定を削除する場合は、パラメーターを ifUnchanged true に設定します。 When ifUnchanged パラメーターを true に設定します。が true の場合 ifUnchanged 、構成設定は指定 settingされたと同じ場合にのみ削除されます。これは、の ETag とサービス内の setting ETag を比較して、それらが同じかどうかを確認することによって決定されます。 ETag が同じ場合は、構成設定が同じであり、その値が削除されていることを意味します。

ConfigurationSetting setting = configurationClient.setConfigurationSetting("some_key", "some_label", "some_value");
Response<ConfigurationSetting> settingResponse = configurationClient.deleteConfigurationSettingWithResponse(setting, true, Context.NONE);

構成ストアでフィーチャーフラグ構成設定または Secrete Reference 構成設定を削除します。

FeatureFlagConfigurationSetting setting = (FeatureFlagConfigurationSetting)
    configurationClient.deleteConfigurationSetting(featureFlagConfigurationSetting);

SecretReferenceConfigurationSetting setting = (SecretReferenceConfigurationSetting)
    configurationClient.deleteConfigurationSetting(referenceConfigurationSetting);

複数のキーを使用して構成設定を一覧表示する

を呼び出 listConfigurationSettingsして、複数の構成設定を一覧表示します。すべての構成設定とそのフィールドをフェッチする場合は、メソッドに null を SettingSelector 渡します。

String key = "some_key";
String key2 = "new_key";
configurationClient.setConfigurationSetting(key, "some_label", "some_value");
configurationClient.setConfigurationSetting(key2, "new_label", "new_value");
SettingSelector selector = new SettingSelector().setKeyFilter(key + "," + key2);
PagedIterable<ConfigurationSetting> settings = configurationClient.listConfigurationSettings(selector);

複数の構成設定のリビジョンを一覧表示する

を呼び出 listRevisionsして、構成設定のすべてのリビジョンを一覧表示します。

String key = "revisionKey";
configurationClient.setConfigurationSetting(key, "some_label", "some_value");
configurationClient.setConfigurationSetting(key, "new_label", "new_value");
SettingSelector selector = new SettingSelector().setKeyFilter(key);
PagedIterable<ConfigurationSetting> settings = configurationClient.listRevisions(selector);

構成設定を読み取り専用に設定する

構成設定を読み取り専用の状態に設定します。

configurationClient.setConfigurationSetting("some_key", "some_label", "some_value");
ConfigurationSetting setting = configurationClient.setReadOnly("some_key", "some_label", true);

構成設定から読み取り専用をクリアする

構成設定から読み取り専用をクリアします。

ConfigurationSetting setting = configurationClient.setReadOnly("some_key", "some_label", false);

プロキシオプションを使用してクライアントを作成する

プロキシオプションを使用して構成クライアントを作成します。

// Proxy options
final String hostname = "{your-host-name}";
final int port = 447; // your port number

ProxyOptions proxyOptions = new ProxyOptions(ProxyOptions.Type.HTTP,
    new InetSocketAddress(hostname, port));
HttpClient httpClient = new NettyAsyncHttpClientBuilder()
    .proxy(proxyOptions)
    .build();
ConfigurationAsyncClient configurationAsyncClient = new ConfigurationClientBuilder()
    .connectionString("{your_connection_string}")
    .httpClient(httpClient)
    .buildAsyncClient();

トラブルシューティング

全般

この Java クライアントライブラリを使用してApp Configurationと対話すると、サービスによって返されるエラーは、REST API 要求に対して返されるのと同じ HTTP 状態コードに対応します。たとえば、構成ストアに存在しない構成設定を取得しようとすると、 404 を示す Not Foundエラーが返されます。

App Configurationは、パブリック API のオブジェクトを通じてContextカスタマイズされたヘッダーを定義する方法を提供します。

// Add your headers
HttpHeaders headers = new HttpHeaders();
headers.set("my-header1", "my-header1-value");
headers.set("my-header2", "my-header2-value");
headers.set("my-header3", "my-header3-value");
// Call API by passing headers in Context.
configurationClient.addConfigurationSettingWithResponse(
    new ConfigurationSetting().setKey("key").setValue("value"),
    new Context(AddHeadersFromContextPolicy.AZURE_REQUEST_HTTP_HEADERS_KEY, headers));
// Above three HttpHeader will be added in outgoing HttpRequest.

詳細については、「AddHeadersFromContextPolicy」をチェック

既定の HTTP クライアント

すべてのクライアントライブラリでは、Netty HTTP クライアントが既定で使用されます。前述の依存関係を追加すると、Netty HTTP クライアントを使用するようにクライアントライブラリが自動的に構成されます。 HTTP クライアントの構成と変更については、HTTP クライアントの Wiki で詳しく説明されています。

既定の SSL ライブラリ

すべてのクライアントライブラリは、Tomcat ネイティブの Boring SSL ライブラリを既定で使用して、SSL 操作にネイティブレベルのパフォーマンスを実現しています。 Boring SSL ライブラリは、Linux、macOS、Windows のネイティブライブラリを含んだ uber jar であり、JDK 内の既定の SSL 実装よりも優れたパフォーマンスを備えています。依存関係のサイズを縮小する方法など、詳細については、Wiki の「パフォーマンスチューニング」セクションを参照してください。

次の手順

サンプルについては、こちらを参照してください。
クイックスタート: App Configurationを使用して Java Spring アプリを作成する

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。ボットによって提供される手順にそのまま従ってください。この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープンソースの倫理規定を採用しています。詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。

インプレッション数

次の方法で共有

Java 用Azure App Configuration クライアントライブラリ - バージョン 1.4.10

作業の開始

前提条件

パッケージをインクルードする

BOM ファイルを含める

直接依存関係を含める

App Configuration ストアを作成する

クライアントを認証する

接続文字列の使用

資格情報の取得

構成クライアントを作成する

AAD トークンを使用する

サービスプリンシパルを作成する (省略可能)

クライアントの作成

主要な概念

構成設定

構成クライアント

例

構成クライアントを作成する

構成設定を作成する

構成設定を取得する

既存の構成設定を更新する

構成設定を削除する

複数のキーを使用して構成設定を一覧表示する

複数の構成設定のリビジョンを一覧表示する

構成設定を読み取り専用に設定する

構成設定から読み取り専用をクリアする

プロキシオプションを使用してクライアントを作成する

トラブルシューティング

全般

既定の HTTP クライアント

既定の SSL ライブラリ

次の手順

共同作成

フィードバック

その他のリソース

次の方法で共有

Java 用Azure App Configuration クライアント ライブラリ - バージョン 1.4.10

作業の開始

前提条件

パッケージをインクルードする

BOM ファイルを含める

直接依存関係を含める

App Configuration ストアを作成する

クライアントを認証する

接続文字列の使用

資格情報の取得

構成クライアントを作成する

AAD トークンを使用する

サービス プリンシパルを作成する (省略可能)

クライアントの作成

主要な概念

構成設定

構成クライアント

例

構成クライアントを作成する

構成設定を作成する

構成設定を取得する

既存の構成設定を更新する

構成設定を削除する

複数のキーを使用して構成設定を一覧表示する

複数の構成設定のリビジョンを一覧表示する

構成設定を読み取り専用に設定する

構成設定から読み取り専用をクリアする

プロキシ オプションを使用してクライアントを作成する

トラブルシューティング

全般

既定の HTTP クライアント

既定の SSL ライブラリ

次の手順

共同作成

フィードバック

その他のリソース

Java 用Azure App Configuration クライアントライブラリ - バージョン 1.4.10

サービスプリンシパルを作成する (省略可能)

プロキシオプションを使用してクライアントを作成する