C++용 Azure SDK에서 라이브러리 설치 및 통합

이 가이드에서는 vcpkg를 사용하여 C++용 Azure SDK에서 라이브러리를 설치하고 CMake를 사용하여 프로젝트에 통합하는 데 필요한 단계를 개발자에게 제공합니다. 지침에 따라 개발 환경을 설정하고 C++ 애플리케이션에서 Azure 서비스 사용을 시작할 수 있습니다. Azure를 익숙하지 않거나 통합 프로세스를 간소화하려는 경우 이 설명서를 통해 빠르고 효율적으로 시작할 수 있습니다.

필수 조건

• 모든 텍스트 편집기
• 터미널
• C++ 컴파일러
• git
• CMake
• Azure 구독
• Azure CLI

git 및 CMake 설치 확인

원활한 통합 프로세스를 보장하려면 git 및 CMake가 시스템에 올바르게 설치되어 있는지 확인하는 것이 중요합니다.

vcpkg 설치

C++ 라이브러리용 Azure SDK를 관리하고 설치하려면 vcpkg를 사용합니다. vcpkg 는 종속성 처리 프로세스를 간소화하는 플랫폼 간 패키지 관리자입니다.

라이브러리 설치

이 섹션에서는 vcpkg를 사용하여 C++용 Azure SDK에서 필요한 라이브러리를 설치하는 프로세스를 안내합니다. 이 섹션에서는 매니페스트 모드에서 vcpkg를 사용하여 다른 공동 작업자와 공유하는 경우에도 프로젝트의 종속성을 관리하는 데 도움이 되는 몇 개의 vcpkg 프로젝트 파일을 만드는 방법을 보여 줍니다.

Azure Key Vault 리소스 만들기

이 섹션에서는 Azure CLI를 사용하여 Azure Key Vault 리소스를 만드는 방법을 설명합니다. 이 Key Vault 리소스는 비밀 및 키와 같은 중요한 정보를 안전하게 저장하고 관리합니다.

1. 마지막으로, Azure 계정에 Key Vault 비밀로 작업할 수 있는 적절한 권한이 있는지 확인합니다. Azure Portal에서 Key Vault 리소스의 IAM(액세스 제어) 페이지에서 "Key Vault 비밀 책임자" 역할을 자신에게 할당하여 적절한 권한을 부여할 수 있습니다. IAM은 ID 및 액세스 관리를 의미합니다.

프로젝트 설정

이 섹션에서는 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 명령을 사용하여 프로젝트를 구성하고 빌드한 다음 프로그램을 실행하여 모든 것이 올바르게 설정되었는지 확인하는 방법을 설명합니다. 이 섹션의 명령은 디렉터리와 buildCMakeLists.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>

자세한 내용은 Azure 리소스 그룹 관리에 대한 AzureCLI 문서를 확인하세요.

CMake 구성 또는 빌드에서 Azure 패키지를 찾을 수 없음

CMake 구성 또는 빌드 명령을 실행할 때 다음 오류 또는 이와 유사한 CMakeLists.txt 오류가 표시되면 CMake 프로젝트가 설립되기 전에 CMakeLists.txt 파일이 모듈을 실행하지 않는 것입니다.

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 코드의 구문 오류

ko-KR: CMake 구성 또는 빌드 명령을 실행할 때 다음 오류가 표시되면 CMakeLists.txt 파일에 \를 사용하는 경로가 포함되어 있을 수 있습니다. 이 문제는 창의 경로를 사용할 때 일반적일 수 있습니다.

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 구성 명령을 다시 실행하여 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 Portal 또는 Azure CLI를 사용하여 계정에 적절한 권한을 부여할 수 있습니다.

Azure Portal을 사용하여 권한을 업데이트하려면 Key Vault 리소스의 IAM(액세스 제어) 페이지로 이동합니다. 추가 드롭다운을 선택하고 역할 할당 추가를 선택합니다. 역할 페이지에서 Key Vault 비밀 책임자 역할을 선택하고 페이지 아래쪽에서 다음을 선택합니다. 구성원 페이지에서 사용자, 그룹 또는 서비스 주체에 대한 액세스 할당 옵션을 그대로 두고 구성원 선택 링크를 선택합니다. 오른쪽 팝업에서 ID를 검색하여 선택한 다음 팝업 아래쪽에서 선택을 선택합니다. 선택한 ID가 이제 멤버 섹션의 테이블에 표시됩니다. 아래쪽에서 검토 + 할당 단추를 선택합니다. 그런 다음 검토 + 할당 단추를 다시 선택합니다.

Azure CLI를 사용하여 사용 권한을 업데이트하려면 다음 명령을 입력하여 사용자 계정 이름, <upn> 구독 ID, <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 문 아래에 오류 줄이 표시되는 경우(다음 이미지에 표시됨) 편집기에서 포함 디렉터리를 찾을 위치를 알 수 없습니다.

vcpkg는 매니페스트 모드일 때 헤더 파일을 build/vcpkg_installed/<vcpkg-platform-triplet>/include에 배치합니다. 플랫폼에 맞는 vcpkg 트리플렛으로 <vcpkg-platform-triplet>를 교체하세요.

VS Code 설정에 include 디렉터리를 추가하려면 오류 줄이 있는 include 문 위로 마우스를 가져다 줍니다. 그런 다음 팝업 맨 아래에 있는 빠른 수정... 링크를 선택합니다. 빠른 수정 옵션에서 추가 "includePath": ${workspaceFolder}/build/vcpkg_installed/<vcpkg-platform-triplet>/include 옵션을 선택합니다. C/C++ 확장 구성 탭이 열리고 "포함 경로" 섹션 아래에 나열된 포함 디렉터리의 경로가 표시됩니다.

Linux 부트스트랩-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 구성 명령을 실행할 때 다음과 같은 오류가 발생하면 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 구성 명령을 실행할 때 다음과 같은 오류가 발생하면 패키지에 대한 시스템 종속성을 설치해야 합니다.

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

필요한 시스템 패키지를 찾으려면 누락된 시스템 패키지로 Could not find <system-package>를 바꾸고 <system-package>으로 시작하는 줄을 CMake 구성 명령의 출력에서 검색합니다. 이 줄 아래에는 누락된 시스템 패키지를 설치하는 명령이 있어야 합니다. 해당 명령을 실행합니다. 그런 다음, CMake 구성 명령을 다시 실행합니다. 누락된 시스템 패키지 수에 따라 이 프로세스를 몇 번 반복해야 할 수 있습니다.

다음 단계