安裝並整合來自適用於 C++ 的 Azure SDK 的程式庫

本指南提供開發人員使用 vcpkg 從 Azure SDK 安裝 C++ 程式庫的必要步驟，並將其使用 CMake 整合到專案中。依照指示，您可以設定開發環境，並開始在C++應用程式中使用 Azure 服務。無論您是 Azure 新手，還是想要簡化整合程式，本文件都協助您快速且有效率地開始使用。

先決條件

任何文字編輯器
終端機
C++編譯程式
git
CMake
Azure 訂用帳戶
Azure CLI

確認 git 和 CMake 安裝

為了確保順暢的整合程式，請務必確認 Git 和 CMake 已正確安裝在您的系統上。

Windows - PowerShell
MacOS/Linux - Bash

若要確認 Git 是否已正確安裝，請在終端機中執行下列命令：
```
git --version
```
您應該取得輸出，指出目前已安裝的 git 版本，如下所示：
```
git version <version>
```
若要確認 CMake 是否已正確安裝，請在終端機中執行下列命令：
```
cmake --version
```
您應該取得輸出，指出目前安裝的 CMake 版本，如下所示：
```
cmake version <version>
```

若要確認 Git 是否已正確安裝，請在終端機中執行下列命令：
```
git --version
```
您應該取得輸出，指出目前已安裝的 git 版本，如下所示：
```
git version <version>
```
若要確認 CMake 是否已正確安裝，請在終端機中執行下列命令：
```
cmake --version
```
您應該取得輸出，指出目前安裝的 CMake 版本，如下所示：
```
cmake version <version>
```

安裝 vcpkg

若要管理及安裝適用於C++連結庫的 Azure SDK，請使用 vcpkg。 vcpkg 是跨平臺套件管理員，可簡化處理相依性的程式。

Windows - PowerShell
MacOS/Linux - Bash

若要安裝 vcpkg，請先複製 vcpkg 存放庫。建議的方法是將 vcpkg 複製到開發環境的中央位置，而不是在C++項目目錄中。在此範例中，vcpkg 會複製到 home dir。
```
cd ~
git clone https://github.com/microsoft/vcpkg.git
```
複製 vcpkg 存放庫之後，請周遊至新的目錄並執行 bootstrap-vcpkg.bat 腳本。
```
cd .\vcpkg\
.\bootstrap-vcpkg.bat
```
啟動載入 vcpkg 之後，請將它新增至您的路徑，以便您可以從專案目錄存取 vcpkg 可執行檔。請記得將命令範例中的 <path\to\vcpkg> 取代為您稍早克隆的 vcpkg 目錄的路徑。
```
$env:Path = "$env:Path;<path\to\vcpkg>"
```
若要確認 vcpkg 目錄已新增至您的路徑，請周遊回您的專案目錄，然後執行下列命令：
```
vcpkg --version
```

您應該會取得下列輸出：

vcpkg package management program version <version>

若要安裝 vcpkg，請先複製 vcpkg 存放庫。建議的方法是將 vcpkg 複製到開發環境的中央位置，而不是在C++項目目錄中。在此範例中，vcpkg 會複製到 home dir。
```
cd ~
git clone https://github.com/microsoft/vcpkg.git
```
複製 vcpkg 存放庫之後，請周遊至新的目錄並執行 bootstrap-vcpkg.sh 腳本。
```
cd vcpkg
./bootstrap-vcpkg.sh
```
啟動載入 vcpkg 之後，請將它新增至您的路徑，以便您可以從專案目錄存取 vcpkg 可執行檔。請記得將命令範例中的 <path\to\vcpkg> 取代為您稍早克隆的 vcpkg 目錄的路徑。
```
export PATH=$PATH:/path/to/vcpkg
```
若要確認 vcpkg 目錄已新增至您的路徑，請周遊回您的專案目錄，然後執行下列命令：
```
vcpkg --version
```

您應該會取得下列輸出：

vcpkg package management program version <version>

安裝程式庫

本節將引導您使用 vcpkg 從 Azure SDK for C++ 安裝必要的程式庫。本節說明如何在指令清單模式中使用 vcpkg，以建立幾個 vcpkg 項目檔，以協助管理專案的相依性，即使與其他共同作業者共用也是如此。

Windows - PowerShell
MacOS/Linux - Bash

從專案的根目錄，執行下列命令，以指令清單模式啟動新的 vcpkg 專案：
```
vcpkg new --application
```
現在應該會有 vcpkg.json 檔案和項目目錄中 的vcpkg-configuration.json 檔案。
現在，我們可以執行下列命令，將 Azure SDK for C++ 的 Azure Key Vault 和身分識別連結庫新增至專案：
```
vcpkg add port azure-identity-cpp azure-security-keyvault-secrets-cpp
```

vcpkg.json 檔案現在應該有下列內容：

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

從專案的根目錄，執行下列命令，以指令清單模式啟動新的 vcpkg 專案：
```
vcpkg new --application
```
現在應該會有 vcpkg.json 檔案和項目目錄中 的vcpkg-configuration.json 檔案。
現在，我們可以執行下列命令，將 Azure SDK for C++ 的 Azure Key Vault 和身分識別連結庫新增至專案：
```
vcpkg add port azure-identity-cpp azure-security-keyvault-secrets-cpp
```

vcpkg.json 檔案現在應該有下列內容：

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

建立 Azure Key Vault 資源

本節討論如何使用 Azure CLI 來建立 Azure Key Vault 資源。此 Key Vault 資源可安全地儲存和管理機密資訊，例如秘密和密鑰。

Windows - PowerShell
MacOS/Linux - Bash

在終端機中輸入下列命令，使用 Azure CLI 登入：
```
az login
```
使用彈出視窗來登入 Azure。
使用快顯瀏覽器視窗登入之後，請選取您想要在終端機中使用的 Azure 訂用帳戶。
然後使用下列命令來建立 Key Vault 資源，並記得以您自己的唯一名稱取代 <your-resource-group-name> 和 <your-key-vault-name> ：
```
az keyvault create --resource-group <your-resource-group-name> --name <your-key-vault-name>
```
在輸出中，您應該會看到包含 vaultUri 屬性的一系列屬性清單。使用下列命令，將設定為要用於程式中的環境變數：
```
$env:AZURE_KEYVAULT_URL = "https://<your-key-vault-name>.vault.azure.net/"
```

在終端機中輸入下列命令，使用 Azure CLI 登入：
```
az login
```
使用彈出視窗來登入 Azure。
使用快顯瀏覽器視窗登入之後，請選取您想要在終端機中使用的 Azure 訂用帳戶。
然後使用下列命令來建立 Key Vault 資源，並記得以您自己的唯一名稱取代 <your-resource-group-name> 和 <your-key-vault-name> ：
```
az keyvault create --resource-group <your-resource-group-name> --name <your-key-vault-name>
```
在輸出中，您應該會看到包含 vaultUri 屬性的一系列屬性清單。使用下列命令，將設定為要用於程式中的環境變數：
```
export AZURE_KEYVAULT_URL="https://<your-key-vault-name>.vault.azure.net/"
```

最後，請確定您的 Azure 帳戶具有適當的許可權來處理 Key Vault 秘密。您可以在 Azure 入口網站的 Key Vault 資源訪問控制（IAM）頁面上指派「Key Vault 秘密人員」角色，以賦予自己適當的許可權。 IAM 代表身分識別和存取管理。

設定您的專案

本節說明建立必要的資料夾和檔案以設定 Azure C++ 專案。

在項目目錄的根目錄中，建立 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
)

在項目目錄的根目錄中，建立 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;
}

建置並執行

本節討論如何使用 CMake 命令來設定和建置專案，然後執行程式以確保一切都已正確設定。本節中的命令應該從目錄、 build和 CMakeLists.txt 檔案所在的專案main.cpp根目錄執行。

Windows - PowerShell
MacOS/Linux - Bash

若要設定 CMake，請輸入下列命令：
```
cmake -B ./build
```
若要建置專案，請輸入下列命令：
```
cmake --build ./build
```
若要執行程式，請輸入下列命令：
```
.\build\Debug\azure_sample.exe
```

程式應該有下列輸出：

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

若要設定 CMake，請輸入下列命令：
```
cmake -B ./build
```
若要建置專案，請輸入下列命令：
```
cmake --build ./build
```
若要執行程式，請輸入下列命令：
```
./build/azure_sample
```

程式應該有下列輸出：

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

故障排除

找不到資源群組

使用 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>

如需詳細資訊，請參閱管理 Azure 資源群組的 AzureCLI 檔。

CMake 設定或組建找不到 Azure 套件

執行 CMake 設定或建置命令時，如果您收到下列錯誤或類似的錯誤，檔案 CMakeLists.txt 就不會在 CMake 專案建立或完全之前執行 vcpkg.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 檔案可能會包含使用 \的路徑。使用 Window 的路徑時，這個問題很常見。

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 只使用/作為檔案路徑分隔符號。您可以透過在 \ 檔案中的路徑中，將所有/替換為，來解決此問題。

如果您在進行變更後錯誤仍然持續發生，請參閱變更後 CMake 錯誤持續發生一節，以瞭解如何解決這些問題。

進行變更之後，CMake 錯誤會持續發生

執行 CMake configure 命令時，如果您在進行變更以修正它之後繼續收到相同的錯誤，請嘗試清除 CMake 快取。刪除組建目錄的內容，然後重新執行 CMake configure 命令，即可清除 CMake 快取。

CMake 3.30 或更高版本

執行 CMake configure 命令時，如果您收到如下的錯誤，您可能需要更新 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 入口網站更新您的許可權，請流覽至 Key Vault 資源的 訪問控制（IAM） 頁面。選取 [ 新增 ] 下拉式列表，然後選取 [新增角色指派]。在 [ 角色] 頁面上，選取 Key Vault 秘密人員 角色，然後選取頁面底部的 [ 下一步 ]。在 [ 成員] 頁面上，將 [ 指派存取權] 選項保留在 [使用者]、[群組] 或服務主體上， 然後選取 [ 選取成員 ] 連結。在右側彈出視窗中，搜尋並選取您的ID，然後在彈出視窗底部選取選取。您選取的識別碼現在應該會顯示在 [ 成員 ] 區段的數據表中。選取底部的 [ 檢閱 + 指派] 按鈕。然後再次選取 [ 檢閱 + 指派] 按鈕。

若要使用 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 包含錯誤

如果您在使用 VS Code 時看到 include 語句底下的錯誤行（如下圖所示），編輯器並不知道在何處尋找 include 目錄。

{C++包含 VS Code 語句的螢幕快照，其下方有紅色錯誤波浪線。}

vcpkg 在指令清單模式中會將 include 標頭放在 build/vcpkg_installed/<vcpkg-platform-triplet>/include。 以您平台的 vcpkg triplet 取代 <vcpkg-platform-triplet> 。

若要將 include 目錄新增至 VS Code 設定，請將滑鼠指針移至 include 語句上方並突出顯示錯誤行。然後選取快顯底部的 [ 快速修正...] 連結。在 [快速修正] 選項中，選取 新增至 "includePath": ${workspaceFolder}/build/vcpkg_installed/<vcpkg-platform-triplet>/include 選項。 [C/C++ 延伸模組組態] 標籤應該會開啟，然後在 [包含路徑] 區段下面，您會看到列出的包含目錄路徑。

Linux bootstrap-vcpkg 找不到相依性

在Linux上執行 bootstrap-vcpkg.sh 文稿時，如果您收到如下的錯誤，則不需要安裝執行腳本所需的工具。

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 configure 命令時，如果您收到如下的錯誤， 則未正確設定 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 檔案中，使用安裝 vcpkg 的正確路徑來更新 set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake") 語句。

Linux vcpkg 安裝失敗

執行 CMake configure 命令時，如果您收到如下的錯誤，則必須安裝套件的系統相依性。

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 組態命令。視遺漏的系統套件數目而定，您可能需要重複此程式幾次。

後續步驟

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-05-08