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

Ten artykuł zawiera omówienie korzystania z funkcji klienta HTTP i potoku w SDK Azure 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 abstrakcji HttpClient. 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-netty. W związku z tym klient HTTP Netty jest domyślnym klientem używanym we wszystkich bibliotekach zestawu Azure SDK dla języka Java.

Ważne

Upewnij się, że azure-core-http-netty zależność używa wersji 1.15.12 lub nowszej. Jeśli używasz BOM, upewnij się, że wersja BOM jest co najmniej 1.2.36.

Ta minimalna wersja jest wymagana do włączenia dużych nagłówków HTTP zwracanych przez usługę Azure Resource Manager podczas długotrwałych operacji.

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
• HttpClient wprowadzony w JDK 11

Notatka

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

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 pom.xml maven wykluczasz zależność Netty i dołączasz inną zależność.

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

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

<!-- OkHttp -->
<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-core-http-okhttp</artifactId>
  <version>1.12.10</version>
</dependency>

<!-- JDK HttpClient -->
<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-core-http-jdk-httpclient</artifactId>
  <version>1.0.3</version>
</dependency>

Notatka

Jeśli usuniesz zależność Netty, ale nie udostępnisz jej implementacji, uruchomienie aplikacji nie powiedzie się. Implementacja HttpClient musi być obecna w classpath.

Konfigurowanie klientów HTTP

Podczas kompilowania klienta usługi domyślnie używa HttpClient.createDefault(). Ta metoda zwraca podstawowe wystąpienie HttpClient 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 wystąpienia HttpClient. Budowniczy to NettyAsyncHttpClientBuilder, OkHttpAsyncHttpClientBuilderi JdkAsyncHttpClientBuilder.

W poniższych przykładach pokazano, jak tworzyć HttpClient wystąpienia przy użyciu biblioteki Netty, OkHttp i klienta HTTP JDK. Te instancje działają jako serwer proxy przez http://localhost:3128 i uwierzytelniają użytkownika example hasłem 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 HttpClient
HttpClient client = new JdkAsyncHttpClientBuilder()
    .proxy(new ProxyOptions(ProxyOptions.Type.HTTP, new InetSocketAddress("localhost", 3128))
        .setCredentials("example", "weakPassword"))
    .build();

Teraz możesz przekazać skonstruowane wystąpienie HttpClient do konstruktora klienta usługi, aby służyło jako klient do komunikacji z usługą. W poniższym przykładzie użyto nowego wystąpienia HttpClient do utworzenia klienta obiektu 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ć HttpClient podczas konfigurowania programu Manager.

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

Mechanizm przetwarzania 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 przesyłania HTTP

Podczas tworzenia klienta możesz podać własny dostosowany potok HTTP. Jeśli nie określisz potoku, biblioteka kliencka utworzy taki, który będzie skonfigurowany do pracy z tą konkretną biblioteką kliencką.

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 przesyłania HTTP

Potok przetwarzania składa się z sekwencji kroków wykonywanych dla każdej komunikacji zwrotnej żądania HTTP. Każda zasada ma określony cel i działa na żądanie, odpowiedź lub czasami obie. Ponieważ wszystkie biblioteki klienckie mają standardową warstwę "Azure Core", warstwa ta gwarantuje, że każda zasada jest wykonywana w odpowiedniej kolejności w potoku. Po wysłaniu żądania zasady są realizowane w kolejności dodawania ich do potoku. Po otrzymaniu odpowiedzi z usługi zasady są wykonywane w odwrotnej kolejności. Wszystkie polityki dodane do potoku są wykonywane przed wysłaniem żądania i po otrzymaniu odpowiedzi. Polityka musi zdecydować, czy zareagować na żądanie, odpowiedź, czy oba te elementy. Na przykład zasada rejestrowania rejestruje żądanie i odpowiedź, ale zasada uwierzytelniania jest zainteresowana 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 polityka może wykonać operację z podanymi danymi i przekazać kontrolę do następnej polityki w potoku.

Pozycja polityki przepływu 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 ta polityka ponawiania dzieli cały potok na dwie części: polityki wykonywane przed polityką ponawiania oraz polityki wykonywane po niej. Zasady dodane przed zasadą ponawiania są wykonywane tylko raz na operację API, a zasady dodane po zasadzie ponawiania są wykonywane tyle razy, ile wynika z liczby powtórzeń tej zasady.

Dlatego podczas budowania potoku HTTP należy zrozumieć, czy zasady powinny być stosowane przy każdym ponowieniu żądania, czy tylko raz na operację API.

Typowe zasady przepływu pracy 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. Azure Core jest wstępnie załadowane z tymi często wymaganymi zasadami HTTP, które można dodać do linii przetwarzania.

Policy	Link usługi GitHub
zasady ponawiania	RetryPolicy.java
zasady uwierzytelniania	BearerTokenAuthenticationPolicy.java
polityka logowania	HttpLoggingPolicy.java
polityka identyfikatora żądania	RequestIdPolicy.java
zasady telemetrii	UserAgentPolicy.java

Niestandardowa polityka 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 zasady do potoku można określić, czy ta zasada ma być wykonywana przy każdym wywołaniu, czy też przy każdej próbie ponowienia.

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

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ą obiektów Context 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ą biblioteki Boring SSL natywnej dla Tomcat, aby zapewnić 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 Tomcat-Native

Domyślnie plik JAR uber biblioteki SSL Tomcat-Native Boring 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 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 JDK TLS/SSL zamiast Tomcat-Native Boring SSL, musisz wykluczyć bibliotekę Tomcat-Native Boring SSL. Należy pamiętać, że w oparciu o nasze testy, wydajność TLS/SSL w JDK jest o 30% wolniejsza w porównaniu z Tomcat-Native Boring SSL. W przypadku korzystania z com.azure:azure-core:1.28.0 lub nowszego biblioteka implementująca HttpClient(na przykład com.azure:azure-core-http-netty) zarządza zależnością od Tomcat-Native Boring SSL. 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.