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

Článek
10/23/2023

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. Klient Netty HTTP je výchozím klientem používaným ve všech knihovnách Azure SDK pro Javu.

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 Maven pom.xml vyloučíte závislost Netty a zahrnete jinou závislost.

Následující příklad ukazuje, jak vyloučit závislost Netty z reálné závislosti na knihovně azure-security-keyvault-secrets . Nezapomeňte vyloučit Netty ze všech příslušných com.azure knihoven, 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í. V HttpClient cestě k třídě musí existovat implementace.

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 HttpClient instanci. Tvůrci jsou NettyAsyncHttpClientBuilder, OkHttpAsyncHttpClientBuildera JdkAsyncHttpClientBuilder.

Následující příklady ukazují, jak sestavovat HttpClient instance pomocí Netty, OkHttp a klienta HTTP sady JDK 11. Tyto instance proxy prostřednictvím http://localhost:3128 a ověřují se v příkladu uživatele pomocí hesla 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();

Nově můžete konstruovanou HttpClient instanci předat do tvůrce klienta služby, který se použije jako klient pro komunikaci se službou. Následující příklad používá novou HttpClient instanci 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 kanál nezadáte, klientská knihovna vytvoří jednu nakonfigurovanou pro práci s danou 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 tvoří bránu pro klientské knihovny Sady Azure SDK pro interakci se službami Azure. Jak jsme si poznamenali dříve v tomto článku, sada Azure SDK pro Javu ve výchozím nastavení používá pro přenos HTTP netty . 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

Kanál se skládá z posloupnosti kroků prováděných pro každou odezvu požadavku HTTP. Každá zásada má vyhrazený účel a pracuje na požadavku, odpovědi nebo někdy obojím. Vzhledem k tomu, že všechny klientské knihovny mají standardní vrstvu Azure Core, tato vrstva zajišťuje, aby se každá zásada v kanálu spouštěla v daném pořadí. Když odešlete žádost, zásady se spustí v pořadí, v jakém jsou přidány do kanálu. Když obdržíte odpověď ze služby, zásady se spustí v obráceném pořadí. Všechny zásady přidané do kanálu se spustí před odesláním požadavku a po přijetí odpovědi. Zásada se musí rozhodnout, jestli se má jednat 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 zásady s potřebnými daty požadavků a odpovědí spolu s veškerým nezbytným kontextem pro spuštění zásady. Tato zásada pak může provést svou operaci s danými daty a předat ovládací prvek k další zásadě v kanálu.

HTTP pipeline diagram

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 zásadami opakování a zásadami, které se spustí po zásadách opakování. Zásady přidané před spuštěním zásady opakování pouze jednou pro každou operaci rozhraní API a zásady přidané po provedení zásady opakování se provádějí tolikrát, kolikrát se pokusy opakují.

Takže při sestavování kanálu HTTP byste měli vědět, jestli se mají zásady pro každou operaci požadavku opakovat nebo jednou pro každou operaci rozhraní 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 se předem načte pomocí těchto běžně požadovaných zásad HTTP, které můžete přidat do kanálu.

Zásada	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 nebo zdobit požadavek a odpověď. Do kanálu, který vytvořil uživatel nebo vývojář klientské knihovny, můžete přidat vlastní zásady. Při přidávání zásad do kanálu můžete určit, jestli se má tato zásada spouštět podle volání nebo 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 zásadu připojit do kanálu.

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 Context objektů 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 nativních pro Tomcat

Ve výchozím nastavení se v sadá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 znázorně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 používali výchozí protokol TLS/SSL sady JDK místo protokolu SSL nativního pro Boring Tomcat, 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 sady JDK o 30 % pomalejší v porovnání s protokolem SSL Pro boring nativní pro Tomcat. Když použijete nebo později, com.azure:azure-core:1.28.0HttpClientimplementující knihovna (například com.azure:azure-core-http-netty) spravuje závislost na protokolu SSL Pro boring nativní tomcat. 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 serverů v sadě Azure SDK pro Javu.

Share via