HTTP-clients en -pijplijnen in de Azure SDK voor Java

Artikel
10/23/2023

Dit artikel bevat een overzicht van het gebruik van de HTTP-client- en pijplijnfunctionaliteit in de Azure SDK voor Java. Deze functionaliteit biedt een consistente, krachtige en flexibele ervaring voor ontwikkelaars die gebruikmaken van alle Azure SDK voor Java-bibliotheken.

HTTP-clients

De Azure SDK voor Java wordt geïmplementeerd met behulp van een HttpClient abstractie. Deze abstractie maakt een pluggable architectuur mogelijk die meerdere HTTP-clientbibliotheken of aangepaste implementaties accepteert. Om afhankelijkheidsbeheer voor de meeste gebruikers te vereenvoudigen, zijn alle Azure-clientbibliotheken afhankelijk van azure-core-http-netty. Als zodanig is de Netty HTTP-client de standaardclient die wordt gebruikt in alle Azure SDK voor Java-bibliotheken.

Hoewel Netty de standaard-HTTP-client is, biedt de SDK drie client-implementaties, afhankelijk van de afhankelijkheden die u al in uw project hebt. Deze implementaties zijn bedoeld voor:

Netty
OkHttp
HttpClient geïntroduceerd in JDK 11

Notitie

De JDK HttpClient in combinatie met de Azure SDK voor Java wordt alleen ondersteund met JDK 12 en hoger.

De standaard-HTTP-client vervangen

Als u liever een andere implementatie gebruikt, kunt u de afhankelijkheid van Netty verwijderen door deze uit te sluiten in de buildconfiguratiebestanden. In een Maven pom.xml-bestand sluit u de Netty-afhankelijkheid uit en neemt u een andere afhankelijkheid op.

In het volgende voorbeeld ziet u hoe u de Netty-afhankelijkheid kunt uitsluiten van een echte afhankelijkheid van de azure-security-keyvault-secrets bibliotheek. Zorg ervoor dat u Netty uitsluit van alle geschikte com.azure bibliotheken, zoals hier wordt weergegeven:

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

Notitie

Als u de Netty-afhankelijkheid verwijdert, maar geen implementatie op de locatie opgeeft, kan de toepassing niet worden gestart. Er moet een HttpClient implementatie aanwezig zijn op het klassepad.

HTTP-clients configureren

Wanneer u een serviceclient bouwt, wordt deze standaard gebruikt HttpClient.createDefault(). Deze methode retourneert een basisexemplementatie HttpClient op basis van de opgegeven HTTP-client-implementatie. Als u een complexere HTTP-client nodig hebt, zoals een proxy, biedt elke implementatie een opbouwfunctie waarmee u een geconfigureerd HttpClient exemplaar kunt maken. De bouwers zijn NettyAsyncHttpClientBuilder, OkHttpAsyncHttpClientBuilderen JdkAsyncHttpClientBuilder.

In de volgende voorbeelden ziet u hoe u exemplaren bouwt HttpClient met Behulp van Netty, OkHttp en de JDK 11 HTTP-client. Deze exemplaren proxy via http://localhost:3128 en verifiëren met gebruikersvoorbeeldmet wachtwoord 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();

U kunt het samengestelde HttpClient exemplaar nu doorgeven aan een serviceclientbouwer voor gebruik als de client voor communicatie met de service. In het volgende voorbeeld wordt het nieuwe HttpClient exemplaar gebruikt om een Azure Storage Blob-client te bouwen.

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

Voor beheerbibliotheken kunt u de HttpClient configuratie van Manager instellen.

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

HTTP-pijplijn

De HTTP-pijplijn is een van de belangrijkste onderdelen voor het bereiken van consistentie en diagnosebaarheid in de Java-clientbibliotheken voor Azure. Een HTTP-pijplijn bestaat uit:

Een HTTP-transport
HTTP-pijplijnbeleid

U kunt uw eigen aangepaste HTTP-pijplijn opgeven bij het maken van een client. Als u geen pijplijn opgeeft, maakt de clientbibliotheek er een die is geconfigureerd voor gebruik met die specifieke clientbibliotheek.

HTTP-transport

Het HTTP-transport is verantwoordelijk voor het tot stand brengen van de verbinding met de server en het verzenden en ontvangen van HTTP-berichten. Het HTTP-transport vormt de gateway voor de Azure SDK-clientbibliotheken om te communiceren met Azure-services. Zoals eerder in dit artikel is vermeld, maakt de Azure SDK voor Java standaard gebruik van Netty voor het HTTP-transport. De SDK biedt echter ook een pluggable HTTP-transport, zodat u waar nodig andere implementaties kunt gebruiken. De SDK biedt ook twee http-transport-implementaties voor OkHttp en de HTTP-client die wordt geleverd met JDK 11 en hoger.

HTTP-pijplijnbeleid

Een pijplijn bestaat uit een reeks stappen die worden uitgevoerd voor elke roundtrip met HTTP-aanvraagreacties. Elk beleid heeft een specifiek doel en handelt op een aanvraag of een antwoord of soms beide. Omdat alle clientbibliotheken een standaardlaag 'Azure Core' hebben, zorgt deze laag ervoor dat elk beleid op volgorde in de pijplijn wordt uitgevoerd. Wanneer u een aanvraag verzendt, worden de beleidsregels uitgevoerd in de volgorde waarin ze aan de pijplijn worden toegevoegd. Wanneer u een reactie van de service ontvangt, worden de beleidsregels uitgevoerd in de omgekeerde volgorde. Alle beleidsregels die aan de pijplijn worden toegevoegd, worden uitgevoerd voordat u de aanvraag verzendt en nadat u een antwoord hebt ontvangen. Het beleid moet beslissen of er actie moet worden uitgevoerd op de aanvraag, het antwoord of beide. Een logboekregistratiebeleid registreert bijvoorbeeld de aanvraag en het antwoord, maar het verificatiebeleid is alleen geïnteresseerd in het wijzigen van de aanvraag.

Het Azure Core-framework biedt het beleid de benodigde aanvraag- en antwoordgegevens, samen met de benodigde context om het beleid uit te voeren. Het beleid kan vervolgens de bewerking uitvoeren met de opgegeven gegevens en het besturingselement doorgeven aan het volgende beleid in de pijplijn.

HTTP pipeline diagram

Positie van HTTP-pijplijnbeleid

Wanneer u HTTP-aanvragen naar cloudservices doet, is het belangrijk om tijdelijke fouten af te handelen en mislukte pogingen opnieuw uit te voeren. Omdat deze functionaliteit een algemene vereiste is, biedt Azure Core een beleid voor opnieuw proberen waarmee tijdelijke fouten kunnen worden gecontroleerd en de aanvraag automatisch opnieuw kan worden uitgevoerd.

Dit beleid voor opnieuw proberen splitst de hele pijplijn daarom in twee delen: beleidsregels die worden uitgevoerd vóór het beleid voor opnieuw proberen en beleidsregels die worden uitgevoerd na het beleid voor opnieuw proberen. Beleidsregels die zijn toegevoegd voordat het beleid voor opnieuw proberen slechts eenmaal per API-bewerking wordt uitgevoerd en beleidsregels die zijn toegevoegd nadat het beleid voor opnieuw proberen zo vaak wordt uitgevoerd als de nieuwe pogingen.

Bij het bouwen van de HTTP-pijplijn moet u dus weten of u een beleid wilt uitvoeren voor elke aanvraag opnieuw proberen of één keer per API-bewerking.

Algemeen HTTP-pijplijnbeleid

HTTP-pijplijnen voor REST-services hebben configuraties met beleid voor verificatie, nieuwe pogingen, logboekregistratie, telemetrie en het opgeven van de aanvraag-id in de header. Azure Core wordt vooraf geladen met deze vaak vereiste HTTP-beleidsregels die u aan de pijplijn kunt toevoegen.

Beleid	GitHub-koppeling
beleid voor opnieuw proberen	RetryPolicy.java
verificatiebeleid	BearerTokenAuthenticationPolicy.java
logboekregistratiebeleid	HttpLoggingPolicy.java
beleid voor aanvraag-id's	RequestIdPolicy.java
telemetriebeleid	UserAgentPolicy.java

Aangepast HTTP-pijplijnbeleid

Het HTTP-pijplijnbeleid biedt een handig mechanisme om de aanvraag en het antwoord te wijzigen of te verfraaien. U kunt aangepast beleid toevoegen aan de pijplijn die de gebruiker of de clientbibliotheekontwikkelaar heeft gemaakt. Wanneer u het beleid aan de pijplijn toevoegt, kunt u opgeven of dit beleid per aanroep of per nieuwe poging moet worden uitgevoerd.

Als u een aangepast HTTP-pijplijnbeleid wilt maken, kunt u een basisbeleidstype uitbreiden en een abstracte methode implementeren. Vervolgens kunt u het beleid aansluiten op de pijplijn.

Aangepaste headers in HTTP-aanvragen

De Azure SDK voor Java-clientbibliotheken bieden een consistente manier om aangepaste headers te definiëren via Context objecten in de openbare API, zoals wordt weergegeven in het volgende voorbeeld:

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

Zie de klasse AddHeadersFromContextPolicy voor meer informatie.

Standaard-TLS/SSL-bibliotheek

Alle clientbibliotheken gebruiken standaard de systeemeigen Boring SSL-bibliotheek van Tomcat om prestaties op systeemeigen niveau in te schakelen voor TLS/SSL-bewerkingen. De Boring SSL-bibliotheek is een uber JAR met systeemeigen bibliotheken voor Linux, macOS en Windows, en biedt betere prestaties in vergelijking met de standaard TLS/SSL-implementatie binnen de JDK.

De grootte van tomcat-native TLS/SSL-afhankelijkheid verkleinen

Standaard wordt de uber JAR van de Tomcat-Native Boring SSL-bibliotheek gebruikt in Azure SDK's voor Java. Als u de grootte van deze afhankelijkheid wilt verkleinen, moet u de afhankelijkheid opnemen met een os classificatie volgens netty-tcnative, zoals wordt weergegeven in het volgende voorbeeld:

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

Als u liever de standaard JDK TLS/SSL gebruikt in plaats van Tomcat-Native Boring SSL, moet u de Tomcat-native Boring SSL-bibliotheek uitsluiten. Houd er rekening mee dat, op basis van onze tests, de prestaties van JDK TLS/SSL 30% langzamer zijn dan Tomcat-Native Boring SSL. Wanneer u de implementatiebibliotheek (zoalscom.azure:azure-core-http-netty) gebruikt com.azure:azure-core:1.28.0 of hoger, HttpClientwordt de afhankelijkheid van Tomcat-Native Boring SSL beheerd. Als u de afhankelijkheid wilt uitsluiten, voegt u de volgende configuratie toe aan uw POM-bestand:

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

Volgende stappen

Nu u bekend bent met http-clientfunctionaliteit in de Azure SDK voor Java, leert u hoe u de HTTP-client die u gebruikt verder kunt aanpassen. Zie Proxy's configureren in de Azure SDK voor Java voor meer informatie.

Delen via