HTTP-klienter och pipelines i Azure SDK för Java

Artikel
10/23/2023

Den här artikeln innehåller en översikt över hur du använder HTTP-klienten och pipelinefunktionerna i Azure SDK för Java. Den här funktionen ger en konsekvent, kraftfull och flexibel upplevelse för utvecklare som använder alla Azure SDK för Java-bibliotek.

HTTP-klienter

Azure SDK för Java implementeras med hjälp av en HttpClient abstraktion. Den här abstraktionen möjliggör en anslutningsbar arkitektur som accepterar flera HTTP-klientbibliotek eller anpassade implementeringar. Men för att förenkla beroendehanteringen för de flesta användare är alla Azure-klientbibliotek beroende av azure-core-http-netty. Därför är Netty HTTP-klienten standardklienten som används i alla Azure SDK för Java-bibliotek.

Även om Netty är http-standardklienten tillhandahåller SDK tre klientimplementeringar, beroende på vilka beroenden du redan har i projektet. Dessa implementeringar är till för:

Netty
OkHttp
HttpClient introducerades i JDK 11

Kommentar

JDK:t HttpClient i kombination med Azure SDK för Java stöds endast med JDK 12 och senare.

Ersätt http-standardklienten

Om du föredrar en annan implementering kan du ta bort beroendet av Netty genom att exkluderas i konfigurationsfilerna för bygget. I en Maven pom.xml-fil exkluderar du Netty-beroendet och inkluderar ett annat beroende.

I följande exempel visas hur du undantar Netty-beroendet från ett verkligt beroende av azure-security-keyvault-secrets biblioteket. Se till att undanta Netty från alla lämpliga com.azure bibliotek, som du ser här:

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

Kommentar

Om du tar bort Netty-beroendet men inte tillhandahåller någon implementering i dess ställe kan programmet inte startas. En HttpClient implementering måste finnas på klassökvägen.

Konfigurera HTTP-klienter

När du skapar en tjänstklient används som standard HttpClient.createDefault(). Den här metoden returnerar en grundläggande HttpClient instans baserat på den angivna HTTP-klientimplementeringen. Om du behöver en mer komplex HTTP-klient, till exempel en proxy, erbjuder varje implementering en byggare som gör att du kan skapa en konfigurerad HttpClient instans. Byggarna är NettyAsyncHttpClientBuilder, OkHttpAsyncHttpClientBuilderoch JdkAsyncHttpClientBuilder.

I följande exempel visas hur du skapar HttpClient instanser med Netty, OkHttp och HTTP-klienten JDK 11. Dessa instanser proxy via http://localhost:3128 och autentisera med användarexempel med lösenord 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();

Nu kan du skicka den konstruerade HttpClient instansen till en tjänstklientbyggare för användning som klient för kommunikation med tjänsten. I följande exempel används den nya HttpClient instansen för att skapa en Azure Storage Blob-klient.

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

För hanteringsbibliotek kan du ange HttpClient under Manager-konfigurationen.

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

HTTP-pipeline

HTTP-pipelinen är en av de viktigaste komponenterna för att uppnå konsekvens och diagnoserbarhet i Java-klientbiblioteken för Azure. En HTTP-pipeline består av:

En HTTP-transport
HTTP-pipelineprinciper

Du kan ange en egen anpassad HTTP-pipeline när du skapar en klient. Om du inte anger en pipeline skapar klientbiblioteket en som är konfigurerad för att fungera med det specifika klientbiblioteket.

HTTP-transport

HTTP-transporten ansvarar för att upprätta anslutningen till servern och skicka och ta emot HTTP-meddelanden. HTTP-transporten utgör gatewayen för Azure SDK-klientbiblioteken för att interagera med Azure-tjänster. Som tidigare nämnts i den här artikeln använder Azure SDK för Java Netty som standard för sin HTTP-transport. SDK:t tillhandahåller dock också en anslutningsbar HTTP-transport så att du kan använda andra implementeringar där det är lämpligt. SDK innehåller också ytterligare två HTTP-transportimplementeringar för OkHttp och HTTP-klienten som levereras med JDK 11 och senare.

HTTP-pipelineprinciper

En pipeline består av en sekvens med steg som körs för varje tur och retur för HTTP-begärandesvar. Varje princip har ett särskilt syfte och agerar på en begäran eller ett svar eller ibland båda. Eftersom alla klientbibliotek har ett standardlager för "Azure Core" ser det här lagret till att varje princip körs i ordning i pipelinen. När du skickar en begäran körs principerna i den ordning som de läggs till i pipelinen. När du får ett svar från tjänsten körs principerna i omvänd ordning. Alla principer som läggs till i pipelinen körs innan du skickar begäran och när du har fått ett svar. Principen måste avgöra om den ska agera på begäran, svaret eller båda. En loggningsprincip loggar till exempel begäran och svaret, men autentiseringsprincipen är bara intresserad av att ändra begäran.

Azure Core-ramverket tillhandahåller principen med nödvändiga begärande- och svarsdata tillsammans med alla nödvändiga kontexter för att köra principen. Principen kan sedan utföra sin åtgärd med angivna data och skicka kontrollen vidare till nästa princip i pipelinen.

HTTP pipeline diagram

HTTP-pipelineprincipposition

När du gör HTTP-begäranden till molntjänster är det viktigt att hantera tillfälliga fel och försöka utföra misslyckade försök igen. Eftersom den här funktionen är ett vanligt krav tillhandahåller Azure Core en återförsöksprincip som kan hålla utkik efter tillfälliga fel och automatiskt försöka begära igen.

Den här återförsöksprincipen delar därför upp hela pipelinen i två delar: principer som körs före återförsöksprincipen och principerna som körs efter återförsöksprincipen. Principer som lagts till innan återförsöksprincipen endast körs en gång per API-åtgärd och principer som läggs till efter återförsöksprincipen körs så många gånger som återförsöken.

När du skapar HTTP-pipelinen bör du därför förstå om du vill köra en princip för varje begäran eller en gång per API-åtgärd.

Vanliga HTTP-pipelineprinciper

HTTP-pipelines för REST-baserade tjänster har konfigurationer med principer för autentisering, återförsök, loggning, telemetri och ange begärande-ID i huvudet. Azure Core är förinstallerat med dessa vanliga HTTP-principer som du kan lägga till i pipelinen.

Policy	GitHub-länk
återförsöksprincip	RetryPolicy.java
autentiseringsprincip	BearerTokenAuthenticationPolicy.java
loggningsprincip	HttpLoggingPolicy.java
begärande-ID-princip	RequestIdPolicy.java
telemetriprincip	UserAgentPolicy.java

Anpassad HTTP-pipelineprincip

HTTP-pipelineprincipen ger en praktisk mekanism för att ändra eller dekorera begäran och svaret. Du kan lägga till anpassade principer i pipelinen som användaren eller klientbiblioteksutvecklaren skapade. När du lägger till principen i pipelinen kan du ange om den här principen ska köras per anrop eller per nytt försök.

Om du vill skapa en anpassad HTTP-pipelineprincip utökar du bara en basprinciptyp och implementerar en abstrakt metod. Du kan sedan ansluta principen till pipelinen.

Anpassade rubriker i HTTP-begäranden

Azure SDK för Java-klientbibliotek ger ett konsekvent sätt att definiera anpassade rubriker via Context objekt i det offentliga API:et, enligt följande exempel:

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

Mer information finns i klassen AddHeadersFromContextPolicy.

Standardbibliotek för TLS/SSL

Alla klientbibliotek använder som standard det Tomcat-inbyggda Boring SSL-biblioteket för att aktivera prestanda på intern nivå för TLS/SSL-åtgärder. Boring SSL-biblioteket är en uber-JAR som innehåller interna bibliotek för Linux, macOS och Windows och ger bättre prestanda jämfört med standardimplementeringen för TLS/SSL i JDK.

Minska tomcat-native TLS/SSL-beroendestorlek

Som standard används uber JAR i Tomcat-Native Boring SSL-biblioteket i Azure SDK:er för Java. För att minska storleken på det här beroendet måste du inkludera beroendet med en os klassificerare enligt netty-tcnative, enligt följande exempel:

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

Använda JDK TLS/SSL

Om du hellre vill använda JDK-standard-TLS/SSL i stället för Tomcat-Native Boring SSL måste du exkludera Tomcat-native Boring SSL-biblioteket. Tänk på att prestanda för JDK TLS/SSL, baserat på våra tester, är 30 % långsammare jämfört med Tomcat-Native Boring SSL. När du använder com.azure:azure-core:1.28.0 eller senare HttpClienthanterar -implementeringsbiblioteket (till exempel com.azure:azure-core-http-netty) beroendet av Tomcat-Native Boring SSL. Om du vill undanta beroendet lägger du till följande konfiguration i POM-filen:

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

Nästa steg

Nu när du är bekant med HTTP-klientfunktioner i Azure SDK för Java kan du lära dig hur du ytterligare anpassar DEN HTTP-klient som du använder. Mer information finns i Konfigurera proxyservrar i Azure SDK för Java.