Udostępnij za pomocą

Instalowanie i integrowanie bibliotek z zestawu Azure SDK dla języka C++

Ten przewodnik zawiera deweloperom niezbędne kroki instalowania bibliotek z zestawu Azure SDK dla języka C++ przy użyciu narzędzia vcpkg i integrowania ich z projektami za pomocą narzędzia CMake. Postępując zgodnie z instrukcjami, możesz skonfigurować środowisko deweloperskie i rozpocząć korzystanie z usług platformy Azure w aplikacjach języka C++. Niezależnie od tego, czy dopiero zaczynasz korzystać z platformy Azure, czy chcesz usprawnić proces integracji, ta dokumentacja ułatwia szybkie i wydajne rozpoczęcie pracy.

Wymagania wstępne

Weryfikowanie instalacji narzędzia Git i narzędzia CMake

Aby zapewnić bezproblemowy proces integracji, należy sprawdzić, czy narzędzie Git i narzędzie CMake są poprawnie zainstalowane w systemie.

  1. Aby sprawdzić, czy narzędzie Git jest poprawnie zainstalowane, uruchom następujące polecenie w terminalu:

    git --version

  2. Powinieneś otrzymać dane wyjściowe informujące o aktualnie zainstalowanej wersji narzędzia git, w formacie:

    git version <version>

  3. Aby sprawdzić, czy narzędzie CMake jest poprawnie zainstalowane, uruchom następujące polecenie w terminalu:

    cmake --version

  4. Powinna zostać wyświetlona wersja CMake, która jest obecnie zainstalowana, w następujący sposób:

    cmake version <version>

Instalowanie narzędzia vcpkg

Aby zarządzać i instalować zestaw Azure SDK dla bibliotek języka C++, użyj narzędzia vcpkg. vcpkg to międzyplatformowy menedżer pakietów, który upraszcza proces obsługi zależności.

  1. Aby zainstalować narzędzie vcpkg, najpierw sklonuj repozytorium vcpkg. Zalecaną metodą jest sklonowanie narzędzia vcpkg do centralnej lokalizacji w środowisku projektowym, a nie w katalogu projektu C++. W tym przykładzie narzędzie vcpkg jest klonowane do dir macierzystego.

    cd ~
git clone https://github.com/microsoft/vcpkg.git

  2. Gdy repozytorium vcpkg zostanie sklonowane, przejdź do nowego folderu i uruchom bootstrap-vcpkg.bat skrypt.

    cd .\vcpkg\
.\bootstrap-vcpkg.bat

  3. Po uruchomieniu narzędzia vcpkg dodaj go do ścieżki, aby uzyskać dostęp do pliku wykonywalnego vcpkg z katalogu projektu. Pamiętaj, aby zastąpić element <path\to\vcpkg> w przykładzie polecenia ścieżką do sklonowanego wcześniej katalogu vcpkg.

    $env:Path = "$env:Path;<path\to\vcpkg>"

  4. Aby sprawdzić, czy katalog vcpkg został dodany do ścieżki, przejdź z powrotem do katalogu projektu i uruchom następujące polecenie:

    vcpkg --version

  5. Powinny zostać wyświetlone następujące dane wyjściowe:

    vcpkg package management program version <version>

Instalowanie bibliotek

Ta sekcja przeprowadzi Cię przez proces instalowania niezbędnych bibliotek z zestawu Azure SDK dla języka C++ przy użyciu narzędzia vcpkg. W tej sekcji pokazano, jak używać narzędzia vcpkg w trybie manifestu, który tworzy kilka plików projektu vcpkg, aby ułatwić zarządzanie zależnościami projektu nawet w przypadku udostępniania innym współpracownikom.

  1. W katalogu głównym projektu uruchom następujące polecenie, aby uruchomić nowy projekt vcpkg w trybie manifestu:

    vcpkg new --application

  2. W katalogu projektu powinien być teraz plik vcpkg.json i plik vcpkg-configuration.json .

  3. Teraz możemy dodać biblioteki usługi Azure Key Vault i tożsamości z zestawu Azure SDK dla języka C++ do naszego projektu, uruchamiając następujące polecenie:

    vcpkg add port azure-identity-cpp azure-security-keyvault-secrets-cpp

  4. Plik vcpkg.json powinien teraz zawierać następującą zawartość:

    {
  "dependencies": [
    "azure-identity-cpp",
    "azure-security-keyvault-secrets-cpp"
  ]
}

Tworzenie zasobu usługi Azure Key Vault

W tej sekcji omówiono sposób tworzenia zasobu usługi Azure Key Vault przy użyciu interfejsu wiersza polecenia platformy Azure. Ten zasób usługi Key Vault bezpiecznie przechowuje poufne informacje, takie jak wpisy tajne i klucze, i zarządza nimi.

  1. Użyj interfejsu wiersza polecenia platformy Azure, aby zalogować się, wprowadzając następujące polecenie w terminalu:

    az login

  2. Użyj okien podręcznych, aby zalogować się do platformy Azure.

  3. Po zalogowaniu się przy użyciu okna podręcznego przeglądarki wybierz subskrypcję platformy Azure, której chcesz użyć w terminalu.

  4. Następnie użyj następującego polecenia, aby utworzyć zasób Key Vault, i pamiętaj, aby zastąpić <your-resource-group-name> oraz <your-key-vault-name> własnymi, unikatowymi nazwami.

    az keyvault create --resource-group <your-resource-group-name> --name <your-key-vault-name>

  5. W danych wyjściowych powinna zostać wyświetlona lista właściwości z właściwością vaultUri . Ustaw zmienną środowiskową, która ma być używana w naszym programie, za pomocą następującego polecenia:

    $env:AZURE_KEYVAULT_URL = "https://<your-key-vault-name>.vault.azure.net/"
  1. Na koniec upewnij się, że twoje konto platformy Azure ma odpowiednie uprawnienia do pracy z sekretami usługi Key Vault. Możesz przyznać sobie odpowiednie uprawnienia, przypisując sobie rolę "Key Vault Secrets Officer" na stronie Kontrola dostępu (IAM) zasobu usługi Key Vault w witrynie Azure Portal. IAM oznacza zarządzanie tożsamościami i dostępem.

Konfigurowanie projektu

W tej sekcji opisano proces tworzenia niezbędnych folderów i plików do skonfigurowania projektu azure C++.

  1. W głównym katalogu projektu utwórz plik CMakeLists.txt . Ten plik służy do konfigurowania naszego projektu CMake. Dodaj następujący kod do pliku 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. W głównym katalogu projektu utwórz plik main.cpp. Dodaj następujący kod do pliku 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. Utwórz katalog kompilacji dla artefaktów kompilacji.

Budowanie i uruchamianie

W tej sekcji omówiono sposób konfigurowania i kompilowania projektu przy użyciu poleceń narzędzia CMake, a następnie uruchamiania programu w celu upewnienia się, że wszystko jest skonfigurowane poprawnie. Polecenia w tej sekcji powinny być uruchamiane z katalogu głównego projektu, w którym znajduje się katalog build, oraz pliki CMakeLists.txt i main.cpp.

  1. Aby skonfigurować narzędzie CMake, wprowadź następujące polecenie:

    cmake -B ./build

  2. Aby skompilować projekt, wprowadź następujące polecenie:

    cmake --build ./build

  3. Aby uruchomić program, wprowadź następujące polecenie:

    .\build\Debug\azure_sample.exe

  4. Program powinien mieć następujące dane wyjściowe:

    Secret is returned with name MySampleSecret and value My super secret value

Rozwiązywanie problemów

Nie można odnaleźć grupy zasobów

Podczas korzystania z narzędzia AzureCLI do tworzenia wystąpienia usługi Key Vault, jeśli pojawi się następujący błąd, oznacza to, że grupa zasobów, do której próbujesz dodać wystąpienie, nie istnieje.

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

Aby utworzyć grupę zasobów, możesz użyć następującego polecenia:

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

Aby uzyskać więcej informacji, zapoznaj się z dokumentami platformy AzureCLI dotyczącymi zarządzania grupami zasobów platformy Azure.

Konfigurowanie lub kompilowanie narzędzia CMake nie może znaleźć pakietów platformy Azure

Podczas uruchamiania poleceń konfiguracji lub budowania CMake, jeśli zostanie wyświetlony następujący błąd lub coś podobnego, plik CMakeLists.txt nie uruchamia modułu vcpkg.cmake przed ustanowieniem projektu CMake lub w ogóle.

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.

Sprawdź w pliku CMakeLists.txt , czy set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg-root/scripts/buildsystems/vcpkg.cmake") wiersz znajduje się powyżej project(azure_sample VERSION 0.1.0 LANGUAGES C CXX).

Następnie sprawdź również, czy element /path/to/vcpkg-root/ w set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg-root/scripts/buildsystems/vcpkg.cmake") wierszu został zaktualizowany do lokalizacji, w której zainstalowano narzędzie vcpkg.

Błąd składniowy w kodzie narzędzia cmake

Jeśli podczas uruchamiania polecenia konfiguracji lub kompilacji narzędzia CMake wystąpi następujący błąd, plik CMakeLists.txt może zawierać ścieżki przy użyciu polecenia \. Ten problem może być typowy podczas korzystania ze ścieżek 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'.

Mimo że system Windows używa \ w ścieżkach plików, narzędzie CMake używa / tylko w ścieżkach plików. Problem można rozwiązać, zastępując wszystkie \ elementami / w ścieżkach używanych w pliku CMakeLists.txt .

Jeśli błąd będzie się powtarzać po wprowadzeniu zmiany, zapoznaj się z sekcją Błędy narzędzia CMake utrwalone po wprowadzeniu zmian , aby dowiedzieć się, jak je rozwiązać.

Błędy narzędzia CMake są utrwalane po wprowadzeniu zmian

Jeśli podczas uruchamiania polecenia konfiguracji narzędzia CMake po wprowadzeniu zmian zostanie wyświetlony ten sam błąd, spróbuj wyczyścić pamięć podręczną CMake. Cache CMake można wyczyścić, usuwając zawartość katalogu build, a następnie ponownie uruchamiając polecenie konfiguracji narzędzia CMake.

Wymagany program CMake 3.30 lub nowszy

Jeśli podczas uruchamiania polecenia konfiguracji narzędzia CMake wystąpi błąd podobny do poniższego, może być konieczne zaktualizowanie wersji narzędzia 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

Aby rozwiązać ten błąd, zaktualizuj instalację narzędzia CMake do wersji podanej w komunikacie o błędzie.

Obiekt wywołujący nie ma autoryzacji do wykonywania akcji na zasobie

Jeśli podczas uruchamiania przykładowego programu C++ wystąpi błąd podobny do poniższego, nie masz odpowiednich uprawnień do pracy z wpisami tajnymi w określonym zasobie usługi 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>

Odpowiednie uprawnienia można nadać twojemu kontu przy użyciu witryny Azure Portal lub interfejsu wiersza polecenia platformy Azure.

Aby zaktualizować uprawnienia przy użyciu witryny Azure Portal, przejdź do strony Kontrola dostępu (zarządzanie dostępem i tożsamościami) zasobu usługi Key Vault. Wybierz listę rozwijaną Dodaj i wybierz pozycję Dodaj przypisanie roli. Na stronie Rola wybierz rolę Oficer tajnych danych Key Vault, a następnie wybierz Dalej w dolnej części strony. Na stronie Członkowie pozostaw opcję Przypisz dostęp do w obszarze Użytkownik, grupa lub jednostka usługi i wybierz link Wybierz członków . W wyskakującym okienku po prawej stronie wyszukaj i wybierz swój identyfikator, a następnie wybierz pozycję Wybierz w dolnej części wyskakującego okienka. Wybrany identyfikator powinien być teraz wyświetlany w tabeli sekcji Członkowie . Wybierz przycisk Przejrzyj i przypisz w dolnej części strony. Następnie ponownie wybierz przycisk Przejrzyj i przypisz .

Aby zaktualizować swoje uprawnienia przy użyciu interfejsu wiersza polecenia platformy Azure, wprowadź następujące polecenie, zastępując <upn> swoją nazwą główną użytkownika, <subscription-id> swoim identyfikatorem subskrypcji, <resource-group-name> nazwą swojej grupy zasobów i <your-unique-keyvault-name> nazwą swojego wystąpienia usługi 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>"

Program VS Code zawiera błędy

Jeśli widzisz linie błędów pod instrukcjami 'include' podczas korzystania z programu VS Code (pokazanej na poniższym obrazku), edytor nie wie, gdzie znaleźć katalog include.

{Zrzut ekranu przedstawiający instrukcje #include w języku C++ w programie VS Code, które mają czerwone faliste linie błędu poniżej.}

Narzędzie vcpkg umieszcza pliki nagłówkowe w build/vcpkg_installed/<vcpkg-platform-triplet>/include w trybie manifestu. Zastąp <vcpkg-platform-triplet> trójką vcpkg dla twojej platformy.

Aby dodać katalog include do ustawień programu VS Code, najedź kursorem na instrukcję include z wierszem błędu. Następnie wybierz link Szybka poprawka... w dolnej części wyskakującego okienka. W opcjach szybkiej poprawki wybierz opcję Dodaj do "includePath": ${workspaceFolder}/build/vcpkg_installed/<vcpkg-platform-triplet>/include . Karta Konfiguracja rozszerzenia C/C++ powinna zostać otwarta, a w sekcji "Ścieżka dołączenia" powinna być wyświetlona lista ścieżek do katalogów dołączania.

Nie można odnaleźć zależności dla bootstrap-vcpkg w systemie Linux

Jeśli podczas uruchamiania skryptu bootstrap-vcpkg.sh w systemie Linux wystąpi błąd podobny do poniższego, nie masz zainstalowanych narzędzi niezbędnych do uruchomienia skryptu.

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)

Aby zainstalować narzędzia, użyj podanego polecenia w komunikacie o błędzie dystrybucji systemu Linux. Na przykład w systemie Ubuntu będzie to następujące polecenie:

sudo apt-get install curl zip unzip tar

Następnie ponownie uruchom skrypt bootstrap-vcpkg.sh.

Nie można odnaleźć pliku łańcucha narzędzi w systemie Linux

Jeśli podczas uruchamiania polecenia konfiguracji narzędzia CMake zostanie wyświetlony błąd podobny do poniższego, ścieżka do modułów vcpkg.cmake nie została prawidłowo ustawiona.

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)

W pliku CMakeLists.txt zaktualizuj deklarację set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake") poprawną ścieżką do miejsca, w którym zainstalowano vcpkg.

Instalacja narzędzia vcpkg systemu Linux nie powiodła się

Jeśli podczas uruchamiania polecenia CMake configure wystąpi błąd podobny do poniższego, zależności systemowe dla pakietów muszą być zainstalowane.

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

Aby znaleźć potrzebne pakiety systemowe, wyszukaj dane wyjściowe poleceń konfiguracji narzędzia CMake dla wierszy rozpoczynających się od Could not find <system-package>, zastępując <system-package> element brakującym pakietem systemowym. Poniżej tego wiersza powinno znajdować się polecenie umożliwiające zainstalowanie brakującego pakietu systemowego. Uruchom to polecenie. Następnie uruchom ponownie polecenie konfiguracji narzędzia CMake. Może być konieczne powtórzenie tego procesu kilka razy w zależności od liczby brakujących pakietów systemowych.

Następny krok

  • Last updated on