HTTP-Clients und Pipelines im Azure SDK für Java

Dieser Artikel enthält eine Übersicht über die Verwendung der HTTP-Client- und Pipelinefunktionen im Azure SDK für Java. Diese Funktionalität bietet entwicklern, die alle Azure SDK für Java-Bibliotheken verwenden, eine konsistente, leistungsstarke und flexible Oberfläche.

HTTP-Clients

Das Azure SDK für Java wird mithilfe einer HttpClient Abstraktion implementiert. Diese Abstraktion ermöglicht eine austauschbare Architektur, die mehrere HTTP-Clientbibliotheken oder benutzerdefinierte Implementierungen akzeptiert. Um die Abhängigkeitsverwaltung für die meisten Benutzer zu vereinfachen, sind alle Azure-Clientbibliotheken jedoch von azure-core-http-nettyabhängig. Daher ist der Netty HTTP-Client der Standardclient, der in allen Azure SDK für Java-Bibliotheken verwendet wird.

Obwohl Netty der Standard-HTTP-Client ist, stellt das SDK drei Clientimplementierungen bereit, je nachdem, welche Abhängigkeiten Sie bereits in Ihrem Projekt haben. Diese Implementierungen beziehen sich auf:

• Netty
• OkHttp
• In JDK 11 eingeführter HttpClient

Anmerkung

Das JDK-HttpClient in Kombination mit dem Azure SDK für Java wird nur mit JDK 12 und höher unterstützt.

Ersetzen des standardmäßigen HTTP-Clients

Wenn Sie eine andere Implementierung bevorzugen, können Sie die Abhängigkeit von Netty entfernen, indem Sie sie in den Buildkonfigurationsdateien ausschließen. In einer Maven pom.xml Datei schließen Sie die Netty-Abhängigkeit aus und schließen eine weitere Abhängigkeit ein.

Im folgenden Beispiel wird gezeigt, wie die Netty-Abhängigkeit aus einer realen Abhängigkeit von der azure-security-keyvault-secrets-Bibliothek ausgeschlossen wird. Stellen Sie sicher, dass Sie Netty aus allen entsprechenden com.azure-Bibliotheken ausschließen, wie hier gezeigt:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-security-keyvault-secrets</artifactId>
    <version>4.2.2.</version>
    <exclusions>
      <exclusion>
        <groupId>com.azure</groupId>
        <artifactId>azure-core-http-netty</artifactId>
      </exclusion>
    </exclusions>
</dependency>

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-core-http-okhttp</artifactId>
  <version>1.3.3</version>
</dependency>

Anmerkung

Wenn Sie die Netty-Abhängigkeit entfernen, aber keine Implementierung an ihrer Stelle bereitstellen, kann die Anwendung nicht gestartet werden. Eine HttpClient-Implementierung muss auf dem Klassenpfad vorhanden sein.

Konfigurieren von HTTP-Clients

Wenn Sie einen Dienstclient erstellen, wird standardmäßig HttpClient.createDefault() verwendet. Diese Methode gibt eine grundlegende HttpClient Instanz basierend auf der bereitgestellten HTTP-Clientimplementierung zurück. Falls Sie einen komplexeren HTTP-Client benötigen, z. B. einen Proxy, bietet jede Implementierung einen Generator, mit dem Sie eine konfigurierte HttpClient Instanz erstellen können. Die Generatoren sind NettyAsyncHttpClientBuilder, OkHttpAsyncHttpClientBuilder und JdkAsyncHttpClientBuilder.

Die folgenden Beispiele zeigen, wie Sie HttpClient Instanzen mit Netty, OkHttp und dem JDK 11-HTTP-Client erstellen. Diese Instanzen dienen als Proxy über http://localhost:3128 und authentifizieren sich bei dem Benutzer example mit dem Kennwort weakPassword.

// Netty
HttpClient httpClient = new NettyAsyncHttpClientBuilder()
    .proxy(new ProxyOptions(ProxyOptions.Type.HTTP, new InetSocketAddress("localhost", 3128))
        .setCredentials("example", "weakPassword"))
    .build();

// OkHttp
HttpClient httpClient = new OkHttpAsyncHttpClientBuilder()
    .proxy(new ProxyOptions(ProxyOptions.Type.HTTP, new InetSocketAddress("localhost", 3128))
        .setCredentials("example", "weakPassword"))
    .build();

// JDK 11 HttpClient
HttpClient client = new JdkAsyncHttpClientBuilder()
    .proxy(new ProxyOptions(ProxyOptions.Type.HTTP, new InetSocketAddress("localhost", 3128))
        .setCredentials("example", "weakPassword"))
    .build();

Sie können jetzt die generierte HttpClient-Instanz an einen Dienstclient-Generator übergeben, damit sie als Client für die Kommunikation mit dem Dienst verwendet wird. Im folgenden Beispiel wird die neue HttpClient Instanz verwendet, um einen Azure Storage Blob-Client zu erstellen.

BlobClient blobClient = new BlobClientBuilder()
    .connectionString(<connection string>)
    .containerName("container")
    .blobName("blob")
    .httpClient(httpClient)
    .build();

Für Verwaltungsbibliotheken können Sie den HttpClient während der Manager-Konfiguration festlegen.

AzureResourceManager azureResourceManager = AzureResourceManager.configure()
    .withHttpClient(httpClient)
    .authenticate(credential, profile)
    .withDefaultSubscription();

HTTP-Pipeline

Die HTTP-Pipeline ist eine der wichtigsten Komponenten, um Konsistenz und Diagnosierbarkeit in den Java-Clientbibliotheken für Azure zu erzielen. Eine HTTP-Pipeline besteht aus:

• Ein HTTP-Transport
• HTTP-Pipelinerichtlinien

Sie können beim Erstellen eines Clients Eine eigene benutzerdefinierte HTTP-Pipeline bereitstellen. Wenn Sie keine Pipeline bereitstellen, erstellt die Clientbibliothek eine, die für die Arbeit mit dieser bestimmten Clientbibliothek konfiguriert ist.

HTTP-Transport

Der HTTP-Transport ist für das Herstellen der Verbindung mit dem Server und das Senden und Empfangen von HTTP-Nachrichten verantwortlich. Der HTTP-Transport bildet das Gateway für die Azure SDK-Clientbibliotheken für die Interaktion mit Azure-Diensten. Wie weiter oben in diesem Artikel erwähnt, verwendet das Azure SDK für Java standardmäßig Netty für den HTTP-Transport. Das SDK bietet jedoch auch einen austauschbaren HTTP-Transport, sodass Sie ggf. andere Implementierungen verwenden können. Das SDK bietet außerdem zwei weitere HTTP-Transportimplementierungen für OkHttp und den HTTP-Client, der mit JDK 11 und höher ausgeliefert wird.

HTTP-Pipelinerichtlinien

Eine Pipeline besteht aus einer Sequenz von Schritten, die für jeden HTTP-Anforderungsantwort-Roundtrip ausgeführt werden. Jede Richtlinie hat einen bestimmten Zweck und wirkt sich auf eine Anforderung oder eine Antwort oder manchmal auf beides aus. Da alle Clientbibliotheken über eine standardmäßige Azure Core-Ebene verfügen, stellt diese Ebene sicher, dass jede Richtlinie in der Pipeline in der Reihenfolge ausgeführt wird. Wenn Sie eine Anforderung senden, werden die Richtlinien in der Reihenfolge ausgeführt, in der sie der Pipeline hinzugefügt wurden. Wenn Sie eine Antwort vom Dienst erhalten, werden die Richtlinien in umgekehrter Reihenfolge ausgeführt. Alle Richtlinien, die der Pipeline hinzugefügt werden, werden vor dem Senden der Anforderung und nach dem Empfangen einer Antwort ausgeführt. Die Richtlinie muss entscheiden, ob sie auf die Anforderung, die Antwort oder beides reagieren soll. Beispielsweise protokolliert eine Protokollierungsrichtlinie die Anforderung und Antwort, aber die Authentifizierungsrichtlinie ist nur daran interessiert, die Anforderung zu ändern.

Das Azure Core-Framework stellt die notwendigen Anforderungs- und Antwortdaten sowie den erforderlichen Kontext für die Ausführung der Richtlinie bereit. Die Richtlinie kann dann den Vorgang mit den angegebenen Daten ausführen und die Steuerung dann an die nächste Richtlinie in der Pipeline übergeben.

Position der HTTP-Pipelinerichtlinie

Wenn Sie HTTP-Anforderungen an Clouddienste senden, ist es wichtig, vorübergehende Fehler zu behandeln und fehlgeschlagene Versuche erneut auszuführen. Da diese Funktionalität eine häufige Anforderung ist, stellt Azure Core eine Wiederholungsrichtlinie bereit, die auf vorübergehende Fehler achten und die Anforderung automatisch wiederholen kann.

Diese Wiederholungsrichtlinie teilt daher die gesamte Pipeline in zwei Teile auf: Richtlinien, die vor der Wiederholungsrichtlinie ausgeführt werden, und Richtlinien, die nach der Wiederholungsrichtlinie ausgeführt werden. Richtlinien, die vor der Wiederholungsrichtlinie hinzugefügt wurden, werden nur einmal pro API-Vorgang ausgeführt, und Richtlinien, die nach der Wiederholungsrichtlinie hinzugefügt wurden, werden so oft wie die Wiederholungsversuche ausgeführt.

Wenn Sie also die HTTP-Pipeline erstellen, sollten Sie wissen, ob Sie eine Richtlinie für jede Anforderungs-Wiederholung oder einmal pro API-Vorgang ausführen.

Allgemeine HTTP-Pipelinerichtlinien

HTTP-Pipelines für REST-basierte Dienste verfügen über Konfigurationen mit Richtlinien für Authentifizierung, Wiederholungen, Protokollierung, Telemetrie und Angeben der Anforderungs-ID im Header. Azure Core wird mit diesen häufig erforderlichen HTTP-Richtlinien vorinstalliert, die Sie der Pipeline hinzufügen können.

Policy	GitHub-Link
Wiederholungsrichtlinie	RetryPolicy.java
Authentifizierungsrichtlinie	BearerTokenAuthenticationPolicy.java
Protokollierungsrichtlinie	HttpLoggingPolicy.java
Anforderungs-ID-Richtlinie	RequestIdPolicy.java
Telemetrierichtlinie	UserAgentPolicy.java

Benutzerdefinierte HTTP-Pipelinerichtlinie

Die HTTP-Pipelinerichtlinie bietet einen praktischen Mechanismus zum Ändern oder Dekorieren der Anforderung und Antwort. Sie können der Pipeline benutzerdefinierte Richtlinien hinzufügen, die der Benutzer oder der Entwickler der Client-Bibliothek erstellt hat. Wenn Sie der Pipeline die Richtlinie hinzufügen, können Sie angeben, ob diese Richtlinie pro Aufruf oder pro Wiederholungsversuch ausgeführt werden soll.

Um eine benutzerdefinierte HTTP-Pipelinerichtlinie zu erstellen, erweitern Sie einfach einen Basisrichtlinientyp und implementieren eine abstrakte Methode. Anschließend können Sie die Richtlinie in die Pipeline integrieren.

Benutzerdefinierte Header in HTTP-Anforderungen

Das Azure SDK für Java-Clientbibliotheken bietet eine konsistente Möglichkeit, benutzerdefinierte Header über Context-Objekte in der öffentlichen API zu definieren, wie im folgenden Beispiel gezeigt:

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

// The three headers are now be added to the outgoing HTTP request.

Weitere Informationen finden Sie in der AddHeadersFromContextPolicy-Klasse.

Standard-TLS/SSL-Bibliothek

Alle Clientbibliotheken verwenden standardmäßig die Tomcat-native Boring-SSL-Bibliothek, um die Leistung auf nativer Ebene für TLS/SSL-Vorgänge zu ermöglichen. Die Boring SSL-Bibliothek ist ein Uber JAR mit nativen Bibliotheken für Linux, macOS und Windows und bietet eine bessere Leistung im Vergleich zur standardmäßigen TLS/SSL-Implementierung innerhalb des JDK.

Verringern Tomcat-Native TLS-SSL-Abhängigkeitsumfang

Standardmäßig wird der Uber-JAR der Tomcat-Native Boring SSL-Bibliothek in den Azure SDKs für Java verwendet. Um die Größe dieser Abhängigkeit zu reduzieren, müssen Sie die Abhängigkeit mit einem os-Klassifikator gemäß netty-tcnative einschließen, wie im folgenden Beispiel gezeigt:

<project>
  ...
  <dependencies>
    ...
    <dependency>
      <groupId>io.netty</groupId>
      <artifactId>netty-tcnative-boringssl-static</artifactId>
      <version>2.0.25.Final</version>
      <classifier>${os.detected.classifier}</classifier>
    </dependency>
    ...
  </dependencies>
  ...
  <build>
    ...
    <extensions>
      <extension>
        <groupId>kr.motd.maven</groupId>
        <artifactId>os-maven-plugin</artifactId>
        <version>1.4.0.Final</version>
      </extension>
    </extensions>
    ...
  </build>
  ...
</project>

Verwenden von JDK TLS/SSL

Wenn Sie lieber das Standardmäßige JDK TLS/SSL anstelle von Tomcat-Native Boring SSL verwenden möchten, müssen Sie die Tomcat-native Boring SSL-Bibliothek ausschließen. Beachten Sie, dass die Leistung von JDK TLS/SSL basierend auf unseren Tests um 30% langsamer als Tomcat-Native Boring SSL ist. Wenn Sie com.azure:azure-core:1.28.0 oder höher verwenden, verwaltet die HttpClientimplementierende Bibliothek (z. B. com.azure:azure-core-http-netty) die Abhängigkeit von Tomcat-Native Boring SSL. Um die Abhängigkeit auszuschließen, fügen Sie der POM-Datei die folgende Konfiguration hinzu:

<project>
  ...
  <dependencies>
    ...
    <dependency>
     <groupId>com.azure</groupId>
       <artifactId>azure-core-http-netty</artifactId>
       <version>1.13.6</version>
       <exclusions>
         <exclusion>
           <groupId>io.netty</groupId>
           <artifactId>netty-tcnative-boringssl-static</artifactId>
         </exclusion>
       </exclusions>
    </dependency>
    ...
  </dependencies>
  ...
</project>

Nächste Schritte

Nachdem Sie nun mit der HTTP-Clientfunktionalität im Azure SDK für Java vertraut sind, erfahren Sie, wie Sie den verwendeten HTTP-Client weiter anpassen. Weitere Informationen finden Sie unter Konfigurieren von Proxys im Azure SDK für Java.