Compartir a través de

Biblioteca compartida de Azure Core para Java: versión 1.45.0

  • Artículo

Documentación de compilación

Azure Core proporciona primitivos compartidos, abstracciones y asistentes para bibliotecas cliente modernas del SDK de Azure para Java. Estas bibliotecas siguen las directrices de diseño del SDK de Azure para Java y se pueden identificar fácilmente mediante nombres de paquete que empiezan por com.azure los nombres de módulo y a partir azure-de , por ejemplo com.azure.storage.blobs , se encuentran en el /sdk/storage/azure-storage-blob directorio . Puede encontrar una lista más completa de las bibliotecas cliente que usan Azure Core aquí.

Azure Core permite que las bibliotecas cliente expongan la funcionalidad común de forma coherente, de modo que, una vez que aprenda a usar estas API en una biblioteca cliente, sabrá cómo usarlas en otras bibliotecas cliente.

Introducción

Requisitos previos

Inclusión del paquete

Inclusión del archivo BOM

Incluya azure-sdk-bom en el proyecto para depender de la versión de disponibilidad general (GA) de la biblioteca. En el fragmento de código siguiente, reemplace el marcador de posición {bom_version_to_target} por el número de versión. Para más información sobre la lista de materiales, consulte el archivo Léame bom del SDK de 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>

y, luego, incluya la dependencia directa en la sección de dependencias sin la etiqueta de versión. Normalmente, no es necesario instalar ni depender de Azure Core, sino que se descargará transitivamente mediante la herramienta de compilación cuando dependa de las bibliotecas cliente que lo usen.

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

Inclusión de dependencias directas

Si desea depender de una versión determinada de la biblioteca que no está presente en la lista de materiales, agregue la dependencia directa al proyecto como se indica a continuación.

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

Conceptos clave

Los conceptos clave de Azure Core (y, por tanto, todas las bibliotecas cliente de Azure que usan Azure Core) incluyen:

  • Configuración de clientes de servicio, por ejemplo, configuración de reintentos, registro, etc. (HttpTrait<T>, ConfigurationTrait<T>, etc.)
  • Acceso a los detalles de respuesta HTTP (Response<T>).
  • Llamar a operaciones de larga duración (PollerFlux<T>).
  • Paginación y secuencias asincrónicas (ContinuablePagedFlux<T>).
  • Excepciones para notificar errores de solicitudes de servicio de forma coherente.
  • Abstracciones para representar las credenciales del SDK de Azure.
  • Tiempos de espera de la operación

Estos se introducirán por medio de los ejemplos que se presentan a continuación.

Ejemplos

Acceso a los detalles de respuesta HTTP mediante Response<T>

Los clientes de servicio tienen métodos que llaman a los servicios de Azure, nos referimos a estos métodos de servicio.

Los métodos de servicio pueden devolver un tipo Response<T>compartido de Azure Core. Este tipo proporciona acceso al resultado deserializado de la llamada de servicio y a los detalles de la respuesta HTTP devuelta desde el servidor.

Canalizaciones HTTP con HttpPipeline

HttpPipelinees una construcción que contiene una lista de HttpPipelinePolicy las cuales se aplican a una solicitud secuencialmente para prepararla enviada por .HttpClient

Jerarquía de excepciones con AzureException

AzureException es la excepción raíz de la jerarquía usada en Azure Core. Se usan excepciones adicionales como HttpRequestException y HttpResponseException para reducir el ámbito de los motivos de excepción.

Paginación con ContinuablePagedFlux<T>

ContinuablePageFlux administra el envío de una solicitud de página inicial a un servicio y la recuperación de páginas adicionales a medida que el consumidor solicita más datos hasta que el consumidor finaliza el procesamiento o se han consumido todas las páginas.

Operaciones de larga duración con PollerFlux<T>

PollerFlux administra el envío de una solicitud de servicio inicial y la solicitud de actualizaciones de procesamiento en un intervalo de corrección hasta que se cancela el sondeo o alcanza un estado terminal.

Configuración de generadores

Los generadores se usan para crear clientes de servicio y algunas TokenCredential implementaciones. Se pueden configurar con una variedad de opciones, incluidas HttpPipeline y HttpClient para clientes basados en HTTP y opciones más generales, como Configuration yendpoint . Para permitir una integración más sencilla en marcos como Spring y permitir que se usen métodos genéricos para todos los generadores azure-core proporciona un conjunto de interfaces que se pueden implementar para proporcionar la funcionalidad necesaria.

HttpTrait

HttpTrait<T> contiene métodos para establecer configuraciones de clave para clientes basados en HTTP. Esta interfaz le permitirá configurar los , , s, HttpLogOptionsRetryOptions, y ClientOptions (preferiblementeHttpClientOptions, ya que es más específico para los clientes de servicio basados en HTTP). HttpPipelinePolicyHttpPipelineHttpClient

En el caso de los generadores que exponen HttpTrait<T>, si o HttpPipelineHttpClient no se establece una instancia predeterminada, se creará en función de las configuraciones de ruta de clase y en función ClientOptions del generador. Esto puede causar confusión si espera un comportamiento específico para el cliente, como el uso de un proxy que no se cargó desde el entorno. Para evitar esto, se recomienda establecer siempre o HttpPipelineHttpClient en todos los clientes si está compilando si las configuraciones no se basan en el entorno que ejecuta la aplicación.

Rasgos de credenciales

Azure Core proporciona credenciales diferentes para la autenticación con servicios de Azure. Cada tipo de credencial tiene un rasgo correspondiente que se puede implementar para proporcionar la credencial al generador de clientes. En la tabla siguiente se enumeran los rasgos de credencial y el tipo de credencial correspondiente.

Rasgo de credencial Tipo de credencial
AzureKeyCredentialTrait AzureKeyCredential
AzureNamedKeyCredentialTrait AzureNamedKeyCredential
AzureSasCredentialTrait AzureSasCredential
ConnectionStringCredentialTrait String (no hay ningún tipo formal para las cadenas de conexión)
KeyCredentialTrait KeyCredential
TokenCredentialTrait TokenCredential

ConfigurationTrait

ConfigurationTrait<T> permite establecer Configuration en los clientes de servicio. Configuration se puede usar para pasar un conjunto de comportamientos en tiempo de ejecución al generador de clientes, como cómo ProxyOptions se cargan desde el entorno, pasando implícitamente las credenciales a algunos generadores de clientes que lo admiten, etc.

EndpointTrait

EndpointTrait<T> permite establecer el punto de conexión de servicio en los clientes de servicio.

Tiempos de espera de la operación

Los SDK de Azure proporcionan algunas formas coherentes de configurar tiempos de espera en las llamadas API. Cada tiempo de espera afecta a un ámbito diferente de los SDK de Azure y a la aplicación de llamada.

Tiempos de espera http

Los tiempos de espera HTTP son el nivel más bajo de control de tiempo de espera que proporcionan los SDK de Azure. Estos tiempos de espera se pueden configurar al compilar HttpClients o usar HttpClientOptions al compilar clientes de servicio sin configurar HttpClient uno mismo. En la tabla siguiente se muestra el tiempo de espera HTTP, el método correspondiente HttpClientOptions que se puede usar para establecerlo, la variable de entorno para controlar el valor predeterminado, el valor predeterminado si no se establece el valor de entorno y una breve descripción de los efectos del tiempo de espera.

Tiempo de espera http HttpClientOptions Método Variable de entorno Valor predeterminado Descripción
Tiempo de espera de la conexión setConnectTimeout(Duration) AZURE_REQUEST_CONNECT_TIMEOUT 10 segundos Cantidad de tiempo para que se establezca una conexión antes de que se agote el tiempo de espera.
Tiempo de espera de escritura setWriteTimeout(Duration) AZURE_REQUEST_WRITE_TIMEOUT 60 segundos Cantidad de tiempo entre cada escritura de datos de solicitud en la red antes de que se agote el tiempo de espera.
Tiempo de espera de respuesta setResponseTimeout(Duration) AZURE_REQUEST_RESPONSE_TIMEOUT 60 segundos Cantidad de tiempo entre finalizar el envío de la solicitud para recibir los primeros bytes de respuesta antes de que se agote el tiempo de espera.
Tiempo de espera de lectura setReadTimeout(Duration) AZURE_REQUEST_READ_TIMEOUT 60 segundos Cantidad de tiempo entre cada datos de respuesta leídos de la red antes de que se agote el tiempo de espera.

Dado que estos tiempos de espera son más cercanos a la red, si desencadenan, se propagarán de nuevo a través HttpPipeline de y, por lo general, el RetryPolicy.

Tiempos de espera de HttpPipeline

Los tiempos de espera de HttpPipeline son el siguiente nivel de tiempo de espera que se controlan los SDK de Azure que proporcionan. Estos tiempos de espera se configuran mediante HttpPipelinePolicy y configuran un tiempo de espera mediante Mono.timeout para solicitudes asincrónicas o con un ExecutorService tiempo de espera get(long, TimeUnit) para las solicitudes sincrónicas.

Dependiendo de la ubicación dentro de HttpPipeline, estos tiempos de espera se pueden capturar mediante RetryPolicy y reintentar. Si la directiva de tiempo de espera es PER_RETRY (HttpPipelinePolicy.getPipelinePosition()) el tiempo de espera se capturará mediante , RetryPolicy ya que se colocará después RetryPolicyde , por lo tanto, en su ámbito de captura, si vuelve PER_CALL a intentar la solicitud deberá controlarse mediante la lógica de la aplicación.

Tiempos de espera del cliente de servicio

Los tiempos de espera del cliente de servicio son el mayor nivel de tiempo de espera que controlan los SDK de Azure. Estos tiempos de espera se configuran pasando Duration timeout a métodos de servicio sincrónicos que admiten tiempos de espera o mediante Mono.timeout o Flux.timeout en métodos de servicio asincrónicos.

Dado que estos tiempos de espera están en la propia llamada API, no pueden capturarse mediante ningún mecanismo de reintento dentro de los SDK de Azure y deben controlarse mediante la lógica de la aplicación.

Pasos siguientes

Introducción a las bibliotecas de Azure compiladas mediante Azure Core.

Solución de problemas

Si encuentra algún error, envíe problemas a través de problemas de GitHub o consulte StackOverflow para el SDK de Java de Azure.

Habilitar el registro

Los SDK de Azure para Java proporcionan un artículo de registro coherente para ayudar a solucionar errores de aplicación y acelerar su resolución. Los registros generados capturarán el flujo de una aplicación antes de alcanzar el estado terminal para ayudar a encontrar el problema raíz. Consulte la documentación de registro para obtener instrucciones sobre cómo habilitar el registro.

Registro de solicitudes y respuestas HTTP

El registro de solicitudes y respuestas HTTP se puede habilitar estableciendo HttpLogDetailLevel en el HttpLogOptions utilizado para crear un cliente de servicio basado en HTTP o estableciendo la variable de entorno o la propiedad AZURE_HTTP_LOG_DETAIL_LEVELdel sistema . En la tabla siguiente se muestran las opciones válidas para AZURE_HTTP_LOG_DETAIL_LEVEL y se HttpLogDetailLevel correlaciona con (las opciones válidas no distinguen mayúsculas de minúsculas):

Valor de AZURE_HTTP_LOG_DETAIL_LEVEL Enumeración HttpLogDetailLevel
basic HttpLogDetailLevel.BASIC
headers HttpLogDetailLevel.HEADERS
body HttpLogDetailLevel.BODY
body_and_headers HttpLogDetailLevel.BODY_AND_HEADERS
bodyandheaders HttpLogDetailLevel.BODY_AND_HEADERS

Todos los demás valores, o valores no admitidos, dan como resultado HttpLogDetailLevel.NONE, o deshabilitan el registro de solicitudes HTTP y respuesta. El registro debe estar habilitado para registrar las solicitudes HTTP y las respuestas. El registro de encabezados HTTP requiere verbose que se habilite el registro. En la tabla siguiente se explica qué registro está habilitado para cada HttpLogDetailLevel:

Valor de HttpLogDetailLevel Registro habilitado
HttpLogDetailLevel.NONE No hay registro de solicitudes HTTP ni respuesta
HttpLogDetailLevel.BASIC Método de solicitud HTTP, código de estado de respuesta y dirección URL de solicitud y respuesta
HttpLogDetailLevel.HEADERS Todos los encabezados de solicitud y respuesta si el nivel de HttpLogDetailLevel.BASIC registro es verbose
HttpLogDetailLevel.BODY Todo y el cuerpo de solicitud y respuesta si tiene menos de HttpLogDetailLevel.BASIC 10 KB de tamaño
HttpLogDetailLevel.BODY_AND_HEADERS Todo y HttpLogDetailLevel.HEADERSHttpLogDetailLevel.BODY

Contribuciones

Para más información sobre cómo contribuir a este repositorio, consulte la guía de contribución.

  1. Bifurcación
  2. Creación de la rama de características (git checkout -b my-new-feature)
  3. Confirmar los cambios (git commit -am 'Add some feature')
  4. Inserción en la rama (git push origin my-new-feature)
  5. Creación de una nueva solicitud de incorporación de cambios

Impresiones