Azure SDK for Python での HTTP パイプラインと再試行について

Azure SDK for Python を使用して任意の Azure サービスを呼び出しても、要求は Azure サービスに直接送信されません。 Azure Blob Storage、Azure Key Vault、Azure Cosmos DB、またはその他の HTTP ベースのサービスのいずれであるかは関係ありません。代わりに、要求は、重大な横断的な問題を自動的に処理する高度な HTTP パイプラインを通過します。

堅牢でパフォーマンスの高いアプリケーションを構築するには、HTTP パイプラインのしくみを理解することが不可欠です。パイプライン:

一時的な障害の再試行を管理します。
認証を処理します。
ログ機能を提供します。
必要に応じてカスタム動作を追加できます。

この知識は、パフォーマンスの問題をデバッグし、回復性を最適化し、アプリケーションと Azure サービスの対話をカスタマイズするのに役立ちます。

HTTP パイプラインとは

Azure SDK for Python では、内部 HTTP パイプラインアーキテクチャを使用して、すべての要求と応答を処理します。このパイプラインは、順番に実行される一連のポリシーで構成されます。各ポリシーは、HTTP 通信の特定の側面を担当します。パイプラインは、処理ステップのチェーンと考えてください。

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

パイプライン内の各ポリシーは次のことができます。

送信前に要求を変更します。
受信後に応答を処理します。
失敗した要求の再試行などのアクションを実行します。
ヘッダーの追加、情報のログ記録、またはカスタムロジックの実装。

パイプライン内の主要なポリシー

Azure SDK for Python には、一般的なシナリオを処理するいくつかの組み込みポリシーが含まれています。

RetryPolicy: 一時的なエラーが原因で失敗した要求を自動的に再試行します。このポリシーでは、停止中のサービスの負荷を回避するために、指数バックオフを伴うインテリジェントな再試行ロジックを実装します。
BearerTokenCredentialPolicy: アクセストークンを自動的に取得および更新することで、認証を管理します。このポリシーにより、要求に、手動でトークンを管理せずに有効な認証資格情報が含まれるようにします。
NetworkTraceLoggingPolicy: デバッグ目的で HTTP 要求と応答に関する詳細情報をキャプチャします。このポリシーは、通信の問題をトラブルシューティングするときに非常に役立ちます。
HttpTransport: ネットワーク経由で HTTP 要求を実際に送信するパイプラインの最下位レイヤー。 Azure SDK for Python では、このポリシーは通常、非同期操作に要求または aiohttp を使用して実装されます。

その他のポリシー

RedirectPolicy: HTTP リダイレクトを自動的に処理します。
DistributedTracingPolicy: 監視用の分散トレースシステムと統合されます。
ProxyPolicy: 構成時に HTTP プロキシを介して要求をルーティングします。
UserAgentPolicy: 要求ヘッダーに SDK バージョン情報を追加します。

再試行の動作

Azure SDK for Python では、一時的なエラーを自動的に処理するためのインテリジェントな再試行ロジックが実装されています。この動作を理解すると、回復性の高いアプリケーションを構築するのに役立ちます。

自動的に再試行される条件

SDK は、次の HTTP 状態コードの要求を再試行します。

408 要求タイムアウト: サーバーが要求を待機中にタイムアウトしました。
429 要求が多すぎます: レート制限が有効です。
500 内部サーバーエラー: 一時サーバーの問題。
502 無効なゲートウェイ: 一時的なネットワークの問題。
503 サービス利用不可: サービスは一時的に利用できません。
504 ゲートウェイタイムアウト: ゲートウェイまたはプロキシのタイムアウト。

既定の再試行構成

既定の再試行設定では、回復性とパフォーマンスのバランスが取られます。

最大再試行回数: 3
再試行モード: 指数バックオフ
基本遅延: 0.8 秒
最大遅延: 60 秒
最大再試行時間: 120 秒

指数バックオフ計算は、次のパターンに従います。

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

再試行をカスタマイズする

SDK クライアントを作成するときに、アプリケーションの特定の要件に合わせて再試行動作をカスタマイズできます。

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
)

再試行を無効にする

再試行が適切でないシナリオの場合:

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
)

再試行動作の診断とデバッグ

再試行が発生するタイミングと理由を理解することは、パフォーマンスの問題のトラブルシューティングに不可欠です。

SDK のログ記録を有効にする

Azure SDK for Python では、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

再試行パターンを特定する

次のようなログエントリを探します。

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

一般的な再試行の落とし穴

一時的でないエラーの再試行: SDK は、408 と 429 を除き、クライアントエラー (4xx) を再試行しません。
再試行の待機時間を無視する: 再試行により、失敗した操作に待機時間が追加されることを忘れないでください。
タイムアウトが不十分な場合: 全体的な操作タイムアウトが再試行の遅延を考慮していることを確認します。

詳細: カスタムポリシーを追加する

特殊なシナリオ用のカスタムポリシーを使用してパイプラインを拡張できます。

カスタムポリシーの作成

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

カスタムポリシーを適用する

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
)

ポリシーの順序付け

ポリシーは特定の順序で実行されます。

呼び出しごとのポリシー (1 回の操作につき 1 回実行)。
再試行ポリシー。
再試行ごとのポリシー (試行ごとに実行)。
認証ポリシー。
HTTP トランスポート。

ベストプラクティス

可能な場合は既定の設定を使用する

既定の再試行構成は、ほとんどのシナリオに適しています。特定の要件がある場合にのみカスタマイズします。

カスタマイズのガイドライン

再試行の動作をカスタマイズする場合:

指数バックオフを使用します。 復旧中のサービスの負荷を抑えるために使用します。
適切な制限を設定します。 無期限の待機を防ぐために、合計再試行時間を上限にします。
再試行メトリックを監視する: 運用環境の再試行率を追跡して、問題を特定します。
サーキットブレーカーを検討します。 大量のシナリオに対してサーキットブレーカーパターンを実装します。

再試行しないもの

次の種類のエラーを再試行しないでください。

認証エラー (401、403): 認証エラーでは、再試行せず、資格情報を修正する必要があります。
クライアントエラー (400、404): クライアントエラーは、要求自体に問題があることを示します。
ビジネスロジックエラー: 再試行で解決されないアプリケーション固有のエラー。

オペレーショナルエクセレンス

ログ相関 ID: Azure サポートのログに x-ms-client-request-id を含めます。
適切なタイムアウトを設定します。 信頼性とユーザーエクスペリエンスのバランスを取る。
再試行の動作をテストします。 アプリケーションで再試行が正常に処理されていることを確認します。
パフォーマンスの監視: 再試行のオーバーヘッドを含む P95/P99 待機時間 (パーセンタイルベースの待機時間メトリック) を追跡します。

回復性のあるアプリケーションを実装する

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-12-09