Java için Azure SDK'da HTTP istemcileri ve işlem hatları

Makale
10/23/2023

Bu makalede, Java için Azure SDK'sı içinde HTTP istemcisi ve işlem hattı işlevselliğini kullanmaya genel bir bakış sağlanır. Bu işlevsellik, tüm Java kitaplıkları için Azure SDK'sını kullanan geliştiriciler için tutarlı, güçlü ve esnek bir deneyim sağlar.

HTTP istemcileri

Java için Azure SDK bir HttpClient soyutlama kullanılarak uygulanır. Bu soyutlama, birden çok HTTP istemci kitaplığını veya özel uygulamayı kabul eden eklenebilir bir mimariyi etkinleştirir. Ancak, çoğu kullanıcı için bağımlılık yönetimini basitleştirmek için tüm Azure istemci kitaplıkları öğesine azure-core-http-nettybağlıdır. Bu nedenle Netty HTTP istemcisi, Java kitaplıkları için tüm Azure SDK'larında kullanılan varsayılan istemcidir.

Netty varsayılan HTTP istemcisi olsa da SDK, projenizde zaten sahip olduğunuz bağımlılıklara bağlı olarak üç istemci uygulaması sağlar. Bu uygulamalar şunlara yöneliktir:

Dekont

Java için Azure SDK ile birlikte JDK HttpClient yalnızca JDK 12 ve üzeri sürümlerde desteklenir.

Varsayılan HTTP istemcisini değiştirme

Başka bir uygulama tercih ederseniz, Derleme yapılandırma dosyalarında dışlayarak Netty bağımlılığını kaldırabilirsiniz. Maven pom.xml dosyasında Netty bağımlılığını dışlar ve başka bir bağımlılık eklersiniz.

Aşağıdaki örnekte, Netty bağımlılığını kitaplıkta gerçek bir bağımlılıktan nasıl hariç tutabileceğiniz gösterilmektedir azure-security-keyvault-secrets . Burada gösterildiği gibi Netty'yi tüm uygun com.azure kitaplıkların dışında tutmayı unutmayın:

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

Dekont

Netty bağımlılığını kaldırır ancak yerine uygulama sağlamazsanız, uygulama başlatılamaz. Sınıf yolu üzerinde bir HttpClient uygulama bulunmalıdır.

HTTP istemcilerini yapılandırma

Bir hizmet istemcisi oluşturduğunuzda, varsayılan olarak kullanılır HttpClient.createDefault(). Bu yöntem, sağlanan HTTP istemci uygulamasını temel alan temel HttpClient bir örnek döndürür. Ara sunucu gibi daha karmaşık bir HTTP istemcisine ihtiyacınız olması durumunda, her uygulama yapılandırılmış HttpClient bir örnek oluşturmanıza olanak tanıyan bir oluşturucu sunar. Oluşturucular , OkHttpAsyncHttpClientBuilderve JdkAsyncHttpClientBuilderşeklindedirNettyAsyncHttpClientBuilder.

Aşağıdaki örneklerde Netty, OkHttp ve JDK 11 HTTP istemcisini kullanarak örneklerin nasıl derlenmiş HttpClient olduğu gösterilmektedir. Bu örnekler aracılığıyla http://localhost:3128 ara sunucu ve parola weakPassword ile kullanıcı örneği ile kimlik doğrulaması.

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

Artık, hizmetle iletişim kurmak için istemci olarak kullanmak üzere bir hizmet istemci oluşturucusuna yapılandırılan HttpClient örneği geçirebilirsiniz. Aşağıdaki örnek, azure Depolama Blob istemcisi oluşturmak için yeni HttpClient örneği kullanır.

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

Yönetim kitaplıkları için, Yönetici yapılandırması sırasında öğesini HttpClient ayarlayabilirsiniz.

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

HTTP işlem hattı

HTTP işlem hattı, Azure için Java istemci kitaplıklarında tutarlılık ve tanınabilirlik elde etme konusunda önemli bileşenlerden biridir. HTTP işlem hattı şunlardan oluşur:

HTTP aktarımı
HTTP işlem hattı ilkeleri

İstemci oluştururken kendi özel HTTP işlem hattınızı sağlayabilirsiniz. İşlem hattı sağlamazsanız, istemci kitaplığı ilgili istemci kitaplığıyla çalışacak şekilde yapılandırılmış bir tane oluşturur.

HTTP aktarımı

HTTP aktarımı, sunucuyla bağlantı kurmaktan ve HTTP iletileri gönderip almaktan sorumludur. HTTP aktarımı, Azure SDK istemci kitaplıklarının Azure hizmetleriyle etkileşime geçmek için ağ geçidini oluşturur. Bu makalede daha önce belirtildiği gibi Java için Azure SDK, HTTP aktarımı için varsayılan olarak Netty kullanır. Ancak SDK, uygun yerlerde diğer uygulamaları kullanabilmeniz için takılabilir bir HTTP aktarımı da sağlar. SDK ayrıca OkHttp ve JDK 11 ve üzeri sürümlerle birlikte gelen HTTP istemcisi için iki http aktarım uygulaması daha sağlar.

HTTP işlem hattı ilkeleri

İşlem hattı, her HTTP istek yanıtı gidiş dönüş için yürütülen bir dizi adımdan oluşur. Her ilkenin özel bir amacı vardır ve bir istek veya yanıt ya da bazen her ikisi üzerinde de hareket eder. Tüm istemci kitaplıkları standart bir 'Azure Core' katmanına sahip olduğundan, bu katman her ilkenin işlem hattında sırayla yürütülmesini sağlar. bir istek gönderdiğinizde, ilkeler işlem hattına eklenme sırasına göre yürütülür. Hizmetten bir yanıt aldığınızda ilkeler ters sırada yürütülür. İşlem hattına eklenen tüm ilkeler, isteği göndermeden önce ve yanıt aldıktan sonra yürütülür. İlkenin istekte mi, yanıtta mı yoksa her ikisinde de işlem yapıp yapmayeceğine karar vermesi gerekir. Örneğin, günlük ilkesi isteği ve yanıtı günlüğe kaydeder, ancak kimlik doğrulama ilkesi yalnızca isteği değiştirmekle ilgilenir.

Azure Core çerçevesi, ilkeyi yürütmek için gerekli bağlamın yanı sıra gerekli istek ve yanıt verilerini de sağlar. İlke daha sonra belirtilen verilerle işlemini gerçekleştirebilir ve denetimi işlem hattındaki bir sonraki ilkeye geçirebilir.

HTTP pipeline diagram

HTTP işlem hattı ilkesi konumu

Bulut hizmetlerine HTTP istekleri gönderdiğinizde, geçici hataların işlenmesi ve başarısız girişimlerin yeniden denenmesi önemlidir. Bu işlevsellik yaygın bir gereksinim olduğundan, Azure Core geçici hataları izleyebilen ve isteği otomatik olarak yeniden deneyebilen bir yeniden deneme ilkesi sağlar.

Bu yeniden deneme ilkesi, işlem hattının tamamını iki bölüme ayırır: yeniden deneme ilkesinden önce yürütülen ilkeler ve yeniden deneme ilkesinden sonra yürütülen ilkeler. Yeniden deneme ilkesinden önce eklenen ilkeler API işlemi başına yalnızca bir kez yürütülür ve yeniden deneme ilkesinden sonra eklenen ilkeler, yeniden denemeler kadar çok kez yürütülür.

Bu nedenle, HTTP işlem hattını oluştururken, her istek yeniden denemesi için bir ilke yürütmeyi mi yoksa API işlemi başına bir kez mi yürütmeniz gerektiğini anlamanız gerekir.

Yaygın HTTP işlem hattı ilkeleri

REST tabanlı hizmetler için HTTP işlem hatlarının kimlik doğrulaması, yeniden denemeler, günlüğe kaydetme, telemetri ve üst bilgide istek kimliğini belirtme ilkelerine sahip yapılandırmaları vardır. Azure Core, işlem hattına ekleyebileceğiniz bu yaygın olarak gerekli HTTP ilkeleriyle önceden yüklenir.

Poliçe	GitHub bağlantısı
yeniden deneme ilkesi	RetryPolicy.java
kimlik doğrulama ilkesi	BearerTokenAuthenticationPolicy.java
günlük ilkesi	HttpLoggingPolicy.java
istek kimliği ilkesi	RequestIdPolicy.java
telemetri ilkesi	UserAgentPolicy.java

Özel HTTP işlem hattı ilkesi

HTTP işlem hattı ilkesi, isteği ve yanıtı değiştirmek veya süslemek için kullanışlı bir mekanizma sağlar. Kullanıcının veya istemci kitaplığı geliştiricisinin oluşturduğu işlem hattına özel ilkeler ekleyebilirsiniz. İlkeyi işlem hattına eklerken, bu ilkenin çağrı başına mı yoksa yeniden deneme başına mı yürütüleceğini belirtebilirsiniz.

Özel bir HTTP işlem hattı ilkesi oluşturmak için bir temel ilke türünü genişletmeniz ve soyut bir yöntem uygulamanız gerekir. Ardından ilkeyi işlem hattına takabilirsiniz.

HTTP isteklerindeki özel üst bilgiler

Java için Azure SDK istemci kitaplıkları, aşağıdaki örnekte gösterildiği gibi genel API'deki nesneler aracılığıyla Context özelleştirilmiş üst bilgileri tanımlamak için tutarlı bir yol sağlar:

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

Daha fazla bilgi için bkz . AddHeadersFromContextPolicy Sınıfı.

Varsayılan TLS/SSL kitaplığı

Varsayılan olarak tüm istemci kitaplıkları, TLS/SSL işlemleri için yerel düzeyde performans sağlamak için Tomcat yerel Sıkıcı SSL kitaplığını kullanır. Sıkıcı SSL kitaplığı Linux, macOS ve Windows için yerel kitaplıklar içeren bir uber JAR'dir ve JDK içindeki varsayılan TLS/SSL uygulamasına kıyasla daha iyi performans sağlar.

Tomcat-Native TLS/SSL bağımlılık boyutunu küçültme

Varsayılan olarak, Java için Azure SDK'larında Tomcat-Native Boring SSL kitaplığının uber JAR'ı kullanılır. Bu bağımlılığın boyutunu küçültmek için, aşağıdaki örnekte gösterildiği gibi bağımlılığı netty-tcnative'a göre bir os sınıflandırıcıya eklemeniz gerekir:

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

JDK TLS/SSL kullanma

Tomcat-Native Boring SSL yerine varsayılan JDK TLS/SSL'yi kullanmayı tercih ediyorsanız, Tomcat-native Boring SSL kitaplığını dışlamanız gerekir. Testlerimize göre JDK TLS/SSL performansının Tomcat-Native Boring SSL ile karşılaştırıldığında %30 daha yavaş olduğunu unutmayın. Veya daha sonra kullandığınızda com.azure:azure-core:1.28.0 , HttpClient-implementing kitaplığı (örneğin com.azure:azure-core-http-netty), Tomcat-Native Boring SSL bağımlılığını yönetir. Bağımlılığı dışlamak için POM dosyanıza aşağıdaki yapılandırmayı ekleyin:

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

Sonraki adımlar

Java için Azure SDK'daki HTTP istemcisi işlevselliğini öğrendiğinize göre, kullandığınız HTTP istemcisini nasıl daha fazla özelleştirebileceğinizi öğrenin. Daha fazla bilgi için bkz . Java için Azure SDK'da proxy'leri yapılandırma.

Share via