Descripción de la canalización HTTP y los reintentos en el SDK de Azure para Python

Al realizar una llamada a cualquier servicio de Azure mediante el SDK de Azure para Python, la solicitud no va directamente al servicio de Azure. No importa si es Azure Blob Storage, Azure Key Vault, Azure Cosmos DB o cualquier otro servicio basado en HTTP. En su lugar, la solicitud fluye a través de una canalización HTTP sofisticada que controla los problemas críticos transversales automáticamente.

Comprender cómo funciona la canalización HTTP es esencial para crear aplicaciones sólidas y eficaces. La canalización:

  • Gestiona los reintentos para errores transitorios.
  • Controla la autenticación.
  • Proporciona funcionalidades de registro.
  • Permite agregar un comportamiento personalizado cuando sea necesario.

Este conocimiento le ayuda a depurar problemas de rendimiento, optimizar la resistencia y personalizar la interacción de la aplicación con los servicios de Azure.

¿Qué es la canalización HTTP?

El SDK de Azure para Python usa una arquitectura de canalización HTTP interna para procesar todas las solicitudes y respuestas. Esta canalización consta de una serie de directivas que se ejecutan en secuencia. Cada directiva es responsable de un aspecto específico de la comunicación HTTP. Piense en la canalización como una cadena de pasos de procesamiento:

Client Request → Retry Policy → Authentication Policy → Logging Policy → HTTP Transport → Azure Service
                                                                                              ↓
Client Response ← Retry Policy ← Authentication Policy ← Logging Policy ← HTTP Transport ← Response

Cada política de la canalización puede:

  • Modifique la solicitud antes de enviarla.
  • Procese la respuesta después de recibirla.
  • Realice acciones como reintentar solicitudes fallidas.
  • Agregue encabezados, información de registro o implemente lógica personalizada.

Políticas clave en proceso

El SDK de Azure para Python incluye varias directivas integradas que controlan escenarios comunes:

  • RetryPolicy: reintenta automáticamente las solicitudes que producen errores debido a errores transitorios. Esta directiva implementa lógica de reintento inteligente con retroceso exponencial para evitar sobrecargar los servicios durante las interrupciones.
  • BearerTokenCredentialPolicy: administra la autenticación mediante la adquisición y actualización automática de tokens de acceso. Esta directiva garantiza que las solicitudes incluyan credenciales de autenticación válidas sin administración manual de tokens.
  • NetworkTraceLoggingPolicy: captura información detallada sobre las solicitudes y respuestas HTTP con fines de depuración. Esta directiva es inestimable al solucionar problemas de comunicación.
  • HttpTransport: la capa más baja de la canalización que realmente envía solicitudes HTTP a través de la red. En el SDK de Azure para Python, esta directiva se implementa normalmente mediante solicitudes o aiohttp para operaciones asincrónicas.

Otras directivas

  • RedirectPolicy: controla automáticamente las redirecciones HTTP.
  • DistributedTracingPolicy: se integra con sistemas de seguimiento distribuidos para la supervisión.
  • ProxyPolicy: enruta las solicitudes a través de servidores proxy HTTP cuando se configuran.
  • UserAgentPolicy: agrega la información de la versión del SDK a los encabezados de la solicitud.

Comportamiento de reintento

El SDK de Azure para Python implementa lógica de reintento inteligente para controlar los errores transitorios automáticamente. Comprender este comportamiento le ayuda a crear aplicaciones más resistentes.

Condiciones que se reintentan automáticamente

El SDK reintenta las solicitudes de estos códigos de estado HTTP:

  • 408 Tiempo de espera de solicitud: el servidor agota el tiempo de espera de la solicitud.
  • 429 Demasiadas solicitudes: la limitación de velocidad está en vigor.
  • 500 Error interno del servidor: problema temporal del servidor.
  • 502 Puerta de enlace incorrecta: problema de red temporal.
  • 503 Servicio no disponible: el servicio no está disponible temporalmente.
  • 504 Tiempo de espera de puerta de enlace: tiempo de espera de puerta de enlace o proxy.

Configuración de reintento predeterminada

La configuración de reintento predeterminada proporciona un buen equilibrio entre resistencia y rendimiento:

  • Número máximo de reintentos: 3
  • Modo de reintento: retroceso exponencial
  • Retraso base: 0,8 segundos
  • Retraso máximo: 60 segundos
  • Tiempo de reintento total máximo: 120 segundos

El cálculo de retroceso exponencial sigue este patrón:

delay = min(base_delay * (2 ** retry_attempt), max_delay)

Personalización de reintentos

Puede personalizar el comportamiento de reintento al crear clientes del SDK para que coincidan con los requisitos específicos de la aplicación.

from azure.storage.blob import BlobServiceClient
from azure.core.pipeline.policies import RetryPolicy

# Custom retry configuration
retry_policy = RetryPolicy(
    retry_total=5,                    # Maximum number of retry attempts
    retry_backoff_factor=0.5,         # Base backoff time in seconds
    retry_backoff_max=120,            # Maximum backoff time in seconds
    retry_on_status_codes=[429, 500, 502, 503, 504]  # HTTP status codes to retry
)

# Apply custom retry policy to client
client = BlobServiceClient(
    account_url="https://myaccount.blob.core.windows.net",
    credential=credential,
    retry_policy=retry_policy
)

Desactivar reintentos

En escenarios en los que los reintentos no son adecuados:

from azure.core.pipeline.policies import RetryPolicy

# Disable retries completely
no_retry_policy = RetryPolicy(retry_total=0)

client = BlobServiceClient(
    account_url="https://myaccount.blob.core.windows.net",
    credential=credential,
    retry_policy=no_retry_policy
)

Diagnóstico y depuración del comportamiento de reintento

Comprender cuándo y por qué se producen los reintentos es fundamental para solucionar problemas de rendimiento.

Habilitación del registro del SDK

El SDK de Azure para Python usa el marco de registro estándar de Python:

import logging
import sys

# Configure logging to see retry attempts
logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    stream=sys.stdout
)

# Enable specific Azure SDK loggers
azure_logger = logging.getLogger('azure')
azure_logger.setLevel(logging.DEBUG)

# Now SDK operations will log retry attempts

Identificación de patrones de reintento

Busque entradas de registro como:

Retry attempt 1 for request [GET] https://myaccount.blob.core.windows.net/container/blob
Waiting 0.8 seconds before retry

Problemas comunes de reintento

  • Reintentar errores no transitorios: El SDK no reintenta los errores de cliente (4xx), excepto 408 y 429.
  • Omitir la latencia de reintento: Recuerde que los reintentos agregan latencia a las operaciones con errores.
  • Proporcionar tiempo de espera insuficiente: Asegúrese de que el tiempo de espera general de la operación tenga en cuenta los retrasos de reintento.

Avanzado: Adición de directivas personalizadas

Puede ampliar el flujo de trabajo con políticas personalizadas para escenarios especializados.

Creación de una directiva personalizada

from azure.core.pipeline import PipelineRequest, PipelineResponse
from azure.core.pipeline.policies import HTTPPolicy
from typing import Any, Optional

class CustomTelemetryPolicy(HTTPPolicy):
    """Custom policy to add telemetry headers"""
    
    def send(self, request: PipelineRequest) -> PipelineResponse:
        # Add custom header before sending request
        request.http_request.headers['X-Custom-Telemetry'] = 'my-app-v1.0'
        
        # Continue with the pipeline
        response = self.next.send(request)
        
        # Log response time
        print(f"Request to {request.http_request.url} completed")
        
        return response

Aplicación de directivas personalizadas

from azure.storage.blob import BlobServiceClient

# Create client with custom policy
client = BlobServiceClient(
    account_url="https://myaccount.blob.core.windows.net",
    credential=credential,
    per_call_policies=[CustomTelemetryPolicy()],  # Policies that run per request
    per_retry_policies=[]  # Policies that run per retry attempt
)

Ordenación de directivas

Las directivas se ejecutan en un orden específico:

  • Directivas por llamada (se ejecutan una vez por operación).
  • Política de reintento.
  • Directivas por reintento (se ejecutan en cada intento).
  • Directiva de autenticación.
  • Transporte HTTP.

procedimientos recomendados

Usar la configuración predeterminada siempre que sea posible

La configuración de reintento predeterminada funciona bien para la mayoría de los escenarios. Personalice solo cuando tenga requisitos específicos.

Directrices de personalización

Al personalizar el comportamiento de reintento:

  • Utiliza backoff exponencial: Úsalo para evitar sobrecargar servicios durante la recuperación.
  • Establecer límites razonables: Limite el tiempo total de reintento para evitar la espera indefinida.
  • Supervisar las métricas de reintento: Realice un seguimiento de las tasas de reintento en producción para identificar problemas.
  • Considere los disyuntores: Implemente patrones de disyuntores para escenarios de gran volumen.

Qué no volver a intentar

Evite reintentar estos tipos de errores:

  • Errores de autenticación (401, 403): Los errores de autenticación requieren corregir credenciales, no volver a intentarlo.
  • Errores de cliente (400, 404): Los errores de cliente indican problemas con la propia solicitud.
  • Errores de lógica de negocios: Errores específicos de la aplicación que no se resuelven con reintentos.

Excelencia operativa

  • Identificadores de correlación de registro: Incluya x-ms-client-request-id en los registros para el soporte de Azure.
  • Establezca los tiempos de espera adecuados: Equilibrio entre la confiabilidad y la experiencia del usuario.
  • Comportamiento de reintento de prueba: Verifique que su aplicación maneja los reintentos correctamente.
  • Supervisar el rendimiento: Realice un seguimiento de las latencias de P95/P99 (métricas de latencia basadas en percentiles), incluida la sobrecarga de reintento.

Contenido relacionado

  • Se actualizó por última vez el