Klienti a kanály HTTP v sadě Azure SDK pro Javu

Článek
01/20/2025

Tento článek obsahuje přehled použití klienta HTTP a funkce kanálu v rámci sady Azure SDK pro Javu. Tato funkce poskytuje konzistentní, výkonné a flexibilní prostředí pro vývojáře, kteří používají všechny knihovny Azure SDK pro Javu.

Klienti HTTP

Sada Azure SDK pro Javu se implementuje pomocí HttpClient abstrakce. Tato abstrakce umožňuje připojitelnou architekturu, která přijímá více klientských knihoven HTTP nebo vlastních implementací. Pro zjednodušení správy závislostí pro většinu uživatelů ale všechny klientské knihovny Azure závisí na azure-core-http-netty. Jako takový je Netty HTTP klient výchozím klientem používaným ve všech knihovnách Azure SDK pro Java.

I když je Netty výchozím klientem HTTP, sada SDK poskytuje tři implementace klienta v závislosti na tom, které závislosti už máte v projektu. Tyto implementace jsou určené pro:

Netty
OkHttp
HttpClient zavedený v JDK 11

Poznámka

Sada JDK HttpClient v kombinaci se sadou Azure SDK pro Javu se podporuje pouze s JDK 12 a vyšší.

Nahrazení výchozího klienta HTTP

Pokud dáváte přednost jiné implementaci, můžete závislost na Netty odebrat tak, že ji v konfiguračních souborech sestavení vyloučíte. V souboru pom.xml Mavenu vyloučíte závislost Netty a zahrnete jinou závislost.

Následující příklad ukazuje, jak vyloučit závislost Netty ze skutečné závislosti na knihovně azure-security-keyvault-secrets. Nezapomeňte vyloučit Netty ze všech příslušných knihoven com.azure, jak je znázorněno tady:

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

Poznámka

Pokud odeberete závislost Netty, ale nezadáte žádnou implementaci na jejím místě, aplikace se nespustí. Na classpathu musí existovat implementace HttpClient.

Konfigurace klientů HTTP

Při vytváření klienta služby se ve výchozím nastavení používá HttpClient.createDefault(). Tato metoda vrátí základní HttpClient instanci založenou na zadané implementaci klienta HTTP. V případě, že potřebujete složitějšího klienta HTTP, jako je proxy server, nabízí každá implementace tvůrce, který umožňuje vytvořit nakonfigurovanou instanci HttpClient. Stavitelé jsou NettyAsyncHttpClientBuilder, OkHttpAsyncHttpClientBuildera JdkAsyncHttpClientBuilder.

Následující příklady ukazují, jak sestavit HttpClient instance pomocí Netty, OkHttp a klienta HTTP sady JDK 11. Tyto instance proxy přes http://localhost:3128 a ověřují se uživatelským jménem example a heslem 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();

Nyní můžete předat konstruovanou instanci HttpClient do konstruktoru klienta služby, která bude sloužit jako klient pro komunikaci se službou. Následující příklad používá novou instanci HttpClient k sestavení klienta Azure Storage Blob.

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

Pro knihovny pro správu můžete nastavit HttpClient během konfigurace Správce.

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

Kanál HTTP

Kanál HTTP je jednou z klíčových komponent pro dosažení konzistence a diagnostiky v klientských knihovnách Java pro Azure. Kanál HTTP se skládá z:

Přenos HTTP
Zásady kanálu HTTP

Při vytváření klienta můžete zadat vlastní kanál HTTP. Pokud nezadáte potrubí, klientská knihovna vytvoří jedno nakonfigurované pro práci s konkrétní klientskou knihovnou.

Přenos HTTP

Přenos HTTP zodpovídá za navázání připojení k serveru a odesílání a přijímání zpráv HTTP. Přenos HTTP slouží jako brána pro klientské knihovny Azure SDK k interakci se službami Azure. Jak jsme uvedli dříve v tomto článku, sada Azure SDK pro Javu používá Netty ve výchozím nastavení pro přenos HTTP. Sada SDK ale také poskytuje připojitelný přenos HTTP, abyste mohli tam, kde je to vhodné, použít jiné implementace. Sada SDK také poskytuje dvě další implementace přenosu HTTP pro OkHttp a klienta HTTP, který je součástí sady JDK 11 a novější.

Zásady kanálu HTTP

Potrubí se skládá z posloupnosti kroků prováděných pro každou transakci požadavek-odpověď HTTP. Každá zásada má vyhrazený účel a působí na požadavek, nebo na odpověď, nebo někdy na obojí. Vzhledem k tomu, že všechny klientské knihovny mají standardní vrstvu „Azure Core“, tato vrstva zajišťuje, aby se každá zásada v rámci pipeline spouštěla ve stanoveném pořadí. Když odešlete žádost, zásady se vykonají v pořadí, v jakém byly přidány do kanálu. Když obdržíte odpověď ze služby, pravidla se vykonají v obráceném pořadí. Všechny zásady, které jsou přidány do kanálu, se spustí před odesláním požadavku a po přijetí odpovědi. Politika se musí rozhodnout, jestli má reagovat na žádost, odpověď, nebo obojí. Zásady protokolování například protokolují požadavek a odpověď, ale zásady ověřování se zajímají pouze o úpravu požadavku.

Architektura Azure Core poskytuje politice potřebná data o požadavcích a odpovědích spolu s veškerým nezbytným kontextem pro její provedení. Tato zásada pak může provést svou operaci s danými daty a předat řízení k další zásadě v potrubí.

diagram kanálu HTTP

Pozice zásad kanálu HTTP

Při provádění požadavků HTTP na cloudové služby je důležité zpracovávat přechodné chyby a opakovat neúspěšné pokusy. Vzhledem k tomu, že je tato funkce běžným požadavkem, Azure Core poskytuje zásady opakování, které můžou sledovat přechodné selhání a automaticky opakovat požadavek.

Tato zásada opakování proto rozdělí celý kanál na dvě části: zásady, které se spouštějí před opakovací zásadou, a zásady, které se spouštějí po opakovací zásadě. Zásady přidané před zásadou opakování se provedou pouze jednou pro každou operaci API a zásady přidané po zásadě opakování se provedou tolikrát, kolikrát se opakuje pokus.

Takže při sestavování kanálu HTTP byste měli porozumět tomu, zda provádět zásady při každém opakování požadavku nebo pouze jednou pro celou operaci API.

Běžné zásady kanálu HTTP

Kanály HTTP pro služby založené na REST mají konfigurace se zásadami pro ověřování, opakování, protokolování, telemetrii a určení ID požadavku v hlavičce. Azure Core je předem načten těmito běžně požadovanými zásadami HTTP, které můžete přidat do potrubí.

Politika	Odkaz na GitHub
zásady opakování	RetryPolicy.java
zásady ověřování	BearerTokenAuthenticationPolicy.java
zásady protokolování	HttpLoggingPolicy.java
zásady ID požadavku	RequestIdPolicy.java
zásady telemetrie	UserAgentPolicy.java

Vlastní zásady kanálu HTTP

Zásady kanálu HTTP poskytují pohodlný mechanismus pro úpravu požadavku a odpovědi. Do roury, kterou vytvořil uživatel nebo vývojář klientské knihovny, můžete přidat vlastní zásady. Při přidávání zásad k pipeline můžete určit, jestli se má tato zásada spouštět při každém volání nebo při každém opakování.

Pokud chcete vytvořit vlastní zásadu kanálu HTTP, stačí rozšířit základní typ zásady a implementovat nějakou abstraktní metodu. Pak můžete politiku připojit k potrubí.

Vlastní hlavičky v požadavcích HTTP

Klientské knihovny Azure SDK pro Javu poskytují konzistentní způsob definování přizpůsobených hlaviček prostřednictvím objektů Context ve veřejném rozhraní API, jak je znázorněno v následujícím příkladu:

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

Další informace naleznete v AddHeadersFromContextPolicy Třída.

Výchozí knihovna TLS/SSL

Všechny klientské knihovny ve výchozím nastavení používají nativní knihovnu BORING SSL tomcat k povolení výkonu nativní úrovně pro operace TLS/SSL. Boring SSL library je uber JAR obsahující nativní knihovny pro Linux, macOS a Windows a poskytuje lepší výkon v porovnání s výchozí implementací TLS/SSL v rámci sady JDK.

Zmenšení velikosti závislostí protokolu TLS/SSL Tomcat-Native

Ve výchozím nastavení se v knihovnách Azure SDK pro Javu používá soubor uber JAR knihovny Tomcat-Native Boring SSL. Chcete-li zmenšit velikost této závislosti, musíte zahrnout závislost s klasifikátorem os podle netty-tcnative, jak je ukázáno v následujícím příkladu:

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

Použití protokolu TLS/SSL sady JDK

Pokud byste raději místo Tomcat-Native boring SSL použili výchozí protokol TLS/SSL sady JDK, musíte vyloučit nativní knihovnu PROTOKOLU SSL tomcat. Mějte na paměti, že na základě našich testů je výkon protokolu TLS/SSL JDK 30% pomalejší v porovnání s Tomcat-Native boring SSL. Při použití com.azure:azure-core:1.28.0 nebo novější spravuje HttpClientimplementující knihovnu (například com.azure:azure-core-http-netty) závislost na Tomcat-Native Boring SSL. Pokud chcete závislost vyloučit, přidejte do souboru POM následující konfiguraci:

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

Další kroky

Teď, když znáte funkce klienta HTTP v sadě Azure SDK pro Javu, se dozvíte, jak dále přizpůsobit klienta HTTP, kterého používáte. Další informace najdete v tématu Konfigurace proxy v sadě Azure SDK pro javu.

Sdílet prostřednictvím