Client HTTP e pipeline nell'Azure SDK per Java

Articolo
01/20/2025

Questo articolo offre una panoramica dell'uso della funzionalità del client HTTP e della pipeline all'interno di Azure SDK per Java. Questa funzionalità offre un'esperienza coerente, potente e flessibile per gli sviluppatori che usano tutte le librerie di Azure SDK per Java.

Client HTTP

Azure SDK per Java viene implementato usando un'astrazione HttpClient. Questa astrazione consente un'architettura collegabile che accetta più librerie client HTTP o implementazioni personalizzate. Tuttavia, per semplificare la gestione delle dipendenze per la maggior parte degli utenti, tutte le librerie client di Azure dipendono da azure-core-http-netty. Di conseguenza, il client HTTP Netty è il client predefinito usato in tutte le librerie di Azure SDK per Java.

Anche se Netty è il client HTTP predefinito, l'SDK fornisce tre implementazioni client, a seconda delle dipendenze già presenti nel progetto. Queste implementazioni sono per:

Netty
OkHttp
HttpClient introdotto in JDK 11

Nota

Il HttpClient JDK in combinazione con Azure SDK per Java è supportato solo con JDK 12 e versioni successive.

Sostituire il client HTTP predefinito

Se si preferisce un'altra implementazione, è possibile rimuovere la dipendenza da Netty escludendola nei file di configurazione della build. In un file di pom.xml Maven si esclude la dipendenza Netty e si include un'altra dipendenza.

L'esempio seguente illustra come escludere la dipendenza Netty da una dipendenza reale dalla libreria azure-security-keyvault-secrets. Assicurati di escludere Netty da tutte le librerie com.azure appropriate, come mostrato qui.

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

Nota

Se si rimuove la dipendenza Netty ma non si specifica alcuna implementazione, l'applicazione non viene avviata. Un'implementazione di HttpClient deve esistere nel classpath.

Configurare i client HTTP

Quando crei un client di servizio, per impostazione predefinita viene utilizzato HttpClient.createDefault(). Questo metodo restituisce un'istanza di base HttpClient basata sull'implementazione del client HTTP fornita. Nel caso in cui sia necessario un client HTTP più complesso, ad esempio un proxy, ogni implementazione offre un generatore che consente di costruire un'istanza di HttpClient configurata. I costruttori sono NettyAsyncHttpClientBuilder, OkHttpAsyncHttpClientBuildere JdkAsyncHttpClientBuilder.

Gli esempi seguenti illustrano come compilare HttpClient istanze usando Netty, OkHttp e il client HTTP JDK 11. Queste istanze fanno il proxy tramite http://localhost:3128 ed eseguono l'autenticazione con l'utente example e la password 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();

È ora possibile passare l'istanza di HttpClient costruita in un generatore di client del servizio per usarla come client per la comunicazione con il servizio. L'esempio seguente usa la nuova istanza di HttpClient per creare un client di archiviazione blob di Azure.

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

Per le librerie di gestione, è possibile impostare il HttpClient durante la configurazione di Manager.

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

Pipeline HTTP

La pipeline HTTP è uno dei componenti chiave per ottenere coerenza e diagnosbilità nelle librerie client Java per Azure. Una pipeline HTTP è costituita da:

Trasporto HTTP
Politiche della pipeline HTTP

È possibile fornire una pipeline HTTP personalizzata durante la creazione di un client. Se non si fornisce una pipeline, la libreria client ne crea una configurata per l'uso con tale libreria client specifica.

Trasporto HTTP

Il trasporto HTTP è responsabile della connessione al server e dell'invio e della ricezione di messaggi HTTP. Il trasporto HTTP costituisce il gateway per le librerie client di Azure SDK per interagire con i servizi di Azure. Come indicato in precedenza in questo articolo, Azure SDK per Java utilizza per impostazione predefinita Netty per il trasporto HTTP. Tuttavia, l'SDK fornisce anche un trasporto HTTP collegabile, in modo da poter usare altre implementazioni, se appropriato. L'SDK fornisce anche altre due implementazioni di trasporto HTTP per OkHttp e il client HTTP fornito con JDK 11 e versioni successive.

Politiche della pipeline HTTP

Una pipeline è costituita da una sequenza di passaggi eseguiti per ogni ciclo di richiesta/risposta HTTP. Ogni criterio ha uno scopo specifico e agisce su una richiesta, su una risposta o, a volte, su entrambe. Poiché tutte le librerie dei client hanno un livello "Azure Core" standard, questo livello garantisce che ogni politica venga eseguita in ordine nella pipeline. Quando si invia una richiesta, le politiche vengono eseguite nell'ordine in cui vengono aggiunte alla pipeline. Quando si riceve una risposta dal servizio, le politiche vengono eseguite nell'ordine inverso. Tutti i criteri aggiunti alla pipeline vengono eseguiti prima di inviare la richiesta e dopo aver ricevuto una risposta. Il criterio deve decidere se agire sulla richiesta, sulla risposta o su entrambi. Ad esempio, un criterio di registrazione registra la richiesta e la risposta, ma il criterio di autenticazione è interessato solo a modificare la richiesta.

Il framework di Azure Core fornisce i criteri con i dati di richiesta e risposta necessari insieme a qualsiasi contesto necessario per eseguire i criteri. La politica può quindi eseguire la sua operazione con i dati specificati e passare il controllo alla politica successiva nella pipeline.

diagramma della pipeline HTTP

Posizione dei criteri della pipeline HTTP

Quando si effettuano richieste HTTP ai servizi cloud, è importante gestire gli errori temporanei e ripetere i tentativi non riusciti. Poiché questa funzionalità è un requisito comune, Azure Core fornisce un criterio di ripetizione dei tentativi in grado di controllare gli errori temporanei e ripetere automaticamente la richiesta.

Questo criterio di ripetizione dei tentativi suddivide quindi l'intera pipeline in due parti: i criteri eseguiti prima del criterio di ripetizione dei tentativi e dei criteri eseguiti dopo il criterio di ripetizione dei tentativi. I criteri aggiunti prima dei criteri di ritentativo vengono eseguiti una sola volta per ogni operazione API, mentre i criteri aggiunti dopo i criteri di ritentativo vengono eseguiti tante volte quanti sono i tentativi.

Pertanto, quando si compila la pipeline HTTP, è necessario capire se eseguire un criterio per ogni tentativo di richiesta o una volta per ogni operazione API.

Criteri comuni della pipeline HTTP

Le pipeline HTTP per i servizi basati su REST hanno configurazioni con criteri per l'autenticazione, i tentativi, la registrazione, la telemetria e l'ID della richiesta nell'intestazione. Azure Core viene precaricato con questi criteri HTTP comunemente richiesti che è possibile aggiungere alla pipeline.

Politica	Collegamento a GitHub
politica di ripetizione dei tentativi	RetryPolicy.java
criteri di autenticazione	BearerTokenAuthenticationPolicy.java
politica di registrazione	HttpLoggingPolicy.java
politica ID richiesta	RequestIdPolicy.java
criteri di telemetria	UserAgentPolicy.java

Politica della pipeline HTTP personalizzata

I criteri della pipeline HTTP forniscono un meccanismo pratico per modificare o decorare la richiesta e la risposta. È possibile aggiungere criteri personalizzati alla pipeline creata dall'utente o dallo sviluppatore della libreria client. Quando si aggiunge la policy alla pipeline, è possibile specificare se essa deve essere eseguita per ogni chiamata o per tentativo.

Per creare un criterio di pipeline HTTP personalizzato, è sufficiente estendere un tipo di criteri di base e implementare un metodo astratto. È quindi possibile collegare i criteri alla pipeline.

Intestazioni HTTP personalizzate nelle richieste

Le librerie client di Azure SDK per Java offrono un modo coerente per definire intestazioni personalizzate tramite oggetti Context nella API pubblica, come illustrato nell'esempio seguente:

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

Per ulteriori informazioni, consultare la classe AddHeadersFromContextPolicy.

Libreria TLS/SSL predefinita

Per impostazione predefinita, tutte le librerie client usano la libreria Tomcat-native BoringSSL per abilitare prestazioni a livello nativo nelle operazioni TLS/SSL. La libreria SSL boring è un file JAR uber contenente librerie native per Linux, macOS e Windows e offre prestazioni migliori rispetto all'implementazione TLS/SSL predefinita all'interno di JDK.

Ridurre le dimensioni delle dipendenze TLS/SSL Tomcat-Native

Per impostazione predefinita, il file JAR uber della libreria SSL boring Tomcat-Native viene usato negli SDK di Azure per Java. Per ridurre le dimensioni di questa dipendenza, è necessario includere la dipendenza con un classificatore os secondo netty-tcnative , come illustrato nell'esempio seguente:

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

Usare JDK TLS/SSL

Se si preferisce usare il JDK TLS/SSL predefinito anziché Tomcat-Native BoringSSL, è necessario escludere la libreria BoringSSL nativa di Tomcat. Tenere presente che, in base ai nostri test, le prestazioni del JDK TLS/SSL sono del 30%% più lente rispetto a Tomcat-Native Boring SSL. Quando si utilizza com.azure:azure-core:1.28.0 o una versione successiva, la libreria di implementazione HttpClient(ad esempio com.azure:azure-core-http-netty) gestisce la dipendenza da Boring SSL di Tomcat-Native. Per escludere la dipendenza, aggiungere la configurazione seguente al file POM:

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

Passaggi successivi

Ora che hai familiarità con la funzionalità client HTTP nell'Azure SDK per Java, impara come personalizzare ulteriormente il client HTTP che stai utilizzando. Per ulteriori informazioni, vedere Configurazione dei proxy nell'SDK Azure per Java.

Condividi tramite