Clientes HTTP e pipelines no SDK do Azure para Java

Este artigo fornece uma visão geral do uso do cliente HTTP e da funcionalidade de pipeline no SDK do Azure para Java. Essa funcionalidade fornece uma experiência consistente, poderosa e flexível para desenvolvedores que usam todas as bibliotecas do SDK do Azure para Java.

Clientes HTTP

O SDK do Azure para Java é implementado usando uma abstração HttpClient. Essa abstração permite uma arquitetura conectável que aceita várias bibliotecas de cliente HTTP ou implementações personalizadas. No entanto, para simplificar a gestão de dependências para a maioria dos usuários, todas as bibliotecas de cliente do Azure dependem de azure-core-http-netty. Como tal, o cliente HTTP Netty é o cliente padrão usado em todas as bibliotecas do SDK do Azure para Java.

Embora Netty seja o cliente HTTP padrão, o SDK fornece três implementações de cliente, dependendo de quais dependências você já tem em seu projeto. Estas implementações destinam-se a:

• Netty
• OkHttp
• HttpClient introduzido no JDK 11

Substitua o cliente HTTP padrão

Se preferir outra implementação, você pode remover a dependência do Netty excluindo-a nos arquivos de configuração de compilação. Em um arquivo pom.xml Maven, você exclui a dependência Netty e inclui outra dependência.

O exemplo a seguir mostra como excluir a dependência Netty de uma dependência real na biblioteca azure-security-keyvault-secrets. Certifique-se de excluir o Netty de todas as bibliotecas de com.azure apropriadas, conforme mostrado aqui:

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

Configurar clientes HTTP

Quando você cria um cliente de serviço, o padrão é usar HttpClient.createDefault(). Esse método retorna uma instância HttpClient básica com base na implementação do cliente HTTP fornecido. Caso você precise de um cliente HTTP mais complexo, como um proxy, cada implementação oferece um construtor que permite construir uma instância HttpClient configurada. Os construtores são NettyAsyncHttpClientBuilder, OkHttpAsyncHttpClientBuildere JdkAsyncHttpClientBuilder.

Os exemplos a seguir mostram como criar instâncias HttpClient usando Netty, Okhttp e o cliente HTTP JDK 11. Essas instâncias funcionam como proxy através de http://localhost:3128 e autenticam com o utilizador example com a senha 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();

Agora pode passar a instância HttpClient construída para um criador de clientes de serviço, para ser usada como cliente na comunicação com o serviço. O exemplo a seguir usa a nova instância HttpClient para criar um cliente de Blob de Armazenamento do Azure.

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

Para bibliotecas de gerenciamento, você pode definir o HttpClient durante a configuração do Manager.

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

Pipeline HTTP

O pipeline HTTP é um dos principais componentes para obter consistência e capacidade de diagnóstico nas bibliotecas de cliente Java para Azure. Um pipeline HTTP é composto por:

• Um transporte HTTP
• Políticas de Pipelines HTTP

Você pode fornecer seu próprio pipeline HTTP personalizado ao criar um cliente. Se você não fornecer um pipeline, a biblioteca de cliente criará uma configurada para trabalhar com essa biblioteca de cliente específica.

Transporte HTTP

O transporte HTTP é responsável por estabelecer a conexão com o servidor e enviar e receber mensagens HTTP. O transporte HTTP forma o gateway para as bibliotecas de cliente do SDK do Azure interagirem com os serviços do Azure. Conforme observado anteriormente neste artigo, o SDK do Azure para Java usa o Netty por padrão para seu transporte HTTP. No entanto, o SDK também fornece um transporte HTTP conectável para que você possa usar outras implementações quando apropriado. O SDK também fornece mais duas implementações de transporte HTTP para OkHttp e o cliente HTTP fornecido com o JDK 11 e posterior.

Políticas de canalização HTTP

Um pipeline consiste numa sequência de etapas executadas para cada ciclo de solicitação-resposta HTTP. Cada política tem um objetivo específico e atua de acordo com um pedido ou uma resposta ou, por vezes, ambos. Como todas as bibliotecas de cliente têm uma camada padrão 'Azure Core', essa camada garante que cada política seja executada em ordem no pipeline. Quando você envia uma solicitação, as políticas são executadas na ordem em que são adicionadas ao pipeline. Quando você recebe uma resposta do serviço, as políticas são executadas na ordem inversa. Todas as políticas adicionadas ao pipeline são executadas antes de enviar a solicitação e depois de receber uma resposta. A política tem de decidir se deve dar seguimento ao pedido, à resposta ou a ambos. Por exemplo, uma política de registo regista a solicitação e a resposta, mas a política de autenticação visa apenas modificar a solicitação.

A estrutura do Azure Core fornece à política os dados de solicitação e resposta necessários, juntamente com qualquer contexto necessário para executar a política. A política pode então executar a operação com os dados fornecidos e passar o controlo para a próxima política na linhagem.

Posição da política de canalização HTTP

Quando você faz solicitações HTTP para serviços de nuvem, é importante lidar com falhas transitórias e tentar novamente tentativas falhadas. Como essa funcionalidade é um requisito comum, o Azure Core fornece uma política de repetição que pode observar falhas transitórias e repetir automaticamente a solicitação.

Essa política de repetição, portanto, divide todo o pipeline em duas partes: políticas que são executadas antes da política de repetição e políticas que são executadas após a política de nova tentativa. As políticas adicionadas antes da política de repetição são executadas apenas uma vez por operação de API, e as políticas adicionadas após a política de repetição são executadas tantas vezes quanto as tentativas.

Portanto, ao criar o pipeline HTTP, você deve entender se deve executar uma política para cada nova tentativa de solicitação ou uma vez por operação de API.

Políticas comuns de pipeline HTTP

Os pipelines HTTP para serviços baseados em REST têm configurações com políticas para autenticação, tentativas, registro, telemetria e especificação da ID da solicitação no cabeçalho. O Azure Core é pré-carregado com essas políticas HTTP comumente necessárias que você pode adicionar ao pipeline.

Política de canalização HTTP personalizada

A política de pipeline HTTP fornece um mecanismo conveniente para modificar ou decorar a solicitação e a resposta. Você pode adicionar políticas personalizadas ao pipeline que o usuário ou o desenvolvedor da biblioteca de cliente criou. Ao adicionar a política ao pipeline, você pode especificar se essa política deve ser executada por chamada ou por nova tentativa.

Para criar uma política de pipeline HTTP personalizada, basta estender um tipo de política base e implementar algum método abstrato. Em seguida, você pode conectar a política ao pipeline.

Cabeçalhos personalizados em solicitações HTTP

O SDK do Azure para bibliotecas de cliente Java fornece uma maneira consistente de definir cabeçalhos personalizados por meio de objetos Context na API pública, conforme mostrado no exemplo a seguir:

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

Para obter mais informações, consulte o AddHeadersFromContextPolicy Class.

Biblioteca TLS/SSL padrão

Todas as bibliotecas de cliente, por padrão, usam a biblioteca Boring SSL nativa do Tomcat para habilitar o desempenho de nível nativo para operações TLS/SSL. A biblioteca Boring SSL é um uber JAR contendo bibliotecas nativas para Linux, macOS e Windows, e fornece melhor desempenho em comparação com a implementação padrão de TLS/SSL dentro do JDK.

Reduzir o tamanho da dependência Tomcat-Native TLS/SSL

Por padrão, o uber JAR da biblioteca SSL Tomcat-Native Boring é usado nos SDKs do Azure para Java. Para reduzir o tamanho desta dependência, é necessário incluir a dependência com o classificador os, de acordo com netty-tcnative , como mostrado no exemplo seguinte:

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

Utilize o JDK para TLS/SSL

Se você preferir usar o padrão JDK TLS/SSL em vez de Tomcat-Native Boring SSL, então você precisa excluir a biblioteca Boring SSL nativa do Tomcat. Esteja ciente de que, com base em nossos testes, o desempenho do JDK TLS/SSL é 30% mais lento em comparação com Tomcat-Native Boring SSL. Quando se usa o com.azure:azure-core:1.28.0 ou versões posteriores, a biblioteca de HttpClient(como a com.azure:azure-core-http-netty) gere a dependência do Tomcat-Native Boring SSL. Para excluir a dependência, adicione a seguinte configuração ao arquivo 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>

Próximos passos

Agora que você está familiarizado com a funcionalidade do cliente HTTP no SDK do Azure para Java, saiba como personalizar ainda mais o cliente HTTP que você está usando. Para obter mais informações, consulte Configurar proxies no SDK do Azure para Java.