Informazioni sulla pipeline HTTP e sui ritentativi dell'Azure SDK per Python

Quando si effettua una chiamata a qualsiasi servizio di Azure usando Azure SDK per Python, la richiesta non passa direttamente al servizio di Azure. Non importa se si tratta di Archiviazione BLOB di Azure, Azure Key Vault, Azure Cosmos DB o qualsiasi altro servizio basato su HTTP. Al contrario, la richiesta passa attraverso una sofisticata pipeline HTTP che gestisce automaticamente gli aspetti trasversali critici.

Comprendere il funzionamento della pipeline HTTP è essenziale per la creazione di applicazioni affidabili e efficienti. La pipeline:

  • Gestisce i tentativi per gli errori temporanei.
  • Gestisce l'autenticazione.
  • Fornisce funzionalità di registrazione.
  • Consente di aggiungere un comportamento personalizzato quando necessario.

Queste informazioni consentono di eseguire il debug di problemi di prestazioni, ottimizzare la resilienza e personalizzare l'interazione dell'applicazione con i servizi di Azure.

Che cos'è la pipeline HTTP?

Azure SDK per Python usa un'architettura di pipeline HTTP interna per elaborare tutte le richieste e le risposte. Questa pipeline è costituita da una serie di politiche eseguite in sequenza. Ogni criterio è responsabile di un aspetto specifico della comunicazione HTTP. Considerare la pipeline come una catena di passaggi di elaborazione:

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

Ogni criterio nella pipeline può:

  • Modificare la richiesta prima dell'invio.
  • Elaborare la risposta dopo la ricezione.
  • Eseguire azioni come la ripetizione di richieste non riuscite.
  • Aggiungere intestazioni, informazioni di log o implementare la logica personalizzata.

Politiche chiave nella pipeline

Azure SDK per Python include diversi criteri predefiniti che gestiscono scenari comuni:

  • RetryPolicy: ritenta automaticamente le richieste che hanno esito negativo a causa di errori temporanei. Questa politica implementa una logica di reinvio intelligente con backoff esponenziale per evitare di sovraccaricare i servizi durante le interruzioni.
  • BearerTokenCredentialPolicy: gestisce l'autenticazione acquisendo e aggiornando automaticamente i token di accesso. Questo criterio garantisce che le richieste includano credenziali di autenticazione valide senza gestione manuale dei token.
  • NetworkTraceLoggingPolicy: acquisisce informazioni dettagliate sulle richieste HTTP e le risposte a scopo di debug. Questo criterio è prezioso quando si risolvono i problemi di comunicazione.
  • HttpTransport: livello più basso della pipeline che invia effettivamente richieste HTTP in rete. In Azure SDK per Python questo criterio viene in genere implementato usando le richieste o aiohttp per le operazioni asincrone.

Altre politiche

  • RedirectPolicy: gestisce automaticamente i reindirizzamenti HTTP.
  • DistributedTracingPolicy: si integra con i sistemi di traccia distribuiti per il monitoraggio.
  • ProxyPolicy: instrada le richieste tramite proxy HTTP quando configurate.
  • UserAgentPolicy: aggiunge informazioni sulla versione dell'SDK alle intestazioni della richiesta.

Comportamento di ripetizione dei tentativi

Azure SDK per Python implementa la logica di ripetizione intelligente dei tentativi per gestire automaticamente gli errori temporanei. La comprensione di questo comportamento consente di creare applicazioni più resilienti.

Condizioni ritentate automaticamente

L'SDK ritenta le richieste per questi codici di stato HTTP:

  • 408 Timeout della richiesta: Il server ha esaurito il tempo di attesa per la richiesta.
  • 429 Troppe richieste: la limitazione della frequenza è attiva.
  • 500 Errore interno del server: problema temporaneo del server.
  • 502 Gateway non valido: problema di rete temporaneo.
  • 503 Servizio non disponibile: servizio temporaneamente non disponibile.
  • Timeout 504 del gateway: timeout del gateway o proxy.

Configurazione di ripetizione dei tentativi predefinita

Le impostazioni di ripetizione dei tentativi predefinite offrono un buon equilibrio tra resilienza e prestazioni:

  • Numero massimo di tentativi: 3
  • Modalità di ripetizione dei tentativi: backoff esponenziale
  • Ritardo di base: 0,8 secondi
  • Ritardo massimo: 60 secondi
  • Tempo massimo di ripetizione dei tentativi: 120 secondi

Il calcolo del backoff esponenziale segue questo modello:

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

Personalizzare i tentativi

È possibile personalizzare il comportamento di ripetizione dei tentativi quando si creano client SDK in modo che corrispondano ai requisiti specifici dell'applicazione.

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
)

Disabilitare i tentativi

Per gli scenari in cui i ripetuti tentativi non sono appropriati:

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
)

Diagnosticare ed eseguire il debug del comportamento di ripetizione dei tentativi

Comprendere quando e perché si verificano nuovi tentativi è fondamentale per la risoluzione dei problemi di prestazioni.

Abilitare la registrazione dell'SDK

Azure SDK per Python usa il framework di registrazione standard di 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

Identificare i modelli di ripetizione dei tentativi

Cercare voci di registro come:

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

Problemi comuni di riprova

  • Ripetizione di errori non temporanei: L'SDK non ritenta gli errori client (4xx) ad eccezione di 408 e 429.
  • Ignorare la latenza di ripetizione dei tentativi: Tenere presente che i tentativi aggiungono latenza alle operazioni non riuscite.
  • Specificare un timeout insufficiente: Assicurarsi che il timeout complessivo dell'operazione conti i ritardi di ripetizione dei tentativi.

Avanzate: Aggiungere criteri personalizzati

È possibile estendere la pipeline con criteri personalizzati per scenari specializzati.

Creare criteri personalizzati

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

Applicare criteri personalizzati

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
)

Ordinamento delle politiche

Le politiche vengono eseguite in un ordine specifico.

  • Criteri per chiamata (esecuzione una sola volta per operazione).
  • Criterio di ripetizione dei tentativi.
  • Politiche di ritentativo (eseguite per ogni tentativo).
  • Criteri di autenticazione.
  • Trasporto HTTP.

Procedure consigliate

Usare le impostazioni predefinite quando possibile

La configurazione di ripetizione dei tentativi predefinita funziona correttamente per la maggior parte degli scenari. Personalizzare solo quando si hanno requisiti specifici.

Linee guida per la personalizzazione

Quando si personalizza il comportamento di ripetizione dei tentativi:

  • Usare il backoff esponenziale: Usare per evitare il sovraccarico dei servizi durante il ripristino.
  • Impostare limiti ragionevoli: Limitare il tempo totale di ripetizione dei tentativi per evitare l'attesa illimitata.
  • Monitorare le metriche di ripetizione dei tentativi: Tenere traccia delle frequenze di ripetizione dei tentativi nell'ambiente di produzione per identificare i problemi.
  • Prendere in considerazione gli interruttori di circuito: Implementare modelli di interruttore per scenari con volumi elevati.

Cosa non riprovare

Evitare di ripetere questi tipi di errori.

  • Errori di autenticazione (401, 403): Gli errori di autenticazione richiedono la correzione delle credenziali e non la ripetizione dei tentativi.
  • Errori client (400, 404): Gli errori del client indicano problemi con la richiesta stessa.
  • Errori della logica di business: Errori specifici dell'applicazione che non vengono risolti con nuovi tentativi.

Eccellenza operativa

  • ID correlazione log: Includere x-ms-client-request-id nei log per il supporto di Azure.
  • Impostare i timeout appropriati: Bilanciare l'affidabilità e l'esperienza utente.
  • Comportamento dei tentativi di test: Verificare che l'applicazione gestisca i tentativi normalmente.
  • Monitorare le prestazioni: Tenere traccia delle latenze P95/P99 (metriche di latenza basata su percentile), incluso il sovraccarico dei tentativi.

Contenuti correlati

  • Ultimo aggiornamento: