Partilhar via

Biblioteca compartilhada do Azure Core para Java – versão 1.45.0

  • Artigo

Documentação de build

O Azure Core fornece primitivos compartilhados, abstrações e auxiliares para bibliotecas de clientes modernas do SDK do Java do Azure. Essas bibliotecas seguem as Diretrizes de Design do SDK do Azure para Java e podem ser facilmente identificadas por nomes de pacotes que começam com com.azure e nomes de módulo começando com azure-, por exemplo, com.azure.storage.blobs seriam encontrados no /sdk/storage/azure-storage-blob diretório. Uma lista mais completa de bibliotecas de clientes usando o Azure Core pode ser encontrada aqui.

O Azure Core permite que as bibliotecas de clientes exponham a funcionalidade comum de forma consistente, para que, depois de aprender a usar essas APIs em uma biblioteca de clientes, você saiba como usá-las em outras bibliotecas de clientes.

Introdução

Pré-requisitos

Incluir o pacote

Incluir o arquivo da BOM

Inclua o azure-sdk-bom em seu projeto para assumir a dependência da versão ga (disponibilidade geral) da biblioteca. No trecho a seguir, substitua o espaço reservado {bom_version_to_target} pelo número de versão. Para saber mais sobre o BOM, consulte o BOM README do SDK do AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Depois, inclua a dependência direta na seção de dependências sem a marca de versão. Normalmente, você não precisará instalar ou depender do Azure Core, em vez disso, ele será baixado transitivamente pela ferramenta de build quando você depender das bibliotecas de clientes que a usam.

<dependencies>
    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-core</artifactId>
    </dependency>
</dependencies>

Incluir dependência direta

Se você quiser assumir a dependência de uma versão específica da biblioteca que não está presente no BOM, adicione a dependência direta ao seu projeto da seguinte maneira.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-core</artifactId>
    <version>1.45.0</version>
</dependency>

Principais conceitos

Os principais conceitos do Azure Core (e, portanto, todas as bibliotecas de clientes do Azure usando o Azure Core) incluem:

  • Configurando clientes de serviço, por exemplo, configurando repetições, registro em log etc. (HttpTrait<T>, ConfigurationTrait<T>etc.)
  • Acessando detalhes da resposta HTTP (Response<T>).
  • Chamando operações de longa execução (PollerFlux<T>).
  • Paginação e fluxos assíncronos (ContinuablePagedFlux<T>).
  • Exceções para relatar erros de solicitações de serviço de forma consistente.
  • Abstrações para representar credenciais do SDK do Azure.
  • Tempos limite de operação

Eles serão introduzidos por meio dos exemplos apresentados abaixo.

Exemplos

Acessando detalhes de resposta HTTP usando Response<T>

Os clientes de serviço têm métodos que chamam os serviços do Azure, chamamos esses métodos de serviço de métodos.

Os métodos de serviço podem retornar um tipo Response<T>compartilhado do Azure Core . Esse tipo fornece acesso ao resultado desserializado da chamada de serviço e aos detalhes da resposta HTTP retornada do servidor.

Pipelines HTTP com HttpPipeline

HttpPipeline é um constructo que contém uma lista das HttpPipelinePolicy quais são aplicadas a uma solicitação sequencialmente para prepará-la sendo enviada por um HttpClient.

Hierarquia de exceção com AzureException

AzureException é a exceção raiz na hierarquia usada no Azure Core. Exceções adicionais como HttpRequestException e HttpResponseException são usadas para reduzir o escopo dos motivos de exceção.

Paginação com ContinuablePagedFlux<T>

ContinuablePageFlux gerencia o envio de uma solicitação de página inicial para um serviço e a recuperação de páginas adicionais à medida que o consumidor solicita mais dados até que o consumidor termine o processamento ou todas as páginas tenham sido consumidas.

Operações de execução prolongada com PollerFlux<T>

PollerFlux gerencia o envio de uma solicitação de serviço inicial e a solicitação de atualizações de processamento em um intervalo de correção até que a sondagem seja cancelada ou atinja um estado terminal.

Configurando construtores

Os construtores são usados para criar clientes de serviço e algumas TokenCredential implementações. Eles podem ser configurados com uma variedade de opções, incluindo HttpPipeline e HttpClient para clientes baseados em HTTP e opções mais gerais, como Configuration eendpoint. Para permitir uma integração mais simples em estruturas como o Spring e permitir que métodos genéricos sejam usados para todos os construtores azure-core , fornece um conjunto de interfaces que podem ser implementadas para fornecer a funcionalidade necessária.

HttpTrait

HttpTrait<T> contém métodos para definir configurações de chave para clientes baseados em HTTP. Essa interface permitirá que você configure o HttpClient, HttpPipeline, HttpPipelinePolicys, RetryOptions, HttpLogOptionse ClientOptions (preferencialmente HttpClientOptions , pois é mais específico para clientes de serviço baseados em HTTP).

Para construtores que expõem HttpTrait<T>, se uma HttpPipeline ou HttpClient não estiver definida, uma instância padrão será criada com base nas configurações de classpath e na ClientOptions baseada no construtor. Isso poderá causar confusão se você estiver esperando um comportamento específico para seu cliente, como o uso de um proxy que não foi carregado do ambiente. Para evitar isso, é recomendável sempre definir o HttpPipeline ou HttpClient em todos os clientes se você estiver criando se suas configurações não forem baseadas no ambiente que executa o aplicativo.

Características de credencial

O Azure Core fornece credenciais diferentes para autenticação com os serviços do Azure. Cada tipo de credencial tem uma característica correspondente que pode ser implementada para fornecer a credencial ao construtor de clientes. A tabela a seguir lista os traços de credencial e o tipo de credencial correspondente.

Característica de credencial Tipo de Credencial
AzureKeyCredentialTrait AzureKeyCredential
AzureNamedKeyCredentialTrait AzureNamedKeyCredential
AzureSasCredentialTrait AzureSasCredential
ConnectionStringCredentialTrait String (não há nenhum tipo formal para cadeias de conexão)
KeyCredentialTrait KeyCredential
TokenCredentialTrait TokenCredential

ConfigurationTrait

ConfigurationTrait<T> permite a configuração Configuration em clientes de serviço. Configuration pode ser usado para passar um conjunto de comportamentos de runtime para o construtor de clientes, como como ProxyOptions são carregados do ambiente, passando implicitamente credenciais para alguns construtores de clientes que dão suporte a ele e muito mais.

EndpointTrait

EndpointTrait<T> permite definir o ponto de extremidade de serviço em clientes de serviço.

Tempos limite de operação

Os SDKs do Azure fornecem algumas maneiras consistentes de configurar tempos limite em chamadas à API. Cada tempo limite afeta um escopo diferente dos SDKs do Azure e do aplicativo de chamada.

Tempos limite de HTTP

Os tempos limite HTTP são o nível mais baixo de tempo limite que os SDKs do Azure fornecem. Esses tempos limite podem ser configurados ao criar HttpClients ou usar HttpClientOptions ao criar clientes de serviço sem configurar um HttpClient por conta própria. A tabela a seguir lista o tempo limite HTTP, o método correspondente HttpClientOptions que pode ser usado para defini-lo, a variável de ambiente para controlar o valor padrão, o valor padrão se o valor do ambiente não estiver definido e uma breve descrição dos efeitos do tempo limite.

Tempo limite HTTP HttpClientOptions Método Variável de ambiente Valor padrão Descrição
Connect Timeout setConnectTimeout(Duration) AZURE_REQUEST_CONNECT_TIMEOUT 10 segundos A quantidade de tempo para que uma conexão seja estabelecida antes de atingir o tempo limite.
Tempo limite de gravação setWriteTimeout(Duration) AZURE_REQUEST_WRITE_TIMEOUT 60 segundos A quantidade de tempo entre cada gravação de dados de solicitação na rede antes de atingir o tempo limite.
Tempo limite de resposta setResponseTimeout(Duration) AZURE_REQUEST_RESPONSE_TIMEOUT 60 segundos A quantidade de tempo entre terminar de enviar a solicitação para receber os primeiros bytes de resposta antes de atingir o tempo limite.
Tempo limite de leitura setReadTimeout(Duration) AZURE_REQUEST_READ_TIMEOUT 60 segundos A quantidade de tempo entre cada dado de resposta lido da rede antes de atingir o tempo limite.

Como esses tempos limite estão mais próximos da rede, se eles dispararem, eles serão propagados novamente por meio do HttpPipeline e geralmente deverão ser repetidos pelo RetryPolicy.

Tempos limite de HttpPipeline

Os tempos limite do HttpPipeline são o próximo nível de tempo limite que os SDKs do Azure fornecem. Esses tempos limite são configurados usando um HttpPipelinePolicy e configurando um tempo limite usando Mono.timeout para solicitações assíncronas ou com um ExecutorService tempo limite get(long, TimeUnit) para solicitações síncronas.

Dependendo do local dentro do HttpPipeline, esses tempos limite podem ser capturados pelo RetryPolicy e repetidos. Se a política de tempo limite for PER_RETRY (HttpPipelinePolicy.getPipelinePosition()) o tempo limite será capturado pelo RetryPolicy , pois ele será posicionado após o RetryPolicy, portanto, em seu escopo de captura, se ele estiver PER_CALL repetindo a solicitação precisará ser tratado pela lógica do aplicativo.

Tempos limite do cliente de serviço

Os tempos limite do cliente de serviço são o nível mais alto de tempo limite fornecido pelos SDKs do Azure. Esses tempos limite são configurados passando Duration timeout métodos de serviço síncronos que dão suporte a tempos limite ou usando Mono.timeout ou Flux.timeout em métodos de serviço assíncronos.

Como esses tempos limite estão na própria chamada à API, eles não podem ser capturados por nenhum mecanismo de repetição nos SDKs do Azure e devem ser tratados pela lógica do aplicativo.

Próximas etapas

Introdução às bibliotecas do Azure criadas usando o Azure Core.

Solução de problemas

Se você encontrar bugs, registre problemas por meio de Problemas do GitHub ou check-out do StackOverflow para o SDK do Java do Azure.

Habilitando o registro em log

Os SDKs do Azure para Java fornecem uma história de log consistente para ajudar a solucionar problemas de erros do aplicativo e agilizar a resolução. Os logs produzidos capturam o fluxo de um aplicativo antes que acessem o estado do terminal para ajudar a localizar o problema raiz. Veja a documentação de log para obter diretrizes sobre como habilitar o registro em log.

Registro em log de solicitação e resposta HTTP

O log de solicitação e resposta HTTP pode ser habilitado definindo HttpLogDetailLevel no HttpLogOptions usado para criar um cliente de serviço baseado em HTTP ou definindo a variável de ambiente ou a propriedade AZURE_HTTP_LOG_DETAIL_LEVELdo sistema . A tabela a seguir exibe as opções válidas para AZURE_HTTP_LOG_DETAIL_LEVEL e a HttpLogDetailLevel que ela se correlaciona (as opções válidas não diferenciam maiúsculas de minúsculas):

AZURE_HTTP_LOG_DETAIL_LEVEL valor HttpLogDetailLevel enum
basic HttpLogDetailLevel.BASIC
headers HttpLogDetailLevel.HEADERS
body HttpLogDetailLevel.BODY
body_and_headers HttpLogDetailLevel.BODY_AND_HEADERS
bodyandheaders HttpLogDetailLevel.BODY_AND_HEADERS

Todos os outros valores, ou valores sem suporte, resultam em HttpLogDetailLevel.NONE, ou desabilitado solicitação HTTP e log de resposta. O registro em log deve ser habilitado para registrar solicitações e respostas HTTP. O registro em log de cabeçalhos HTTP requer verbose que o registro em log seja habilitado. A tabela a seguir explica o que o registro em log está habilitado para cada HttpLogDetailLevel:

HttpLogDetailLevel valor Registro em log ativado
HttpLogDetailLevel.NONE Nenhuma solicitação HTTP ou registro em log de resposta
HttpLogDetailLevel.BASIC Método de solicitação HTTP, código de status de resposta e URL de solicitação e resposta
HttpLogDetailLevel.HEADERS Todos os cabeçalhos de HttpLogDetailLevel.BASIC solicitação e resposta e se o nível de log for verbose
HttpLogDetailLevel.BODY Todo o corpo da solicitação e da resposta se ele tiver menos de HttpLogDetailLevel.BASIC 10 KB de tamanho
HttpLogDetailLevel.BODY_AND_HEADERS Tudo de HttpLogDetailLevel.HEADERS e HttpLogDetailLevel.BODY

Participante

Para obter detalhes sobre como contribuir para esse repositório, consulte o guia de contribuição.

  1. Bifurcar
  2. Criar seu branch de recurso (git checkout -b my-new-feature)
  3. Confirmar suas alterações (git commit -am 'Add some feature')
  4. Enviar por push para o branch (git push origin my-new-feature)
  5. Criar nova solicitação de pull

Impressões