Freigeben über

Azure App Configuration Clientbibliothek für Java– Version 1.4.10

  • Artikel

Azure App Configuration ist ein verwalteter Dienst, mit dem Entwickler ihre Anwendungskonfigurationen einfach und sicher zentralisieren können.

Moderne Programme, vor allem in einer Cloud ausgeführte Programme, verfügen normalerweise über viele verteilte Komponenten. Das Versehen dieser Komponenten mit Konfigurationseinstellungen kann bei einer Anwendungsbereitstellung zu Fehlern führen, deren Behebung schwierig ist. Mit App Configuration können Sie alle Einstellungen für Ihre Anwendung speichern und den Zugriff darauf an einem zentralen Ort schützen.

Verwenden Sie die Clientbibliothek für App Configuration, um Anwendungskonfigurationseinstellungen zu erstellen und zu verwalten.

Quellcode | Paket (Maven) | API-Referenzdokumentation | Produktdokumentation | Proben

Erste Schritte

Voraussetzungen

Schließen Sie das Paket ein

BOM-Datei einfügen

Fügen Sie azure-sdk-bom in Ihr Projekt ein, um von der Allgemeinverfügbarkeitsversion der Bibliothek abhängig zu sein. Ersetzen Sie im folgenden Codeausschnitt den Platzhalter {bom_version_to_target} durch die Versionsnummer. Weitere Informationen zur BOM finden Sie in der INFODATEI FÜR AZURE SDK-STÜCKLISTEN.

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

und fügen Sie dann die direkte Abhängigkeit wie unten dargestellt ohne das Versionstag in den Abschnitt abhängigkeiten ein.

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

Direkte Abhängigkeiten einfügen

Wenn Sie eine Abhängigkeit von einer bestimmten Version der Bibliothek annehmen möchten, die nicht in der BoM vorhanden ist, fügen Sie die direkte Abhängigkeit wie folgt zu Ihrem Projekt hinzu.

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

Erstellen eines App Configuration Store

Zum Erstellen eines Konfigurationsspeichers können Sie das Azure-Portal oder die Azure CLI verwenden.

Führen Sie zunächst den folgenden Befehl aus, um die CLI-Erweiterung für Azure App Configuration zu installieren:

az extension add -n appconfig

Erstellen Sie anschließend den Konfigurationsspeicher:

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

Authentifizieren des Clients

Um mit dem App Configuration-Dienst zu interagieren, müssen Sie eine instance der Configuration Client-Klasse erstellen. Um dies zu ermöglichen, benötigen Sie die Verbindungszeichenfolge des Konfigurationsspeichers. Alternativ können Sie das AAD-Token verwenden, um eine Verbindung mit dem Dienst herzustellen.

Verbindungszeichenfolge verwenden

Abrufen von Anmeldeinformationen

Verwenden Sie den folgenden Azure CLI-Codeausschnitt, um die Verbindungszeichenfolge aus dem Konfigurationsspeicher abzurufen.

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

Alternativ können Sie die Verbindungszeichenfolge aus dem Azure-Portal abrufen.

Erstellen eines Konfigurationsclients

Sobald Sie den Wert der Verbindungszeichenfolge können Sie den Konfigurationsclient erstellen:

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

oder

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

Verwenden des AAD-Tokens

Hier wird die Verwendung von DefaultAzureCredential zur Authentifizierung als Dienstprinzipal veranschaulicht. Der Konfigurationsclient akzeptiert jedoch alle Azure-Identity-Anmeldeinformationen . Weitere Informationen zu anderen Anmeldeinformationen finden Sie in der Dokumentation zu azure-identity .

Erstellen eines Dienstprinzipals (optional)

Dieser Azure CLI-Codeausschnitt zeigt, wie Sie einen neuen Dienstprinzipal erstellen. Ersetzen Sie vor der Verwendung "Your-application-name" durch den entsprechenden Namen für Ihren Dienstprinzipal.

Erstellen Sie einen Dienstprinzipal:

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

Ausgabe:

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

Verwenden Sie die Ausgabe, um AZURE_CLIENT_ID ("appId" oben), AZURE_CLIENT_SECRET ("Password" oben) und AZURE_TENANT_ID ("Mandant" oben) festzulegen. Das folgende Beispiel zeigt eine Möglichkeit, dies in Bash zu tun:

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

Weisen Sie dem Dienstprinzipal eine der anwendbaren App Configuration Rollen zu.

Erstellen eines Clients

Sobald die AZURE_CLIENT_ID, AZURE_CLIENT_SECRET und AZURE_TENANT_ID Umgebungsvariablen festgelegt sind, kann DefaultAzureCredential den Konfigurationsclient authentifizieren.

Zum Erstellen des Clients ist auch die URL Ihres Konfigurationsspeichers erforderlich, die Sie über die Azure CLI oder das Azure-Portal abrufen können. Im Azure-Portal finden Sie die URL als Dienst "Endpunkt".

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

Wichtige Begriffe

Konfigurationseinstellung

Eine Konfigurationseinstellung ist die grundlegende Ressource in einem Konfigurationsspeicher. In seiner einfachsten Form ist es ein Schlüssel und ein Wert. Es gibt jedoch zusätzliche Eigenschaften, z. B. die änderbaren Inhaltstyp- und Tagsfelder, mit denen der Wert auf unterschiedliche Weise interpretiert oder zugeordnet werden kann.

Die Label-Eigenschaft einer Konfigurationseinstellung bietet eine Möglichkeit, Konfigurationseinstellungen in verschiedene Dimensionen zu trennen. Diese Dimensionen sind benutzerdefinierter Art und können eine beliebige Form annehmen. Einige gängige Beispiele für Dimensionen, die für eine Bezeichnung verwendet werden sollen, sind Regionen, semantische Versionen oder Umgebungen. Viele Anwendungen verfügen über einen erforderlichen Satz von Konfigurationsschlüsseln, die unterschiedliche Werte aufweisen, da die Anwendung in verschiedenen Dimensionen vorhanden ist. Beispielsweise kann MaxRequests in "NorthAmerica" 100 und in "WestEurope" 200 sein. Durch das Erstellen einer Konfigurationseinstellung namens MaxRequests mit der Bezeichnung "NorthAmerica" und einer anderen , nur mit einem anderen Wert, in der Bezeichnung "WestEurope" kann eine Lösung erreicht werden, die es der Anwendung ermöglicht, Konfigurationseinstellungen nahtlos abzurufen, während sie in diesen beiden Dimensionen ausgeführt wird.

Konfigurationsclient

Der Client führt die Interaktionen mit dem App Configuration-Dienst aus, wobei Konfigurationseinstellungen erhalten, festgelegt, gelöscht und ausgewählt werden. Im SDK ist ein asynchroner ConfigurationAsyncClient, und synchroner Client vorhanden, ConfigurationClientder die Auswahl eines Clients basierend auf dem Anwendungsfall einer Anwendung ermöglicht.

Eine Anwendung, die Startkonfigurationen abrufen muss, eignet sich besser für den synchronen Client, z. B. das Einrichten einer SQL-Verbindung.

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

Eine Anwendung, die über einen großen Satz von Konfigurationen verfügt, die sie regelmäßig aktualisieren muss, eignet sich besser für den asynchronen Client, z. B. werden alle Einstellungen mit einer bestimmten Bezeichnung regelmäßig aktualisiert.

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

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

Beispiele

Die folgenden Abschnitte enthalten mehrere Codeausschnitte, die einige der gängigsten Aufgaben des Konfigurationsdiensts abdecken, einschließlich: Für die Konfigurationseinstellungen "Featureflag" und "Geheimnisreferenz" finden Sie weitere Details in den Beispielen .

Erstellen eines Konfigurationsclients

Erstellen Sie mithilfe von ConfigurationClientBuilder einen Konfigurationsclient, indem Sie Verbindungszeichenfolge übergeben.

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

Erstellen einer Konfigurationseinstellung

Erstellen Sie eine Konfigurationseinstellung, die im Konfigurationsspeicher gespeichert werden soll. Es gibt zwei Möglichkeiten, eine Konfigurationseinstellung zu speichern:

  • addConfigurationSetting erstellt eine Einstellung nur, wenn die Einstellung noch nicht im Speicher vorhanden ist.
ConfigurationSetting setting = configurationClient.addConfigurationSetting("new_key", "new_label", "new_value");

oder

  • setConfigurationSetting erstellt eine Einstellung, wenn sie nicht vorhanden ist, oder überschreibt eine vorhandene Einstellung.
ConfigurationSetting setting = configurationClient.setConfigurationSetting("some_key", "some_label", "some_value");

Erstellen Sie eine Featureflagskonfigurationseinstellung oder eine Geheimnisverweiskonfigurationseinstellung, die im Konfigurationsspeicher gespeichert werden soll.

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

Abrufen einer Konfigurationseinstellung

Rufen Sie eine zuvor gespeicherte Konfigurationseinstellung ab, indem Sie aufrufen getConfigurationSetting.

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

Wenn Sie für bedingte Anforderungen eine Konfigurationseinstellung bedingt abrufen möchten, legen Sie auf TRUE fest ifChanged . Wenn ifChanged true ist, wird die Konfigurationseinstellung nur abgerufen, wenn sie sich von der angegebenen settingunterscheidet. Dies wird bestimmt, indem das ETag von setting mit dem im Dienst verglichen wird, um festzustellen, ob sie identisch sind oder nicht. Wenn die ETags nicht identisch sind, bedeutet dies, dass sich die Konfigurationseinstellung unterscheidet und ihr Wert abgerufen wird.

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

Rufen Sie im Konfigurationsspeicher eine Konfigurationseinstellung für das Featureflag oder die Konfigurationseinstellung Geheimnisverweis ab.

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

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

Aktualisieren einer vorhandenen Konfigurationseinstellung

Aktualisieren Sie eine vorhandene Konfigurationseinstellung, indem Sie aufrufen setConfigurationSetting.

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

Wenn Sie für bedingte Anforderungen eine Konfigurationseinstellung bedingt aktualisieren möchten, legen Sie den ifUnchanged Parameter auf true fest. Wenn ifUnchanged true ist, wird die Konfigurationseinstellung nur aktualisiert, wenn sie mit der angegebenen settingidentisch ist. Dies wird bestimmt, indem das ETag von setting mit dem im Dienst verglichen wird, um festzustellen, ob sie identisch sind oder nicht. Wenn das ETag identisch ist, bedeutet dies, dass die Konfigurationseinstellung identisch ist und ihr Wert aktualisiert wird.

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

Aktualisieren Sie eine Konfigurationseinstellung für Featureflags oder die Konfigurationseinstellung Geheimnisverweis im Konfigurationsspeicher.

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

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

Löschen einer Konfigurationseinstellung

Löschen Sie eine vorhandene Konfigurationseinstellung, indem Sie aufrufen deleteConfigurationSetting.

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

Wenn Sie bei bedingten Anforderungen eine Konfigurationseinstellung bedingt löschen möchten, legen Sie den ifUnchanged Parameter auf true fest. Wenn-Parameter ifUnchanged auf true festgelegt ist. Wenn ifUnchanged true ist, wird die Konfigurationseinstellung nur gelöscht, wenn sie mit der angegebenen settingidentisch ist. Dies wird bestimmt, indem das ETag von setting mit dem im Dienst verglichen wird, um festzustellen, ob sie identisch sind oder nicht. Wenn das ETag identisch ist, bedeutet dies, dass die Konfigurationseinstellung identisch ist und ihr Wert gelöscht wird.

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

Löschen Sie im Konfigurationsspeicher eine Konfigurationseinstellung für Featureflags oder eine Referenzkonfigurationseinstellung für Secrete.Delete a Feature Flag configuration setting or Secrete Reference configuration setting.

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

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

Auflisten von Konfigurationseinstellungen mit mehreren Schlüsseln

Listen Sie mehrere Konfigurationseinstellungen auf, indem Sie aufrufen listConfigurationSettings. Übergeben Sie null SettingSelector an die -Methode, wenn Sie alle Konfigurationseinstellungen und ihre Felder abrufen möchten.

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

Auflisten von Revisionen mehrerer Konfigurationseinstellungen

Auflisten aller Revisionen einer Konfigurationseinstellung durch Aufrufen listRevisionsvon .

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

Festlegen einer Konfigurationseinstellung auf schreibgeschützt

Legen Sie eine Konfigurationseinstellung auf schreibgeschützte status fest.

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

Löschen schreibgeschützt aus einer Konfigurationseinstellung

Löschen Sie schreibgeschützt aus einer Konfigurationseinstellung.

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

Erstellen eines Clients mit Proxyoptionen

Erstellen Sie einen Konfigurationsclient mit Proxyoptionen.

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

Problembehandlung

Allgemein

Wenn Sie mit App Configuration interagieren, die diese Java-Clientbibliothek verwenden, entsprechen vom Dienst zurückgegebene Fehler den gleichen HTTP-status-Codes, die für REST-API-Anforderungen zurückgegeben werden. Wenn Sie beispielsweise versuchen, eine Konfigurationseinstellung abzurufen, die nicht in Ihrem Konfigurationsspeicher vorhanden ist, wird ein 404 Fehler zurückgegeben, der Not Foundangibt.

App Configuration bietet eine Möglichkeit, benutzerdefinierte Header über Context ein Objekt in der öffentlichen API zu definieren.

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

Ausführlichere Informationen finden Sie unter AddHeadersFromContextPolicy.

HTTP-Standardclient

Alle Clientbibliotheken verwenden standardmäßig den Netty-HTTP-Client. Durch Hinzufügen der obigen Abhängigkeit wird die Clientbibliothek automatisch für die Verwendung des Netty-HTTP-Clients konfiguriert. Das Konfigurieren oder Ändern des HTTP-Clients wird detailliert im Wiki zu HTTP-Clients beschrieben.

SSL-Standardbibliothek

Alle Clientbibliotheken verwenden standardmäßig die Tomcat-native Boring-SSL-Bibliothek, um die Leistung auf nativer Ebene für SSL-Vorgänge zu ermöglichen. Die Boring-SSL-Bibliothek ist eine Uber-JAR-Datei mit nativen Bibliotheken für Linux/macOS/Windows und bietet im Vergleich zur SSL-Standardimplementierung im JDK eine bessere Leistung. Weitere Informationen, einschließlich zur Reduzierung der Abhängigkeitsgröße, finden Sie im Abschnitt Leistungsoptimierung des Wikis.

Nächste Schritte

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Für die meisten Beiträge ist die Zustimmung zu einer Lizenzvereinbarung für Mitwirkende (Contributor License Agreement, CLA) erforderlich, in der Sie erklären, dass Sie dazu berechtigt sind, uns die Rechte für die Nutzung Ihres Beitrags zu erteilen, und dies auch tun.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Aufrufe