Bagikan melalui

Menginstal dan mengintegrasikan pustaka dari Azure SDK untuk C++

Panduan ini memberi pengembang langkah-langkah yang diperlukan untuk menginstal pustaka dari Azure SDK untuk C++ menggunakan vcpkg dan mengintegrasikannya ke dalam proyek mereka dengan CMake. Dengan mengikuti instruksi, Anda dapat menyiapkan lingkungan pengembangan dan mulai menggunakan layanan Azure di aplikasi C++ Anda. Baik Anda baru menggunakan Azure atau ingin menyederhanakan proses integrasi Anda, dokumentasi ini membantu Anda memulai dengan cepat dan efisien.

Prasyarat

Memverifikasi penginstalan git dan CMake

Untuk memastikan proses integrasi yang lancar, penting untuk memverifikasi bahwa git, dan CMake diinstal dengan benar pada sistem Anda.

  1. Untuk memverifikasi bahwa git diinstal dengan benar, jalankan perintah berikut di terminal Anda:

    git --version

  2. Anda harus mendapatkan output yang menunjukkan versi yang saat ini diinstal untuk git, seperti ini:

    git version <version>

  3. Untuk memverifikasi bahwa CMake diinstal dengan benar, jalankan perintah berikut di terminal Anda:

    cmake --version

  4. Anda harus mendapatkan output yang menunjukkan versi CMake yang saat ini diinstal, seperti ini:

    cmake version <version>

Menginstal vcpkg

Untuk mengelola dan menginstal Azure SDK untuk pustaka C++, gunakan vcpkg. vcpkg adalah manajer paket lintas platform yang menyederhanakan proses penanganan dependensi.

  1. Untuk menginstal vcpkg, pertama-tama kloning repositori vcpkg. Pendekatan yang disarankan adalah mengkloning vcpkg ke lokasi pusat di lingkungan pengembangan Anda dan bukan di direktori proyek C++Anda. Dalam contoh ini, vcpkg diklon ke direktori rumah.

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

  2. Setelah repositori vcpkg dikloning, arahkan ke direktori baru dan jalankan bootstrap-vcpkg.bat skrip.

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

  3. Setelah mengonfigurasi awal vcpkg, tambahkan ke path sistem Anda sehingga Anda dapat mengakses file eksekusi vcpkg dari direktori proyek Anda. Ingatlah untuk mengganti <path\to\vcpkg> dalam contoh perintah dengan jalur ke direktori vcpkg yang Anda kloning sebelumnya.

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

  4. Untuk memverifikasi bahwa direktori vcpkg ditambahkan ke jalur Anda, kembali ke direktori proyek Anda dan jalankan perintah berikut:

    vcpkg --version

  5. Anda harus mendapatkan output berikut:

    vcpkg package management program version <version>

Instal pustaka

Bagian ini memandu Anda melalui proses penginstalan pustaka yang diperlukan dari Azure SDK untuk C++ menggunakan vcpkg. Bagian ini menunjukkan cara menggunakan vcpkg dalam mode manifes yang membuat beberapa file proyek vcpkg untuk membantu mengelola dependensi proyek bahkan ketika dibagikan dengan kolaborator lain.

  1. Dari direktori akar proyek Anda, jalankan perintah berikut untuk memulai proyek vcpkg baru dalam mode manifes:

    vcpkg new --application

  2. Sekarang harus ada file vcpkg.json dan file vcpkg-configuration.json di direktori proyek Anda.

  3. Sekarang kita dapat menambahkan pustaka Azure Key Vault dan Identity dari Azure SDK untuk C++ ke proyek kita dengan menjalankan perintah berikut:

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

  4. File vcpkg.json sekarang harus memiliki konten berikut:

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

Membuat sumber daya Azure Key Vault

Bagian ini membahas cara menggunakan Azure CLI untuk membuat sumber daya Azure Key Vault. Sumber daya Key Vault ini menyimpan dan mengelola informasi sensitif dengan aman, seperti rahasia dan kunci.

  1. Gunakan Azure CLI untuk masuk dengan memasukkan perintah berikut di terminal Anda:

    az login

  2. Gunakan jendela pop-up untuk masuk ke Azure.

  3. Setelah menggunakan jendela browser pop-up untuk masuk, pilih langganan Azure yang ingin Anda gunakan di terminal.

  4. Kemudian gunakan perintah berikut untuk membuat sumber daya Key Vault Anda, dan ingatlah untuk mengganti <your-resource-group-name> dan <your-key-vault-name> dengan nama unik Anda sendiri:

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

  5. Dalam output, Anda akan melihat daftar properti yang memiliki properti vaultUri. Atur ke variabel lingkungan yang akan digunakan dalam program kami dengan perintah berikut:

    $env:AZURE_KEYVAULT_URL = "https://<your-key-vault-name>.vault.azure.net/"
  1. Terakhir, pastikan akun Azure Anda memiliki izin yang tepat untuk bekerja dengan Rahasia Key Vault. Anda dapat memberi diri Anda izin yang tepat dengan menetapkan peran "Petugas Rahasia Key Vault" pada halaman Kontrol Akses (IAM) sumber daya Key Vault Anda di portal Microsoft Azure. IAM adalah singkatan dari manajemen identitas dan akses.

Menyiapkan proyek Anda

Bagian ini menjelaskan proses pembuatan folder dan file yang diperlukan untuk menyiapkan proyek Azure C++Anda.

  1. Di akar direktori proyek Anda, buat file CMakeLists.txt . File ini digunakan untuk mengonfigurasi proyek CMake kami. Tambahkan kode berikut ke file 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. Di akar direktori proyek Anda, buat file main.cpp . Tambahkan kode berikut ke file 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. Buat direktori untuk penyimpanan hasil build.

Membangun dan menjalankan

Bagian ini membahas cara mengonfigurasi dan membangun proyek Anda menggunakan perintah CMake, lalu menjalankan program untuk memastikan semuanya disiapkan dengan benar. Perintah di bagian ini harus dijalankan dari akar proyek Anda tempat build direktori, CMakeLists.txt, dan main.cpp file berada.

  1. Untuk mengonfigurasi CMake, masukkan perintah berikut:

    cmake -B ./build

  2. Untuk membangun proyek, masukkan perintah berikut:

    cmake --build ./build

  3. Untuk menjalankan program, masukkan perintah berikut:

    .\build\Debug\azure_sample.exe

  4. Program harus memiliki output berikut:

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

Penyelesaian Masalah

Grup sumber daya tidak ditemukan

Saat menggunakan AzureCLI untuk membuat instans Key Vault, jika Anda menerima kesalahan berikut, grup sumber daya yang Anda coba tambahkan instans Key Vault tidak ada.

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

Untuk membuat grup sumber daya, Anda bisa menggunakan perintah berikut:

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

Untuk informasi selengkapnya, lihat dokumen AzureCLI tentang Mengelola Grup Sumber Daya Azure.

Proses konfigurasi atau build CMake tidak dapat menemukan paket Azure

Saat menjalankan perintah konfigurasi atau build CMake, jika Anda menerima kesalahan berikut atau sesuatu yang serupa, berarti CMakeLists.txt file tidak menjalankan modul vcpkg.cmake sebelum proyek CMake dibuat atau tidak sama sekali.

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.

Verifikasi dalam file CMakeLists.txt , bahwa set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg-root/scripts/buildsystems/vcpkg.cmake") baris berada di atas project(azure_sample VERSION 0.1.0 LANGUAGES C CXX).

Kemudian juga verifikasi bahwa /path/to/vcpkg-root/ dalam baris set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg-root/scripts/buildsystems/vcpkg.cmake") telah diperbarui ke lokasi tempat vcpkg diinstal.

Kesalahan sintaks dalam kode cmake

Saat menjalankan konfigurasi CMake atau perintah build, jika Anda menerima kesalahan berikut, file CMakeLists.txt mungkin berisi jalur menggunakan \. Masalah ini sering kali terjadi saat menggunakan jalur 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'.

Meskipun Windows menggunakan \ di jalur file, CMake hanya menggunakan / di jalur file. Masalah ini dapat diatasi dengan mengganti semua \ dengan / jalur yang digunakan dalam file CMakeLists.txt .

Jika kesalahan Anda berlanjut setelah melakukan perubahan, lihat bagian kesalahan CMake terus berlanjut setelah membuat perubahan untuk mempelajari cara mengatasinya.

Kesalahan CMake berlanjut setelah membuat perubahan

Saat menjalankan perintah konfigurasi CMake, jika Anda terus menerima kesalahan yang sama setelah membuat perubahan untuk memperbaikinya, coba hapus cache CMake. Cache CMake dapat dibersihkan dengan menghapus konten direktori build lalu menjalankan ulang perintah konfigurasi CMake.

CMake 3.30 atau lebih tinggi diperlukan

Saat menjalankan perintah konfigurasi CMake, jika Anda menerima kesalahan seperti berikut ini, Anda mungkin perlu memperbarui versi CMake Anda.

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

Untuk mengatasi kesalahan ini, perbarui penginstalan CMake Anda ke versi yang dinyatakan dalam pesan kesalahan.

Pemanggil tidak berwenang untuk melakukan tindakan pada sumber daya

Saat menjalankan program sampel C++, jika Anda menerima kesalahan seperti berikut ini, Anda tidak memiliki izin yang tepat untuk bekerja dengan rahasia pada sumber daya Key Vault yang ditentukan.

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>

Izin yang tepat dapat diberikan ke akun Anda baik menggunakan portal Microsoft Azure atau Azure CLI.

Untuk memperbarui izin Anda menggunakan portal Microsoft Azure, navigasikan ke halaman Kontrol Akses (IAM) sumber daya Key Vault Anda. Pilih menu dropdown Tambahkan dan pilih Tambahkan penetapan peran. Pada halaman Peran , pilih peran Petugas Rahasia Key Vault dan pilih Berikutnya di bagian bawah halaman. Pada halaman Anggota, biarkan opsi Tetapkan akses ke tetap pada Pengguna, grup, atau peran layanan, lalu pilih tautan Pilih anggota. Di pop-up di sebelah kanan, cari dan pilih ID Anda, lalu pilih Pilih di bagian bawah pop-up. ID yang Anda pilih sekarang akan ditampilkan dalam tabel bagian Anggota . Pilih tombol Tinjau + tetapkan di bagian bawah. Kemudian pilih tombol Tinjau + berikan tugas lagi.

Untuk memperbarui izin Anda menggunakan Azure CLI, masukkan perintah berikut, ganti <upn> dengan nama prinsipal pengguna Anda, <subscription-id> dengan ID langganan Anda, <resource-group-name> dengan nama grup sumber daya Anda, dan <your-unique-keyvault-name> dengan nama instans Key Vault Anda:

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>"

Visual Studio Code mengandung kesalahan

Jika Anda melihat baris kesalahan di bawah pernyataan sertakan saat menggunakan Visual Studio Code (diperlihatkan dalam gambar berikut), editor tidak tahu di mana menemukan direktori sertakan.

{Cuplikan layar C++ menyertakan pernyataan dari Visual Studio Code yang memiliki garis berlekuk kesalahan merah di bawahnya.}

vcpkg menempatkan header include ke dalam build/vcpkg_installed/<vcpkg-platform-triplet>/include ketika berada dalam mode manifes. Gantilah <vcpkg-platform-triplet> dengan triplet vcpkg untuk platform Anda.

Untuk menambahkan direktori sertakan ke pengaturan Visual Studio Code Anda, arahkan mouse ke atas pernyataan sertakan dengan baris kesalahan. Lalu pilih tautan Perbaikan Cepat... di bagian bawah pop-up. Di opsi Perbaikan Cepat, pilih opsi Tambahkan ke "includePath": ${workspaceFolder}/build/vcpkg_installed/<vcpkg-platform-triplet>/include . Tab Konfigurasi Ekstensi C/C++ seharusnya terbuka dan di bagian "Jalur sertakan", Anda dapat melihat jalur ke direktori include yang tercantum.

Linux bootstrap-vcpkg tidak dapat menemukan dependensi

Saat menjalankan skrip bootstrap-vcpkg.sh di Linux, jika Anda menerima kesalahan seperti berikut ini, Anda tidak memiliki alat yang diperlukan yang diinstal untuk menjalankan skrip.

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)

Untuk menginstal alat, gunakan perintah yang disediakan dalam pesan kesalahan untuk distribusi linux Anda. Misalnya, pada Ubuntu akan menjadi perintah berikut:

sudo apt-get install curl zip unzip tar

Kemudian jalankan bootstrap-vcpkg.sh ulang skrip.

Linux tidak dapat menemukan file toolchain

Saat menjalankan perintah konfigurasi CMake, jika Anda menerima kesalahan seperti berikut ini, jalur ke modul vcpkg.cmake tidak diatur dengan benar.

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)

Dalam file CMakeLists.txt perbarui set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake") pernyataan dengan jalur yang benar ke tempat vcpkg diinstal.

Penginstalan Linux vcpkg gagal

Saat menjalankan perintah konfigurasi CMake, jika Anda menerima kesalahan seperti berikut ini, dependensi sistem untuk paket perlu diinstal.

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

Untuk menemukan paket sistem yang diperlukan, cari output perintah konfigurasi CMake untuk baris yang dimulai dengan Could not find <system-package>, mengganti <system-package> dengan paket sistem yang hilang. Di bawah baris ini harus menjadi perintah untuk menginstal paket sistem yang hilang. Jalankan perintah itu. Kemudian jalankan ulang perintah konfigurasi CMake. Anda mungkin perlu mengulangi proses ini beberapa kali tergantung pada jumlah paket sistem yang hilang.

Langkah selanjutnya

  • Last updated on