Установка и интеграция библиотек из пакета SDK Azure для C++

Это руководство предоставляет разработчикам необходимые действия по установке библиотек из пакета SDK Azure для C++ с помощью vcpkg и интеграции их в проекты с CMake. Следуя инструкциям, вы можете настроить среду разработки и начать использовать службы Azure в приложениях C++. Независимо от того, знакомы ли вы с Azure или хотите упростить процесс интеграции, эта документация поможет вам быстро и эффективно приступить к работе.

Предпосылки

• Любой текстовый редактор
• Терминал
• Компилятор C++
• Git
• CMake.
• Подписка Azure
• Azure CLI

Проверка установки git и CMake

Чтобы обеспечить гладкий процесс интеграции, важно убедиться, что git и CMake правильно установлены в вашей системе.

Установка vcpkg

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

Установка библиотек

В этом разделе описан процесс установки необходимых библиотек из пакета SDK Azure для C++ с помощью vcpkg. В этом разделе показано, как использовать vcpkg в режиме манифеста, который создает несколько файлов проекта vcpkg для управления зависимостями проекта даже при совместном использовании с другими участниками совместной работы.

Создание ресурса Azure Key Vault

В этом разделе описывается, как использовать Azure CLI для создания ресурса Azure Key Vault. Этот ресурс Key Vault безопасно хранит конфиденциальные сведения и управляет ими, такими как секреты и ключи.

1. Наконец, убедитесь, что у вашей учетной записи Azure есть необходимые разрешения для работы с секретами Key Vault. Вы можете предоставить себе необходимые разрешения, назначив себе роль "Специалист по секретам Key Vault" на странице управления доступом (IAM) ресурса Key Vault на портале Azure. IAM обозначает управление идентификацией и доступом.

Настройка проекта

В этом разделе описывается процесс создания необходимых папок и файлов для настройки проекта Azure C++.

1. В корневом каталоге проекта создайте файлCMakeLists.txt . Этот файл используется для настройки проекта CMake. Добавьте следующий код в файл CMakeLists.txt :

   # Specify the minimum version of CMake required to build this project
   cmake_minimum_required(VERSION 3.30.0)
   
   # Set the path to the vcpkg toolchain file
   # Remember to replace the path below with the path where you cloned vcpkg
   set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg-root/scripts/buildsystems/vcpkg.cmake")
   
   # Define the project name, version, and the languages used
   project(azure_sample VERSION 0.1.0 LANGUAGES C CXX)
   
   # Find and include the azure-identity-cpp package
   find_package(azure-identity-cpp CONFIG REQUIRED)
   
   # Find and include the azure-security-keyvault-secrets-cpp package
   find_package(azure-security-keyvault-secrets-cpp CONFIG REQUIRED)
   
   # Add an executable target named 'azure_sample' built from the main.cpp source file
   add_executable(azure_sample main.cpp)
   
   # Link the azure-identity and azure-security-keyvault-secrets 
   # libraries to the azure_sample target
   target_link_libraries(azure_sample PRIVATE
       Azure::azure-identity
       Azure::azure-security-keyvault-secrets
   )
   

2. В корневом каталоге проекта создайте файл main.cpp . Добавьте следующий код в файл main.cpp :

   #include <azure/identity.hpp>
   #include <azure/keyvault/secrets.hpp>
   #include <iostream>
   
   using namespace Azure::Security::KeyVault::Secrets;
   
   int main()
   {
       try
       {
           // Set Key Vault URL string
           auto const keyVaultUrl = std::getenv("AZURE_KEYVAULT_URL");
   
           // Create Default Azure Credential to Authenticate.
           // It will pick up on our AzureCLI login
           auto credential = std::make_shared<Azure::Identity::DefaultAzureCredential>();
   
           // Create Key Vault Secret Client
           SecretClient secretClient(keyVaultUrl, credential);
   
           // Create a Secret
           std::string secretName("MySampleSecret");
           std::string secretValue("My super secret value");
           secretClient.SetSecret(secretName, secretValue);
   
           // Get the Secret
           KeyVaultSecret secret = secretClient.GetSecret(secretName).Value;
           std::string valueString = secret.Value.HasValue()
                                         ? secret.Value.Value()
                                         : "NONE RETURNED";
           std::cout << "Secret is returned with name " << secret.Name
                     << " and value " << valueString << std::endl;
       }
       catch (Azure::Core::Credentials::AuthenticationException const &e)
       {
           std::cout << "Authentication Exception happened:" << std::endl
                     << e.what() << std::endl;
           return 1;
       }
       catch (Azure::Core::RequestFailedException const &e)
       {
           std::cout << "Key Vault Secret Client Exception happened:" << std::endl
                     << e.Message << std::endl;
           return 1;
       }
   
       return 0;
   }
   

3. Создайте каталог сборки для результатов сборки.

Сборка и запуск

В этом разделе описывается настройка и сборка проекта с помощью команд CMake, а затем запуск программы, чтобы убедиться, что все настроено правильно. Команды в этом разделе должны выполняться из корневого каталога вашего проекта, где находятся каталог build, CMakeLists.txt и файлы main.cpp.

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

Группа ресурсов не найдена

При использовании AzureCLI для создания экземпляра Key Vault, если вы получаете следующую ошибку, это означает, что группа ресурсов, в которую вы пытаетесь добавить экземпляр Key Vault, не существует.

(ResourceGroupNotFound) Resource group '<your-resource-group-name>' could not be found.
Code: ResourceGroupNotFound
Message: Resource group '<your-resource-group-name>' could not be found.

Чтобы создать группу ресурсов, можно использовать следующую команду:

az group create --name <your-resource-group-name> --location <your-resource-group-location>

Дополнительные сведения см. в документации AzureCLI по управлению группами ресурсов Azure.

CMake не может найти пакеты для Azure при настройке или сборке

При выполнении команд настройки CMake или сборки, если вы получаете следующую ошибку или что-то подобное, файл CMakeLists.txt не запускает модуль vcpkg.cmake перед созданием проекта CMake или не запускается вообще.

CMake Error at CMakeLists.txt:12 (find_package):
  Could not find a package configuration file provided by
  "azure-identity-cpp" with any of the following names:

    azure-identity-cppConfig.cmake
    azure-identity-cpp-config.cmake

  Add the installation prefix of "azure-identity-cpp" to CMAKE_PREFIX_PATH or
  set "azure-identity-cpp_DIR" to a directory containing one of the above
  files.  If "azure-identity-cpp" provides a separate development package or
  SDK, be sure it has been installed.

Убедитесь в CMakeLists.txt файле, что set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg-root/scripts/buildsystems/vcpkg.cmake") строка выше project(azure_sample VERSION 0.1.0 LANGUAGES C CXX).

Затем убедитесь, что /path/to/vcpkg-root/ в строке set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg-root/scripts/buildsystems/vcpkg.cmake") обновлено на расположение, в котором был установлен vcpkg.

Синтаксическая ошибка в коде cmake

При выполнении команд конфигурации CMake или сборки, если вы получите следующую ошибку, файл CMakeLists.txt может содержать пути с \. Эта проблема может быть распространенной при использовании путей Windows.

Syntax error in cmake code at

    C:/Users/username/Desktop/CppProject/CMakeLists.txt:6

  when parsing string

    C:\Users\username\vcpkg\scripts\buildsystems\vcpkg.cmake

  Invalid character escape '\U'.

Несмотря на то, что Windows использует \ в путях к файлам, CMake использует только / в путях к файлам. Проблему можно устранить, заменив все \ на / в путях, используемых в файле CMakeLists.txt.

Если ошибка сохраняется после внесения изменений, обратитесь к ошибкам CMake после внесения изменений , чтобы узнать, как их устранить.

Ошибки CMake сохраняются после внесения изменений

При выполнении команды настройки CMake при продолжении получения той же ошибки после внесения изменений в нее попробуйте очистить кэш CMake. Кэш CMake можно очистить, удалив содержимое каталога build, а затем повторно выполнить команду настройки CMake.

Требуется CMake версии 3.30 или выше

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

CMake Error at CMakeLists.txt:2 (cmake_minimum_required):
  CMake 3.30.0 or higher is required.  You are running version 3.25.0

Чтобы устранить эту ошибку, обновите установку CMake до версии, указанной в сообщении об ошибке.

Вызывающий объект не авторизован для выполнения действия на ресурсе

При запуске примера программы C++ при получении ошибки, как показано ниже, у вас нет соответствующих разрешений на работу с секретами в указанном ресурсе Key Vault.

Key Vault Secret Client Exception happened:
Caller is not authorized to perform action on resource.
If role assignments, deny assignments or role definitions were changed recently, please observe propagation time.
Caller: <redacted-application-information>
Action: 'Microsoft.KeyVault/vaults/secrets/setSecret/action'
Resource: <redacted-resource-information>
Assignment: (not found)
DenyAssignmentId: null
DecisionReason: null 
Vault: <your-key-vault-name>;location=<your-key-vault-location>

Соответствующие разрешения можно предоставить учетной записи с помощью портала Azure или Azure CLI.

Чтобы обновить разрешения с помощью портала Azure, перейдите на страницу управления доступом (IAM) ресурса Key Vault. Выберите раскрывающийся список "Добавить" и выберите "Добавить назначение роли". На странице "Роль" выберите роль офицера по работе с секретами Key Vault и нажмите "Далее" в нижней части страницы. На странице «Участники» оставьте опцию «Назначить доступ для» на «Пользователь, группа или служебный принципал» и выберите ссылку «Выбрать участников». Во всплывающем окне справа найдите и выберите ваш идентификатор, затем нажмите Выбрать внизу всплывающего окна. Выбранный идентификатор должен отображаться в таблице раздела "Члены ". Нажмите кнопку "Проверить и назначить " в нижней части экрана. Затем снова нажмите кнопку "Проверить и назначить ".

Чтобы обновить разрешения с помощью Azure CLI, введите следующую команду, заменив <upn> вашим именем участника-пользователя, <subscription-id> вашим идентификатором подписки, <resource-group-name> именем группы ресурсов, и <your-unique-keyvault-name> именем экземпляра Key Vault.

az role assignment create --role "Key Vault Secrets Officer" --assignee "<upn>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

VS Code включает ошибки

Если под вашими операторами #include в VS Code появляются строки ошибок (как показано на следующем изображении), это означает, что редактор не знает, где находится каталог для include.

vcpkg размещает заголовки для включения в build/vcpkg_installed/<vcpkg-platform-triplet>/include, когда активирован режим манифеста. Замените <vcpkg-platform-triplet> на vcpkg triplet для вашей платформы.

Чтобы добавить каталог include в параметры VS Code, наведите указатель мыши на инструкцию include со строкой ошибки. Затем выберите ссылку "Быстрое исправление", расположенную в нижней части всплывающего окна. В параметрах быстрого исправления выберите «Добавить в "includePath": ${workspaceFolder}/build/vcpkg_installed/<vcpkg-platform-triplet>/include». Вкладка "Конфигурация расширения C/C++" должна открыться и в разделе "Путь включения" должен отобразиться путь к каталогу включения.

Linux bootstrap-vcpkg не удалось найти зависимости

При запуске скрипта bootstrap-vcpkg.sh в Linux, если вы получите ошибку, как показано ниже, у вас нет необходимых средств для запуска скрипта.

Could not find zip. Please install it (and other dependencies) with:
On Debian and Ubuntu derivatives:
  sudo apt-get install curl zip unzip tar
On recent Red Hat and Fedora derivatives:
  sudo dnf install curl zip unzip tar
On older Red Hat and Fedora derivatives:
  sudo yum install curl zip unzip tar
On SUSE Linux and derivatives:
  sudo zypper install curl zip unzip tar
On Arch Linux and derivatives:
  sudo pacman -Syu base-devel git curl zip unzip tar cmake ninja
On Alpine:
  apk add build-base cmake ninja zip unzip curl git
  (and export VCPKG_FORCE_SYSTEM_BINARIES=1)

Чтобы установить средства, используйте указанную команду в сообщении об ошибке для дистрибутива Linux. Например, в Ubuntu это будет следующая команда:

sudo apt-get install curl zip unzip tar

Затем повторно запустите bootstrap-vcpkg.sh скрипт.

Не удалось найти файл цепочки инструментов Linux

При выполнении команды настройки CMake, если вы получили сообщение об ошибке, как показано ниже, путь к модулям vcpkg.cmake не был правильно задан.

CMake Error at /usr/share/cmake-3.28/Modules/CMakeDetermineSystem.cmake:176 (message):
  Could not find toolchain file:
  /path/to/vcpkg-root/scripts/buildsystems/vcpkg.cmake
Call Stack (most recent call first):
  CMakeLists.txt:9 (project)

В файлеCMakeLists.txt обновите инструкцию set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake") с правильным путем к месту установки vcpkg.

Сбой установки vcpkg для Linux

При выполнении команды настройки CMake, если вы получите ошибку, как приведено ниже, должны быть установлены системные зависимости для пакетов.

CMake Error at /path/to/vcpkg/scripts/buildsystems/vcpkg.cmake:904 (message):
  vcpkg install failed.  See logs for more information:

Чтобы найти нужные системные пакеты, выполните поиск команд конфигурации CMake для строк, начинающихся с Could not find <system-package>, и замените <system-package> на отсутствующий системный пакет. Под этой строкой должна быть команда для установки отсутствующего системного пакета. Выполните следующую команду. Затем повторно запустите команду конфигурации CMake. Этот процесс может потребоваться повторить несколько раз в зависимости от количества отсутствующих системных пакетов.

Следующий шаг