Instalace a integrace knihoven ze sady Azure SDK pro C++

2025-05-08

Tato příručka poskytuje vývojářům nezbytné kroky k instalaci knihoven ze sady Azure SDK pro C++ pomocí vcpkg a jejich integraci do svých projektů pomocí CMake. Podle pokynů můžete nastavit vývojové prostředí a začít používat služby Azure v aplikacích C++. Bez ohledu na to, jestli s Azure začínáte, nebo chcete zjednodušit proces integrace, vám tato dokumentace pomůže rychle a efektivně začít.

Požadavky

Libovolný textový editor
Terminál
Kompilátor C++
Git
CMake
Předplatné Azure
Azure CLI

Ověření instalace Gitu a CMake

Pokud chcete zajistit hladký proces integrace, je důležité ověřit, že git a CMake jsou ve vašem systému správně nainstalované.

Windows – PowerShell
MacOS/Linux – Bash

Pokud chcete ověřit, že je git správně nainstalovaný, spusťte v terminálu následující příkaz:
```
git --version
```
Měli byste získat výstup, který označuje aktuálně nainstalovanou verzi gitu, například takto:
```
git version <version>
```
Pokud chcete ověřit, že je CMake správně nainstalovaný, spusťte v terminálu následující příkaz:
```
cmake --version
```
Měli byste získat výstup, který označuje aktuálně nainstalovanou verzi CMake, například takto:
```
cmake version <version>
```

Pokud chcete ověřit, že je git správně nainstalovaný, spusťte v terminálu následující příkaz:
```
git --version
```
Měli byste získat výstup, který označuje aktuálně nainstalovanou verzi gitu, například takto:
```
git version <version>
```
Pokud chcete ověřit, že je CMake správně nainstalovaný, spusťte v terminálu následující příkaz:
```
cmake --version
```
Měli byste získat výstup, který označuje aktuálně nainstalovanou verzi CMake, například takto:
```
cmake version <version>
```

Instalace vcpkg

Ke správě a instalaci knihoven Azure SDK pro C++ použijte vcpkg. vcpkg je správce balíčků pro různé platformy, který zjednodušuje proces zpracování závislostí.

Windows – PowerShell
MacOS/Linux – Bash

Pokud chcete nainstalovat vcpkg, nejprve naklonujte úložiště vcpkg. Doporučeným přístupem je klonování vcpkg do centrálního umístění ve vývojovém prostředí, nikoli v adresáři projektu C++. V tomto příkladu se vcpkg naklonuje do domovského adresáře.
```
cd ~
git clone https://github.com/microsoft/vcpkg.git
```
Po naklonování úložiště vcpkg přejděte do nového adresáře a spusťte bootstrap-vcpkg.bat skript.
```
cd .\vcpkg\
.\bootstrap-vcpkg.bat
```
Po spuštění vcpkg ho přidejte do své cesty, abyste měli přístup ke spustitelnému souboru vcpkg z adresáře projektu. Nezapomeňte nahradit <path\to\vcpkg> v příkladu příkazu cestou k adresáři vcpkg, který jste naklonovali dříve.
```
$env:Path = "$env:Path;<path\to\vcpkg>"
```
Pokud chcete ověřit, že se adresář vcpkg přidal do cesty, přejděte zpět do adresáře projektu a spusťte následující příkaz:
```
vcpkg --version
```

Měl by se zobrazit následující výstup:

vcpkg package management program version <version>

Pokud chcete nainstalovat vcpkg, nejprve naklonujte úložiště vcpkg. Doporučeným přístupem je klonování vcpkg do centrálního umístění ve vývojovém prostředí, nikoli v adresáři projektu C++. V tomto příkladu se vcpkg naklonuje do domovského adresáře.
```
cd ~
git clone https://github.com/microsoft/vcpkg.git
```
Po naklonování úložiště vcpkg přejděte do nového adresáře a spusťte bootstrap-vcpkg.sh skript.
```
cd vcpkg
./bootstrap-vcpkg.sh
```
Po spuštění vcpkg ho přidejte do své cesty, abyste měli přístup ke spustitelnému souboru vcpkg z adresáře projektu. Nezapomeňte nahradit <path\to\vcpkg> v příkladu příkazu cestou k adresáři vcpkg, který jste naklonovali dříve.
```
export PATH=$PATH:/path/to/vcpkg
```
Pokud chcete ověřit, že se adresář vcpkg přidal do cesty, přejděte zpět do adresáře projektu a spusťte následující příkaz:
```
vcpkg --version
```

Měl by se zobrazit následující výstup:

vcpkg package management program version <version>

Instalace knihoven

Tato část vás provede procesem instalace potřebných knihoven ze sady Azure SDK pro C++ pomocí vcpkg. Tato část ukazuje, jak používat vcpkg v režimu manifestu, který vytvoří několik souborů projektu vcpkg, které pomáhají spravovat závislosti projektu i při sdílení s ostatními spolupracovníky.

Windows – PowerShell
MacOS/Linux – Bash

V kořenovém adresáři projektu spusťte následující příkaz, který spustí nový projekt vcpkg v režimu manifestu:
```
vcpkg new --application
```
V adresáři projektu by teď měl být soubor vcpkg.json a soubor vcpkg-configuration.json .
Teď můžeme do našeho projektu přidat knihovny Azure Key Vault a identity ze sady Azure SDK pro C++, a to spuštěním následujícího příkazu:
```
vcpkg add port azure-identity-cpp azure-security-keyvault-secrets-cpp
```

Soubor vcpkg.json by teď měl mít následující obsah:

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

V kořenovém adresáři projektu spusťte následující příkaz, který spustí nový projekt vcpkg v režimu manifestu:
```
vcpkg new --application
```
V adresáři projektu by teď měl být soubor vcpkg.json a soubor vcpkg-configuration.json .
Teď můžeme do našeho projektu přidat knihovny Azure Key Vault a identity ze sady Azure SDK pro C++, a to spuštěním následujícího příkazu:
```
vcpkg add port azure-identity-cpp azure-security-keyvault-secrets-cpp
```

Soubor vcpkg.json by teď měl mít následující obsah:

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

Vytvořit prostředek Azure Key Vault

Tato část popisuje, jak pomocí Azure CLI vytvořit prostředek služby Azure Key Vault. Tento prostředek služby Key Vault bezpečně ukládá a spravuje citlivé informace, jako jsou tajné kódy a klíče.

Windows – PowerShell
MacOS/Linux – Bash

Pomocí Azure CLI se přihlaste zadáním následujícího příkazu v terminálu:
```
az login
```
Pomocí automaticky otevíraných oken se přihlaste k Azure.
Po přihlášení pomocí automaticky otevíraných oken prohlížeče vyberte předplatné Azure, které chcete použít v terminálu.
Pak pomocí následujícího příkazu vytvořte zdroj služby Key Vault a nezapomeňte nahradit <your-resource-group-name> a <your-key-vault-name> vlastními jedinečnými názvy.
```
az keyvault create --resource-group <your-resource-group-name> --name <your-key-vault-name>
```
Ve výstupu by se měl zobrazit seznam vlastností s vaultUri vlastností. Nastavte ji na proměnnou prostředí, která se má použít v našem programu, pomocí následujícího příkazu:
```
$env:AZURE_KEYVAULT_URL = "https://<your-key-vault-name>.vault.azure.net/"
```

Pomocí Azure CLI se přihlaste zadáním následujícího příkazu v terminálu:
```
az login
```
Pomocí automaticky otevíraných oken se přihlaste k Azure.
Po přihlášení pomocí automaticky otevíraných oken prohlížeče vyberte předplatné Azure, které chcete použít v terminálu.
Pak pomocí následujícího příkazu vytvořte zdroj služby Key Vault a nezapomeňte nahradit <your-resource-group-name> a <your-key-vault-name> vlastními jedinečnými názvy.
```
az keyvault create --resource-group <your-resource-group-name> --name <your-key-vault-name>
```
Ve výstupu by se měl zobrazit seznam vlastností s vaultUri vlastností. Nastavte ji na proměnnou prostředí, která se má použít v našem programu, pomocí následujícího příkazu:
```
export AZURE_KEYVAULT_URL="https://<your-key-vault-name>.vault.azure.net/"
```

Nakonec se ujistěte, že váš účet Azure má správná oprávnění pro práci s tajnými klíči služby Key Vault. Správná oprávnění si můžete udělit přiřazením role "Key Vault Secrets Officer" na stránce řízení přístupu (IAM) vašeho prostředku Key Vault v portálu Azure. IAM je zkratka pro správu identit a přístupu.

Nastavení projektu

Tato část popisuje proces vytváření potřebných složek a souborů k nastavení projektu Azure C++.

V kořenovém adresáři projektu vytvořte souborCMakeLists.txt . Tento soubor slouží ke konfiguraci projektu CMake. Do souboru CMakeLists.txt přidejte následující kód:

# 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
)

V kořenovém adresáři projektu vytvořte soubor main.cpp . Do souboru main.cpp přidejte následující kód:

#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;
}

Vytvořte adresář sestavení pro artefakty sestavení.

Sestavení a spuštění

Tato část popisuje, jak nakonfigurovat a sestavit projekt pomocí příkazů CMake, a pak spustit program, aby se zajistilo správné nastavení všeho. Příkazy v této části by se měly spouštět z kořenového adresáře vašeho projektu, kde se nachází adresář build, soubory CMakeLists.txt a main.cpp.

Windows – PowerShell
MacOS/Linux – Bash

Pokud chcete nakonfigurovat CMake, zadejte následující příkaz:
```
cmake -B ./build
```
Pokud chcete projekt sestavit, zadejte následující příkaz:
```
cmake --build ./build
```
Pokud chcete program spustit, zadejte následující příkaz:
```
.\build\Debug\azure_sample.exe
```

Program by měl mít následující výstup:

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

Pokud chcete nakonfigurovat CMake, zadejte následující příkaz:
```
cmake -B ./build
```
Pokud chcete projekt sestavit, zadejte následující příkaz:
```
cmake --build ./build
```
Pokud chcete program spustit, zadejte následující příkaz:
```
./build/azure_sample
```

Program by měl mít následující výstup:

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

Řešení problémů

Skupina prostředků nebyla nalezena.

Pokud při vytváření instance služby Key Vault používáte AzureCLI, zobrazí se následující chyba, skupina prostředků, do které se pokoušíte přidat instanci služby Key Vault, neexistuje.

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

K vytvoření skupiny prostředků můžete použít následující příkaz:

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

Další informace najdete v dokumentaci k AzureCLI o správě skupin prostředků Azure.

Konfigurace nebo sestavení CMake nemůže najít balíky Azure

Pokud se při spuštění příkazů pro konfiguraci nebo sestavení CMake zobrazí následující chyba nebo něco podobného, soubor CMakeLists.txt nespouští modul vcpkg.cmake před vytvořením projektu CMake nebo ho nespouští vůbec.

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.

Ověřte v souboru CMakeLists.txt, zda je řádek set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg-root/scripts/buildsystems/vcpkg.cmake") nad project(azure_sample VERSION 0.1.0 LANGUAGES C CXX).

Pak také ověřte, že umístění, kde byla nainstalována vcpkg, je na řádku /path/to/vcpkg-root/ aktualizováno.

Chyba syntaxe v kódu cmake

Pokud se při spuštění konfigurace nebo sestavení pomocí CMake zobrazí následující chyba, soubor CMakeLists.txt může obsahovat cesty pomocí \. Tento problém může být běžný při použití cest 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'.

I když Windows používá \ v cestách k souborům, CMake používá v cestách k souborům pouze /. Problém lze vyřešit nahrazením všech \, / cest použitých v souboruCMakeLists.txt.

Pokud chyba po provedení změny přetrvává, přečtěte si informace o tom, jak je vyřešit, v části věnované chybám CMake .

Chyby CMake se po provedení změn zachovají

Pokud se při spuštění příkazu CMake configure zobrazí stejná chyba i po provedení změn, zkuste vymazat mezipaměť CMake. Mezipaměť CMake je možné vymazat odstraněním obsahu adresáře sestavení a opětovným zadáním příkazu CMake configure.

Vyžaduje se CMake 3.30 nebo vyšší

Pokud se při spuštění příkazu CMake configure zobrazí chyba podobná následující, možná budete muset aktualizovat svoji verzi 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

Pokud chcete tuto chybu vyřešit, aktualizujte instalaci CMake na verzi uvedenou v chybové zprávě.

Volající nemá oprávnění k provedení úkonu na zdroji.

Pokud se při spuštění ukázkového programu C++ zobrazí chyba podobná následující, nemáte správná oprávnění pro práci s tajnými kódy u zadaného prostředku služby 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>

Ke svému účtu je možné udělit správná oprávnění pomocí webu Azure Portal nebo Azure CLI.

Pokud chcete aktualizovat oprávnění pomocí webu Azure Portal, přejděte na stránku Řízení přístupu (IAM) vašeho prostředku služby Key Vault. Vyberte rozevírací seznam Přidat a vyberte možnost přiřadit roli. Na stránce Role vyberte roli Důstojník správy tajemství Key Vault a v dolní části stránky vyberte Další. Na stránce Členové ponechte možnost Přiřadit přístup k nastavenou na Uživatel, skupina nebo hlavní služba a klikněte na odkaz Vybrat členy. V automaticky otevíraném okně vpravo vyhledejte a vyberte své ID, poté zvolte Select v dolní části okna. Vybrané ID by se teď mělo zobrazit v tabulce oddílu Členové . Vyberte tlačítko Zkontrolovat a přiřadit dole. Pak znovu vyberte tlačítko Zkontrolovat a přiřadit .

Pokud chcete aktualizovat oprávnění pomocí Azure CLI, zadejte následující příkaz, nahraďte <upn> hlavním názvem uživatele, <subscription-id> ID předplatného, <resource-group-name> názvem vaší skupiny prostředků a <your-unique-keyvault-name> názvem vaší instance služby 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 zahrnuje chyby

Pokud se při použití editoru VS Code (na následujícím obrázku) zobrazí chybové řádky pod příkazy include, editor neví, kde najít adresář zahrnutí.

{Snímek obrazovky s příkazy C++ include z editoru VS Code, které mají pod sebou červené vlnovky.}

vcpkg umístí záhlaví zahrnutí do build/vcpkg_installed/<vcpkg-platform-triplet>/include v režimu manifestu. Nahraďte <vcpkg-platform-triplet> trojitým vcpkg pro vaši platformu.

Pokud chcete přidat adresář include do nastavení VS Code, najeďte myší na příkaz include s chybovým řádkem. Pak vyberte odkaz Rychlá oprava... v dolní části automaticky otevíraného okna. V možnostech Rychlá oprava vyberte možnost Přidat do "includePath": ${workspaceFolder}/build/vcpkg_installed/<vcpkg-platform-triplet>/include . Otevře se karta konfigurace rozšíření C/C++ a v části "Include path" by se měla zobrazit cesta k zahrnujícímu adresáři.

Linux bootstrap-vcpkg nemohl najít závislosti

Pokud se při spuštění bootstrap-vcpkg.sh skriptu v Linuxu zobrazí chyba podobná následující, nemáte nainstalované potřebné nástroje ke spuštění skriptu.

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)

K instalaci nástrojů použijte zadaný příkaz v chybové zprávě pro vaši linuxovou distribuci. Například v Ubuntu by to byl následující příkaz:

sudo apt-get install curl zip unzip tar

Pak znovu spusťte bootstrap-vcpkg.sh skript.

V Linuxu se nepodařilo najít soubor sady nástrojů

Pokud se při spuštění příkazu CMake configure zobrazí chyba podobná následující, cesta k modulům vcpkg.cmake nebyla správně nastavena.

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)

V souboruCMakeLists.txt aktualizujte set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake") příkaz se správnou cestou k umístění instalace vcpkg.

Instalace linuxové vcpkg se nezdařila.

Pokud se při spuštění příkazu CMake configure zobrazí chyba podobná následující, musí být nainstalovány systémové závislosti pro balíčky.

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

Pokud chcete najít potřebné systémové balíčky, vyhledejte ve výstupu konfiguračních příkazů CMake řádky, které začínají na Could not find <system-package>, a nahraďte <system-package> chybějícím systémovým balíčkem. Pod tímto řádkem by měl být příkaz pro instalaci chybějícího systémového balíčku. Spusťte tento příkaz. Pak znovu spusťte konfigurační příkaz CMake. Tento proces možná budete muset opakovat několikrát v závislosti na počtu chybějících systémových balíčků.

Sdílet prostřednictvím