Конвейеры HTTP и повторные попытки в пакете SDK Azure для C++

2025-05-08

Пакет SDK Azure для C++ использует архитектуру конвейера HTTP для обработки HTTP-запросов к службам Azure. В этом документе объясняется, как работают конвейеры HTTP, как реализуются политики повторных попыток и как их можно настроить в соответствии с потребностями приложения.

Архитектура конвейера HTTP

Что такое конвейер HTTP?

Конвейер HTTP — это стек политик HTTP, которые применяются последовательно для обработки HTTP-запросов и ответов. Каждый клиент в пакете SDK Azure имеет собственный конвейер HTTP. Политики определяют, как обрабатываются HTTP-запросы, включая такие операции.

Добавление заголовков аутентификации
Ведение журнала запросов и ответов
Логика повторных попыток для неудачных запросов
Сбор данных телеметрии
Обработка транспорта (фактически отправка HTTP-запроса)

Конвейер разделен на две основные части:

Политики для каждого вызова — выполняется один раз в рамках операции API
Политики повторных попыток — выполнение для каждой попытки

Эта структура гарантирует, что соответствующие политики (например, проверка подлинности) выполняются только один раз на каждую операцию, а другие (например, ведение журнала) выполняются для каждой попытки повторных попыток.

Упорядочивание политик

Типичный конвейер HTTP в пакете SDK Azure для C++ включает следующие политики в порядке:

Политика телеметрии (для каждого вызова) — добавляет сведения телеметрии пакета SDK Azure
Политика идентификатора запроса (для каждого вызова) — гарантирует, что каждый запрос имеет уникальный идентификатор.
Политики Per-Call для конкретной службы — пользовательские политики, относящиеся к службе
Политика повторных попыток (для каждого вызова) — реализует логику повторных попыток
Политики Per-Retry, специфические для службы — пользовательские политики, выполняющиеся при каждой повторной попытке.
Политика действий запроса (для повтора) — управление распределенной трассировкой
Политика ведения журнала (повторно) — обрабатывает запросы и ответы
Политика транспорта (для повтора) — обрабатывает фактическую отправку HTTP-запроса.

Схема, показывющая этапы политики пакета SDK Azure для конвейера HTTP C++.

Политика повторных попыток

Как работают повторные попытки

Политика повторных попыток предназначена для обработки временных сбоев, которые могут возникнуть при выполнении HTTP-запросов к службам Azure. Если запрос завершается ошибкой из-за временной ошибки, политика повторных попыток будет выполнять следующие действия:

Определите, можно ли повторить попытку устранения сбоя
Вычисление соответствующей задержки
Дождитесь этой задержки
Повторите запрос

Политика поддерживает повторную попытку при сбоях уровня транспорта (проблемах сети) и некоторых кодов состояния HTTP.

Поведение повторных попыток по умолчанию

По умолчанию политика повторных попыток настроена следующим образом:

Не более трех попыток повторного выполнения
Начальная задержка повторных попыток в 800 миллисекундах
Максимальная задержка повторных попыток в 60 секунд
Коды состояния для повторного запроса: 408, 429, 500, 502, 503, 504

Задержка повторных попыток использует экспоненциальную стратегию понижения интенсивности с джиттером.

Первая повторная попытка: ~800 мс
Вторая повторная попытка: ~1600 мс
Третья повторная попытка: ~3200 мс
И т. д. До достижения максимальной задержки повторных попыток

Когда происходят повторные попытки

Политика повторных попыток пытается повторить запрос в следующих сценариях:

Сбои транспорта:
- Проблемы, связанные с подключением к сети
- Время ожидания подключения
- Сбои разрешения DNS (система доменных имен)
Коды состояния HTTP:
- 408 (истекло время ожидания запроса)
- 429 (слишком много запросов)
- 500 (внутренняя ошибка сервера)
- 502 (недопустимый шлюз)
- 503 (служба недоступна)
- 504 (время ожидания шлюза)
Логика повторных попыток для конкретной службы:
- Некоторые службы, такие как Storage, реализуют специализированную логику повторных попыток запросов для обработки сценариев отказа.

Настройка поведения повторных попыток

При создании клиента можно настроить поведение повторных попыток, изменив параметры RetryOptions клиента.

Пример. Настройка параметров повторных попыток

#include <azure/storage/blobs.hpp>

int main() 
{
    // Create client options
    Azure::Storage::Blobs::BlobClientOptions options;
    
    // Modify retry options
    options.Retry.MaxRetries = 5;                                    // Increase max retries
    options.Retry.RetryDelay = std::chrono::milliseconds(1000);      // Set initial retry delay to 1 second
    options.Retry.MaxRetryDelay = std::chrono::seconds(30);          // Cap maximum retry delay at 30 seconds
    
    // Add a custom status code to retry on
    options.Retry.StatusCodes.insert(Azure::Core::Http::HttpStatusCode::Forbidden); // Retry on 403 errors
    
    // Create the client with custom retry options
    auto blobClient = Azure::Storage::Blobs::BlobClient::CreateFromConnectionString(
        connectionString,
        containerName,
        blobName,
        options);
    
    // Use the client...
}

Добавление настраиваемых политик

Пользовательские политики можно добавить в конвейер HTTP для реализации специализированного поведения:

Добавление политики для каждой операции

Политики выполнения операций применяются один раз для каждой операции API, независимо от количества повторных попыток.

class MyCustomPolicy final : public Azure::Core::Http::Policies::HttpPolicy {
public:
    ~MyCustomPolicy() override = default;
    std::unique_ptr<HttpPolicy> Clone() const override
    {
        return std::make_unique<MyCustomPolicy>(*this);
    }

    std::unique_ptr<Azure::Core::Http::RawResponse> Send(
        Azure::Core::Http::Request& request,
        Azure::Core::Http::Policies::NextHttpPolicy nextPolicy,
        Azure::Core::Context const& context) const override
    {
        // Custom logic before the request
        
        auto response = nextPolicy.Send(request, context);
        
        // Custom logic after the response
        
        return response;
    }
};

// Adding the policy to client options
Azure::Storage::Blobs::BlobClientOptions options;
options.PerOperationPolicies.emplace_back(std::make_unique<MyCustomPolicy>());

Добавление политики повторных попыток

Политики повторных попыток вызываются для каждой попытки повтора:

// Similar implementation to above, but add to PerRetryPolicies
options.PerRetryPolicies.emplace_back(std::make_unique<MyCustomRetryPolicy>());

Обработка вторичных конечных точек

Некоторые службы Azure, такие как служба хранилища, поддерживают вторичные конечные точки для обеспечения высокой доступности. Пакет SDK включает поддержку автоматического перехода на вторичные узлы в случае отказа:

Azure::Storage::Blobs::BlobClientOptions options;

// Configure secondary endpoint for Storage
std::string primaryUrl = blobClient.GetUrl();
std::string secondaryUrl = InferSecondaryUrl(primaryUrl); // Your logic to determine secondary URL
std::string secondaryHost = Azure::Core::Url(secondaryUrl).GetHost();

options.SecondaryHostForRetryReads = secondaryHost;

Попытки повторной записи действий в журнал

Конвейер HTTP включает встроенное ведение журнала для повторных попыток. Вы можете настроить уровень ведения журнала, чтобы просмотреть сведения о повторных попытках:

// Set log level to see retry information
Azure::Core::Diagnostics::Logger::SetLevel(Azure::Core::Diagnostics::Logger::Level::Informational);

// Set a custom log listener to capture logs
Azure::Core::Diagnostics::Logger::SetListener([](auto level, auto message) {
    std::cout << "Log [" << static_cast<int>(level) << "]: " << message << std::endl;
});

При возникновении повторных попыток записи журнала отображаются следующим образом:

"Ошибка транспорта HTTP: [сведения об ошибке]"
"Попытка повтора HTTP #1 будет выполнена в 800 мс".
Код состояния HTTP 503 будет повторно отправлен.

Лучшие практики

Используйте параметры повторных попыток по умолчанию, когда это возможно
- Параметры по умолчанию оптимизированы для большинства сценариев и включают наилучшие практики, такие как экспоненциальная задержка.
Будьте осторожны с неидемпотентными операциями
- Рассмотрите возможность ограничения повторных попыток для операций, которые небезопасны для повторных попыток (например, неимпотентных запросов POST)
Рассмотрим шаблоны разбиения цепи
- Для приложений с большим объемом реализуйте паттерны предохранителей, чтобы не перегружать службы, которые отвечают с ошибками.
Тестовые сценарии повторных попыток
- Проверка поведения приложения при возникновении повторных попыток, чтобы обеспечить правильную обработку
Мониторинг попыток повторной телеметрии
- Высокий уровень повторных попыток может указывать на основные проблемы, которые следует устранить

Продвинутые: внутренности трубопровода

Конвейер HTTP реализуется в Azure::Core::Http::_internal::HttpPipeline классе, который управляет последовательностью выполнения политики. При поступлении запроса, конвейер:

Начинается с первой политики в конвейере
Каждая политика обрабатывает запрос, а затем передает его в следующую политику.
Последняя политика обычно является политикой транспорта, которая фактически отправляет запрос.
Затем ответ проходит обратно через набор правил в обратном порядке

Политика повторных попыток особенная тем, что она может повторять всю последовательность политик, поступающих после неё в конвейере.

Устранение неполадок

Если возникают проблемы с повторными попытками:

Включите ведение информационного журнала
- AZURE_LOG_LEVEL Установите переменную среды на Informational, чтобы увидеть попытки повторного запуска
Проверка транспортных ошибок
- Проблемы с сетью часто проявляются в виде исключений при передаче данных
Проверка работоспособности службы
- Постоянные ошибки уровня 500 могут указывать на проблему службы Azure
Проверка идентификаторов запросов
- Каждый запрос имеет уникальный идентификатор, который можно использовать при работе с службой поддержки Azure
Проверьте настройки тайм-аута
- Убедитесь, что время ожидания приложения совместимы с политикой повторных попыток