Share via

Client HTTP e pipeline in Azure SDK per Java

  • Articolo

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:

Nota

JDK HttpClient 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 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 azure-security-keyvault-secrets libreria. Assicurarsi di escludere Netty da tutte le librerie appropriate com.azure , come illustrato di seguito:

<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 HttpClient deve esistere nel classpath.

Configurare i client HTTP

Quando si compila un client del servizio, per impostazione predefinita si usa 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 configurata HttpClient . I generatori sono NettyAsyncHttpClientBuilder, OkHttpAsyncHttpClientBuildere JdkAsyncHttpClientBuilder.

Gli esempi seguenti illustrano come compilare HttpClient istanze usando Netty, OkHttp e il client HTTP JDK 11. Queste istanze proxyno tramite http://localhost:3128 e eseguono l'autenticazione con l'esempio utente con 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 costruita HttpClient in un generatore di client del servizio da usare come client per la comunicazione con il servizio. Nell'esempio seguente viene usata la nuova HttpClient istanza per compilare un client BLOB Archiviazione di Azure.

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

Per le librerie di gestione, è possibile impostare durante la HttpClient 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
  • Criteri 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 usa Netty per impostazione predefinita 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.

Criteri della pipeline HTTP

Una pipeline è costituita da una sequenza di passaggi eseguiti per ogni round trip di richiesta-risposta HTTP. Ogni criterio ha uno scopo dedicato e agisce su una richiesta o una risposta o a volte entrambi. Poiché tutte le librerie client hanno un livello "Azure Core" standard, questo livello garantisce che ogni criterio venga eseguito in ordine nella pipeline. Quando si invia una richiesta, i criteri vengono eseguiti nell'ordine in cui vengono aggiunti alla pipeline. Quando si riceve una risposta dal servizio, i criteri vengono eseguiti 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. I criteri possono quindi eseguire l'operazione con i dati specificati e passare il controllo al criterio successivo nella pipeline.

HTTP pipeline diagram

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 dell'esecuzione dei criteri di ripetizione dei tentativi vengono eseguiti una sola volta per ogni operazione API e i criteri aggiunti dopo l'esecuzione dei criteri di ripetizione dei tentativi vengono eseguiti ogni volta che vengono eseguiti 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 richiesta nell'intestazione. Azure Core viene precaricato con questi criteri HTTP comunemente richiesti che è possibile aggiungere alla pipeline.

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

Criteri della pipeline HTTP personalizzati

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 aggiungono i criteri alla pipeline, è possibile specificare se questo criterio deve essere eseguito 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 personalizzate nelle richieste HTTP

Le librerie client di Azure SDK per Java offrono un modo coerente per definire intestazioni personalizzate tramite Context oggetti nell'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 altre informazioni, vedere la classe AddHeadersFromContextPolicy.

Libreria TLS/SSL predefinita

Per impostazione predefinita, tutte le librerie client usano la libreria SSL Boring nativa tomcat per abilitare le prestazioni a livello nativo per le 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 native di Tomcat

Per impostazione predefinita, il file JAR uber della libreria SSL Tomcat-Native Boring viene usato negli SDK di Azure per Java. Per ridurre le dimensioni di questa dipendenza, è necessario includere la dipendenza con un os classificatore in base a 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 TLS/SSL JDK

Se si preferisce usare il protocollo SSL/TLS/SSL JDK predefinito anziché Tomcat-Native Boring SSL, è necessario escludere la libreria SSL Boring nativa di Tomcat. Tenere presente che, in base ai test, le prestazioni di TLS/SSL JDK sono del 30% più lente rispetto a Tomcat-Native Boring SSL. Quando si usa com.azure:azure-core:1.28.0 o versioni successive, la HttpClientlibreria di implementazione (ad esempio com.azure:azure-core-http-netty) gestisce la dipendenza da Tomcat-Native Boring SSL. 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 si ha familiarità con la funzionalità client HTTP in Azure SDK per Java, vedere come personalizzare ulteriormente il client HTTP in uso. Per altre informazioni, vedere Configurare i proxy in Azure SDK per Java.