Базовая библиотека Azure SDK для C++

Azure::Core (azure-core) предоставляет общие примитивы, абстракции и вспомогательные средства для современных клиентских библиотек azure SDK, написанных на языке C++. Эти библиотеки следуют рекомендациям по проектированию пакета SDK Azure для C++.

Библиотека позволяет клиентским библиотекам предоставлять общие функциональные возможности согласованно. Когда вы узнаете, как использовать эти API в одной клиентской библиотеке, вы узнаете, как использовать их в других клиентских библиотеках.

Начало работы

Как правило, вам не нужно скачать azure-core. Оно будет скачано для вас в качестве зависимости клиентских библиотек. Если вы хотите явно скачать его (например, для реализации собственной клиентской библиотеки), можно найти источник здесь или использовать vcpkg для установки пакета azure-core-cpp.

Включите пакет

Самый простой способ получить пакет SDK для C++ — использовать диспетчер пакетов vcpkg. См. соответствующий раздел пакета SDK Azure для C++ для чтения.

Чтобы установить пакет Azure Core с помощью vcpkg, выполните приведенные действия.

> vcpkg install azure-core-cpp

Затем используйте в файле CMake:

find_package(azure-core-cpp CONFIG REQUIRED)
target_link_libraries(<your project name> PRIVATE Azure::azure-core)

Основные понятия

Основные общие понятия Azure::Core включают:

• Обработка потоковых данных и входных и выходных данных (ввода-вывода) BodyStream наряду с производными типами.
• Доступ к сведениям о ответе HTTP для возвращаемой модели любой клиентской операции пакета SDK через Response<T>.
• Опрос длительных операций (LROS) через Operation<T>.
• Исключения для создания отчетов об ошибках из запросов служб в согласованном режиме с помощью базового типа RequestFailedExceptionисключения.
• Абстракции для учетных данных пакета SDK Azure (TokenCredential).
• Замещаемый уровень транспорта HTTP для отправки запросов и получения ответов по сети.
• Конвейер HTTP и политики HTTP, такие как повторные попытки и ведение журнала, которые можно настроить с помощью определенных параметров клиента службы.

Длительные операции

Для выполнения некоторых операций требуется много времени и требуется опрос по их состоянию. Методы запускают длительные типы возвращаемых Operation<T> операций.

Можно периодически опрашивировать, завершена ли операция с помощью Poll() метода для возвращаемого Operation<T> и отслеживания хода выполнения операции.Value() Кроме того, если вы просто хотите ждать завершения операции, можно использовать PollUntilDone().

SomeServiceClient client;

auto operation = *client.StartSomeLongRunningOperation();

while (!operation.IsDone())
{
  std::unique_ptr<Http::RawResponse> response = operation.Poll();

  auto partialResult = operation.Value();

  // Your per-polling custom logic goes here, such as logging progress.

  // You can also try to abort the operation if it doesn't complete in time.

  std::this_thread::sleep_for(std::chrono::milliseconds(1000));
}

auto finalResult = operation.Value();

Адаптер транспорта HTTP

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

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

Ниже приведены три основных способа устранения неполадок.

• Проверка исключений
• Включение ведения журнала (см. сообщения журнала ПАКЕТА SDK)

Сообщения журнала ПАКЕТА SDK

Самый простой способ включения журналов — задать переменную среды AZURE_LOG_LEVEL для одной из значений: |AZURE_LOG_LEVEL|Azure::Core::Diagnostics::Logger::Level|Уровень сообщения журнала| |-|-|-| |4 или error или err|Error|Уровень ведения журнала для сбоев, с которыми приложение вряд ли восстановится.| |3 или warning или warn|Warning|Уровень ведения журнала, когда функция не выполняет свою целевую задачу.| |2 или informational или information или info|Informational|Уровень ведения журнала при обычной работе функции.| |1 или verbose или debug|Verbose|Уровень ведения журнала для подробных сценариев устранения неполадок.|

Затем сообщения журнала будут напечатаны в консоли (stderr). Обратите внимание, что stderr сообщения можно перенаправить в файл журнала следующим образом:

В Windows:

myprogram.exe 2> log.txt

В Linux или macOS:

./myprogram 2> log.txt

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

#include <azure/core/diagnostics/logger.hpp>

int main()
{
    using namespace Azure::Core::Diagnostics;

    // See above for the level descriptions.
    Logger::SetLevel(Logger::Level::Verbose);

    // SetListener accepts std::function<>, which can be either lambda or a function pointer.
    Logger::SetListener([&](auto lvl, auto msg){ /* handle Logger::Level lvl and std::string msg */ });
}

Обратите внимание, что обратный вызов прослушивателя выполняется в том же потоке, что и операция, активировающая сообщение журнала. Рекомендуется реализовать из-за минимального объема обработки сообщений журнала в потоке обратного вызова. Если требуется обработка сообщений, рассмотрите возможность реализации таким образом, чтобы обратный вызов помещал строку сообщения в потокобезопасную очередь, чтобы другой поток выбрал сообщения из этой очереди и обработал их.

Дальнейшие шаги

Изучите и установите доступные библиотеки Azure SDK.

Contributing

Дополнительные сведения об участии в этом репозитории см. в руководстве по участию.

Этот проект приветствует взносы и предложения. Большинство вкладов требуют, чтобы вы согласились с соглашением о лицензии участника (CLA), заявив, что у вас есть право, и на самом деле, предоставьте нам права на использование вашего вклада. Дополнительные сведения см. в лицензионном соглашении участника.

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

В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Для получения дополнительной информации см. FAQ о кодексе поведения, или свяжитесь с opencode@microsoft.com по любым дополнительным вопросам или комментариям.

Дополнительные полезные ссылки для участников

Многие люди во всем мире помогли сделать этот проект лучше. Вы хотите проверить:

• Каковы некоторые хорошие первые проблемы для новых участников репозитория?
• Как создать и проверить изменение
• Как можно внести изменения!
• Часто задаваемые вопросы и концептуальные разделы в подробном вики-сайте Пакета SDK Azure для C++ .

Создание отчетов о проблемах безопасности и ошибках безопасности

Проблемы безопасности и ошибки должны сообщаться в частном порядке через электронную почту в Центр реагирования майкрософт (MSRC). secure@microsoft.com Вы должны получить ответ в течение 24 часов. Если по какой-то причине вы не сделали этого, следуйте инструкциям по электронной почте, чтобы убедиться, что мы получили исходное сообщение. Дополнительные сведения, включая ключ PGP MSRC, можно найти в TechCenter безопасности.

Лицензия

Пакет SDK Azure для C++ лицензирован в соответствии с лицензией MIT .