Compreender o pipeline HTTP e as repetições no SDK do Azure para Python

Quando você faz uma chamada para qualquer serviço do Azure usando o SDK do Azure para Python, sua solicitação não vai diretamente para o serviço do Azure. Não importa se é o Armazenamento de Blobs do Azure, o Azure Key Vault, o Azure Cosmos DB ou qualquer outro serviço baseado em HTTP. Em vez disso, sua solicitação flui por meio de um pipeline HTTP sofisticado que lida automaticamente com preocupações transversais críticas.

Entender como o pipeline HTTP funciona é essencial para a criação de aplicativos robustos e com desempenho. O pipeline:

  • Gerencia as tentativas de correção para falhas transitórias.
  • Gerencia a autenticação.
  • Fornece funcionalidades de log.
  • Permite que você adicione um comportamento personalizado quando necessário.

Esse conhecimento ajuda você a depurar problemas de desempenho, otimizar a resiliência e personalizar a interação do aplicativo com os serviços do Azure.

O que é o pipeline HTTP?

O SDK do Azure para Python usa uma arquitetura de pipeline HTTP interna para processar todas as solicitações e respostas. Esse pipeline consiste em uma série de políticas que são executadas em sequência. Cada política é responsável por um aspecto específico da comunicação HTTP. Pense no pipeline como uma cadeia de etapas de processamento:

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 no pipeline pode:

  • Modifique a solicitação antes de ser enviada.
  • Processe a resposta depois que ela for recebida.
  • Execute ações como tentar novamente solicitações com falha.
  • Adicione cabeçalhos, informações de log ou implemente a lógica personalizada.

Principais políticas no pipeline

O SDK do Azure para Python inclui várias políticas internas que lidam com cenários comuns:

  • RetryPolicy: repete automaticamente as solicitações que falham devido a erros transitórios. Essa política implementa a lógica de repetição inteligente com retirada exponencial para evitar sobrecarregar os serviços durante interrupções.
  • BearerTokenCredentialPolicy: gerencia a autenticação adquirindo e atualizando automaticamente tokens de acesso. Essa política garante que suas solicitações incluam credenciais de autenticação válidas sem gerenciamento manual de token.
  • NetworkTraceLoggingPolicy: captura informações detalhadas sobre solicitações HTTP e respostas para fins de depuração. Essa política é inestimável quando você soluciona problemas de comunicação.
  • HttpTransport: a camada mais baixa do pipeline que realmente envia solicitações HTTP pela rede. No SDK do Azure para Python, essa política normalmente é implementada usando solicitações ou aiohttp para operações assíncronas.

Outras políticas

  • RedirectPolicy: manipula redirecionamentos HTTP automaticamente.
  • DistributedTracingPolicy: Integra-se aos sistemas de rastreamento distribuídos para monitoramento.
  • ProxyPolicy: roteia solicitações por meio de proxies HTTP quando configuradas.
  • UserAgentPolicy: adiciona informações de versão do SDK aos cabeçalhos de solicitação.

Comportamento de repetição

O SDK do Azure para Python implementa a lógica de repetição inteligente para lidar com falhas transitórias automaticamente. Entender esse comportamento ajuda você a criar aplicativos mais resilientes.

Condições repetidas automaticamente

O SDK tenta novamente solicitações para estes códigos de status HTTP:

  • Tempo limite da solicitação 408: o servidor atingiu o tempo limite aguardando a solicitação.
  • 429 Muitas Solicitações: a limitação de requisições está em vigor.
  • 500 Erro interno do servidor: problema temporário do servidor.
  • 502 Gateway Inválido: Problema de rede temporário.
  • Serviço 503 Indisponível: serviço temporariamente indisponível.
  • Tempo limite do gateway 504: tempo limite de gateway ou proxy.

Configuração de repetição padrão

As configurações de repetição padrão fornecem um bom equilíbrio entre resiliência e desempenho:

  • Tentativas máximas de repetição: 3
  • Modo de repetição: retirada exponencial
  • Atraso base: 0,8 segundos
  • Atraso máximo: 60 segundos
  • Tempo máximo total de repetição: 120 segundos

O cálculo de retirada exponencial segue este padrão:

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

Personalizar novas tentativas

Você pode personalizar o comportamento de repetição ao criar clientes do SDK para corresponder aos requisitos específicos do aplicativo.

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
)

Desabilitar novas tentativas

Para cenários em que as tentativas não são apropriadas:

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
)

Diagnosticar e depurar o comportamento de repetição

Entender quando e por que novas tentativas ocorrem é crucial para solucionar problemas de desempenho.

Habilitar o registro em log do SDK

O SDK do Azure para Python usa a estrutura de log padrão do 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

Identificar padrões de repetição

Procure entradas de log como:

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

Armadilhas de repetição comuns

  • Repetindo erros não transitórios: O SDK não tenta novamente os erros do cliente (4xx), exceto para 408 e 429.
  • Ignorando a latência de repetição: Lembre-se de que as novas tentativas adicionam latência a operações com falha.
  • Fornecendo tempo limite insuficiente: Certifique-se de que o tempo limite geral da operação leva em conta os atrasos causados por tentativas de repetição.

Avançado: Adicionar políticas personalizadas

Você pode estender o pipeline com políticas personalizadas para cenários especializados.

Criar uma política 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

Aplicar políticas 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
)

Ordenação de política

As políticas são executadas em uma ordem específica:

  • Políticas por chamada (executar uma vez por operação).
  • Política de repetição.
  • Políticas por repetição (executar em cada tentativa).
  • Política de autenticação.
  • Transporte HTTP.

Práticas recomendadas

Usar configurações padrão quando possível

A configuração de repetição padrão funciona bem para a maioria dos cenários. Personalize somente quando você tiver requisitos específicos.

Diretrizes de personalização

Ao personalizar o comportamento de tentativa:

  • Use o recuo exponencial: Use para evitar sobrecarregar os serviços durante a recuperação.
  • Definir limites razoáveis: Limite o tempo total de repetição para evitar espera indefinida.
  • Monitorar métricas de repetição: Acompanhe as taxas de repetição na produção para identificar problemas.
  • Considere os disjuntores: Implemente padrões de disjuntor para cenários de alto volume.

O que não tentar novamente

Evite repetir esses tipos de erros:

  • Falhas de autenticação (401, 403): Os erros de autenticação exigem a correção de credenciais, não a repetição.
  • Erros do cliente (400, 404): Os erros do cliente indicam problemas com a solicitação em si.
  • Erros de lógica de negócios: Erros específicos do aplicativo que não são resolvidos com novas tentativas.

Excelência operacional

  • IDs de correlação de log: Inclua x-ms-client-request-id nos logs para o suporte do Azure.
  • Defina os tempos limite apropriados: Balancear entre confiabilidade e experiência do usuário.
  • Comportamento de repetição de teste: Verifique se o aplicativo manipula as novas tentativas normalmente.
  • Monitorar o desempenho: Acompanhe as latências P95/P99 (métricas de latência baseadas em percentil), incluindo a sobrecarga de tentativas adicionais.

Conteúdo relacionado

  • Última atualização em