Klienci i potoki HTTP w zestawie Azure SDK dla języka Java

Artykuł
10/23/2023

Ten artykuł zawiera omówienie korzystania z funkcji klienta HTTP i potoku w zestawie Azure SDK dla języka Java. Ta funkcja zapewnia spójne, zaawansowane i elastyczne środowisko dla deweloperów korzystających ze wszystkich bibliotek zestawu Azure SDK dla języka Java.

Klienci HTTP

Zestaw Azure SDK dla języka Java jest implementowany przy użyciu HttpClient abstrakcji. Ta abstrakcja umożliwia podłączanie architektury, która akceptuje wiele bibliotek klienckich HTTP lub niestandardowych implementacji. Jednak aby uprościć zarządzanie zależnościami dla większości użytkowników, wszystkie biblioteki klienckie platformy Azure zależą od azure-core-http-nettyprogramu . W związku z tym klient HTTP Netty jest domyślnym klientem używanym we wszystkich bibliotekach zestawu Azure SDK dla języka Java.

Mimo że netty jest domyślnym klientem HTTP, zestaw SDK udostępnia trzy implementacje klienta, w zależności od zależności, które już masz w projekcie. Te implementacje są przeznaczone dla:

Netty
OkHttp
Obiekt HttpClient wprowadzony w zestawie JDK 11

Uwaga

Zestaw JDK HttpClient w połączeniu z zestawem Azure SDK dla języka Java jest obsługiwany tylko z zestawem JDK 12 i nowszym.

Zamień domyślnego klienta HTTP

Jeśli wolisz inną implementację, możesz usunąć zależność od platformy Netty, wykluczając ją w plikach konfiguracji kompilacji. W pliku Maven pom.xml należy wykluczyć zależność Netty i dołączyć inną zależność.

W poniższym przykładzie pokazano, jak wykluczyć zależność netty z rzeczywistej azure-security-keyvault-secrets zależności od biblioteki. Pamiętaj, aby wykluczyć rozwiązanie Netty ze wszystkich odpowiednich com.azure bibliotek, jak pokazano poniżej:

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

Uwaga

Jeśli usuniesz zależność Netty, ale nie udostępnisz jej implementacji, uruchomienie aplikacji nie powiedzie się. Implementacja HttpClient musi istnieć na ścieżce klasy.

Konfigurowanie klientów HTTP

Podczas kompilowania klienta usługi domyślnie jest używany program HttpClient.createDefault(). Ta metoda zwraca podstawowe HttpClient wystąpienie na podstawie podanej implementacji klienta HTTP. Jeśli potrzebujesz bardziej złożonego klienta HTTP, takiego jak serwer proxy, każda implementacja oferuje konstruktora, który umożliwia konstruowanie skonfigurowanego HttpClient wystąpienia. Konstruktorzy to NettyAsyncHttpClientBuilder, OkHttpAsyncHttpClientBuilderi JdkAsyncHttpClientBuilder.

W poniższych przykładach pokazano, jak tworzyć HttpClient wystąpienia przy użyciu oprogramowania Netty, OkHttp i klienta HTTP zestawu JDK 11. Te wystąpienia proxy za pomocą przykładu użytkownika i uwierzytelniają się przy użyciu http://localhost:3128 hasła 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();

Teraz możesz przekazać skonstruowane HttpClient wystąpienie do konstruktora klienta usługi do użycia jako klient do komunikowania się z usługą. W poniższym przykładzie użyto nowego HttpClient wystąpienia do utworzenia klienta obiektów blob usługi Azure Storage.

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

W przypadku bibliotek zarządzania można ustawić konfigurację HttpClient programu Manager.

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

Potok HTTP

Potok HTTP jest jednym z kluczowych składników w celu zapewnienia spójności i możliwości diagnostyki w bibliotekach klienta Java dla platformy Azure. Potok HTTP składa się z następujących elementów:

Transport HTTP
Zasady potoku HTTP

Podczas tworzenia klienta możesz podać własny niestandardowy potok HTTP. Jeśli nie podasz potoku, biblioteka kliencka utworzy jedną skonfigurowaną do pracy z daną biblioteką klienta.

Transport HTTP

Transport HTTP jest odpowiedzialny za nawiązanie połączenia z serwerem oraz wysyłanie i odbieranie komunikatów HTTP. Transport HTTP tworzy bramę bibliotek klienckich zestawu Azure SDK w celu interakcji z usługami platformy Azure. Jak wspomniano wcześniej w tym artykule, zestaw Azure SDK dla języka Java domyślnie używa platformy Netty dla transportu HTTP. Jednak zestaw SDK zapewnia również podłączany transport HTTP, dzięki czemu można używać innych implementacji w odpowiednich przypadkach. Zestaw SDK udostępnia również dwie kolejne implementacje transportu HTTP dla usługi OkHttp i klienta HTTP dostarczanego z zestawem JDK 11 lub nowszym.

Zasady potoku HTTP

Potok składa się z sekwencji kroków wykonywanych dla każdego elementu roundtrip żądania HTTP. Każda zasada ma dedykowany cel i działa na żądanie, odpowiedź lub czasami oba te zasady. Ponieważ wszystkie biblioteki klienckie mają standardową warstwę "Azure Core", ta warstwa gwarantuje, że każda zasada jest wykonywana w kolejności w potoku. Po wysłaniu żądania zasady są wykonywane w kolejności dodawania ich do potoku. Po otrzymaniu odpowiedzi z usługi zasady są wykonywane w odwrotnej kolejności. Wszystkie zasady dodane do potoku są wykonywane przed wysłaniem żądania i po otrzymaniu odpowiedzi. Zasady muszą zdecydować, czy należy podjąć działania na żądanie, odpowiedź, czy oba te elementy. Na przykład zasady rejestrowania rejestruje żądanie i odpowiedź, ale zasady uwierzytelniania są zainteresowane tylko modyfikowaniem żądania.

Platforma Azure Core udostępnia zasady z niezbędnymi danymi żądania i odpowiedzi wraz z dowolnym kontekstem niezbędnym do wykonania zasad. Następnie zasady mogą wykonać operację z podanymi danymi i przekazać kontrolę do następnych zasad w potoku.

HTTP pipeline diagram

Pozycja zasad potoku HTTP

Gdy wysyłasz żądania HTTP do usług w chmurze, ważne jest, aby obsługiwać błędy przejściowe i ponowić nieudane próby. Ponieważ ta funkcja jest typowym wymaganiem, platforma Azure Core udostępnia zasady ponawiania, które mogą obserwować błędy przejściowe i automatycznie ponowić próbę żądania.

W związku z tym te zasady ponawiania prób dzielą cały potok na dwie części: zasady, które są wykonywane przed zasadami ponawiania i zasadami wykonywanymi po ponowieniu próby. Zasady dodane przed zasadami ponawiania są wykonywane tylko raz na operację interfejsu API, a zasady dodane po ponowieniu próby są wykonywane tyle razy, ile ponownych prób.

Dlatego podczas tworzenia potoku HTTP należy zrozumieć, czy należy wykonać zasady dla każdego żądania ponawiania próby, czy raz na operację interfejsu API.

Typowe zasady potoku HTTP

Potoki HTTP dla usług opartych na protokole REST mają konfiguracje z zasadami uwierzytelniania, ponawiania prób, rejestrowania, telemetrii i określania identyfikatora żądania w nagłówku. Usługa Azure Core jest wstępnie ładowana z tymi często wymaganymi zasadami HTTP, które można dodać do potoku.

Zasady	Link usługi GitHub
zasady ponawiania próby	RetryPolicy.java
zasady uwierzytelniania	BearerTokenAuthenticationPolicy.java
zasady rejestrowania	HttpLoggingPolicy.java
zasady identyfikatora żądania	RequestIdPolicy.java
zasady telemetrii	UserAgentPolicy.java

Niestandardowe zasady potoku HTTP

Zasady potoku HTTP zapewniają wygodny mechanizm modyfikowania lub dekorowania żądania i odpowiedzi. Możesz dodać zasady niestandardowe do potoku utworzonego przez użytkownika lub dewelopera biblioteki klienta. Podczas dodawania zasad do potoku można określić, czy te zasady mają być wykonywane na wywołanie, czy na ponawianie próby.

Aby utworzyć niestandardowe zasady potoku HTTP, wystarczy rozszerzyć podstawowy typ zasad i zaimplementować jakąś abstrakcyjną metodę. Następnie możesz podłączyć zasady do potoku.

Niestandardowe nagłówki w żądaniach HTTP

Zestaw Azure SDK dla bibliotek klienckich Języka Java zapewnia spójny sposób definiowania niestandardowych nagłówków za pomocą Context obiektów w publicznym interfejsie API, jak pokazano w poniższym przykładzie:

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

Aby uzyskać więcej informacji, zobacz AddHeadersFromContextPolicy Class (Klasa AddHeadersFromContextPolicy).

Domyślna biblioteka TLS/SSL

Domyślnie wszystkie biblioteki klienckie używają natywnej biblioteki SSL Boring serwera Tomcat, aby włączyć wydajność na poziomie natywnym dla operacji TLS/SSL. Biblioteka Boring SSL to plik JAR uber zawierający biblioteki natywne dla systemów Linux, macOS i Windows oraz zapewnia lepszą wydajność w porównaniu z domyślną implementacją protokołu TLS/SSL w zestawie JDK.

Zmniejsz rozmiar zależności protokołu TLS/SSL natywnego serwera Tomcat

Domyślnie plik JAR ubera biblioteki SSL boring natywnej dla serwera Tomcat jest używany w zestawach SDK platformy Azure dla języka Java. Aby zmniejszyć rozmiar tej zależności, należy uwzględnić zależność z klasyfikatorem os zgodnie z wartością netty-tcnative, jak pokazano w poniższym przykładzie:

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

Korzystanie z protokołu TLS/SSL zestawu JDK

Jeśli wolisz użyć domyślnego protokołu TLS/SSL zestawu JDK zamiast protokołu SSL boring natywnego dla serwera Tomcat, musisz wykluczyć natywną bibliotekę SSL boringową serwera Tomcat. Należy pamiętać, że w oparciu o nasze testy wydajność protokołu TLS/SSL zestawu JDK jest o 30% wolniejsza w porównaniu z protokołem SSL boring natywnym dla serwera Tomcat. W przypadku użycia com.azure:azure-core:1.28.0 lub nowszej HttpClientbiblioteki implementowania (na przykład com.azure:azure-core-http-netty) zarządza zależnością od protokołu SSL boring natywnego dla serwera Tomcat. Aby wykluczyć zależność, dodaj następującą konfigurację do pliku POM:

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

Następne kroki

Teraz, gdy znasz już funkcje klienta HTTP w zestawie Azure SDK dla języka Java, dowiedz się, jak dalej dostosowywać używanego klienta HTTP. Aby uzyskać więcej informacji, zobacz Konfigurowanie serwerów proxy w zestawie Azure SDK dla języka Java.

Udostępnij za pośrednictwem