Mulai cepat: Pustaka klien Azure Blob Storage untuk C++

Mulai menggunakan pustaka klien Azure Blob Storage untuk C++. Azure Blob Storage adalah solusi penyimpanan objek Microsoft untuk cloud. Ikuti langkah-langkah berikut untuk menginstal paket dan mencoba contoh kode untuk tugas dasar.

| Contoh kode | sumber pustaka dokumentasi | referensi API |

Prasyarat

• Langganan Azure - buat akun secara gratis
• Akun penyimpanan Azure - buat akun penyimpanan
• Pengompilasi C++
• CMake
• vcpkg - Manajer paket C dan C++

Menyiapkan

Bagian ini memancang Anda menyiapkan proyek untuk bekerja dengan pustaka klien Azure Blob Storage untuk C++. Cara term mudah untuk memperoleh Azure SDK untuk C++ adalah dengan menggunakan vcpkg manajer paket.

Menginstal paket

vcpkg install Gunakan perintah untuk menginstal pustaka Azure Blob Storage untuk C++ dan dependensi yang diperlukan:

vcpkg.exe install azure-storage-blobs-cpp

Pustaka Azure Identity diperlukan untuk koneksi tanpa kata sandi ke layanan Azure:

vcpkg.exe install azure-identity-cpp

Untuk informasi selengkapnya tentang penyiapan proyek dan bekerja dengan Azure SDK untuk C++, lihat readme Azure SDK untuk C++.

Membuat proyek

Di Visual Studio, buat aplikasi konsol C++ baru untuk Windows yang disebut BlobQuickstart.

Model objek

Azure Blob Storage dioptimalkan untuk menyimpan data tidak terstruktur dalam jumlah besar. Data tidak terstruktur adalah data yang tidak mematuhi model atau definisi data tertentu, seperti data teks atau biner. Blob Storage menawarkan tiga jenis sumber daya:

• Akun penyimpanan
• Kontainer di akun penyimpanan
• Blob di dalam kontainer

Diagram berikut menunjukkan hubungan antara ketiga sumber daya ini.

Gunakan kelas C++ berikut untuk berinteraksi dengan sumber daya ini:

• BlobServiceClient: Kelas BlobServiceClient memungkinkan Anda memanipulasi sumber daya Microsoft Azure Storage dan kontainer blob.
• BlobContainerClient: Kelas BlobContainerClient ini memungkinkan Anda memanipulasi kontainer Azure Storage dan blobnya.
• BlobClient: Kelas BlobClient ini memungkinkan Anda memanipulasi blob Azure Storage. Ini adalah kelas dasar untuk semua kelas blob khusus.
• BlockBlobClient: Kelas BlockBlobClient ini memungkinkan Anda memanipulasi blob blok Azure Storage.

Contoh kode

Contoh cuplikan kode ini menunjukkan cara melakukan tugas berikut dengan pustaka klien Azure Blob Storage untuk C++:

• Menambahkan file
• Mengautentikasi ke Azure dan mengotorisasi akses ke data blob
• Membuat kontainer
• Unggah blob ke kontainer
• Cantumkan blob di kontainer
• Unduh blob
• Menghapus kontainer

Menambahkan file

Dari direktori proyek:

1. Buka file solusi BlobQuickstart.sln di Visual Studio
2. Di dalam Visual Studio, buka file sumber BlobQuickstart.cpp
3. Hapus kode apa pun di dalam main yang telah dibuat secara otomatis
4. Tambahkan #include dan using namespace pernyataan

#include <iostream>
#include <azure/core.hpp>
#include <azure/identity/default_azure_credential.hpp>
#include <azure/storage/blobs.hpp>

using namespace Azure::Identity;
using namespace Azure::Storage::Blobs;

Mengautentikasi ke Azure dan mengotorisasi akses ke data blob

Permintaan aplikasi ke Azure Blob Storage harus diotorisasi. Menggunakan kelas yang DefaultAzureCredential disediakan oleh pustaka klien Azure Identity adalah pendekatan yang direkomendasikan untuk menerapkan koneksi tanpa kata sandi ke layanan Azure dalam kode Anda, termasuk Blob Storage.

Anda juga dapat mengotorisasi permintaan untuk Azure Blob Storage menggunakan kunci akses akun. Namun, pendekatan ini harus digunakan dengan hati-hati. Pengembang harus rajin untuk tidak pernah mengekspos kunci akses di lokasi yang tidak aman. Siapa pun yang memiliki kunci akses dapat mengotorisasi permintaan terhadap akun penyimpanan, dan secara efektif memiliki akses ke semua data. DefaultAzureCredential menawarkan keuntungan pengelolaan dan keamanan yang ditingkatkan melalui kunci akun untuk memungkinkan autentikasi tanpa kata sandi. Kedua opsi diperlihatkan dalam contoh berikut.

Tanpa Kata Sandi (Disarankan)

Pustaka Azure Identity menyediakan dukungan autentikasi token Microsoft Entra di seluruh Azure SDK. Ini menyediakan serangkaian TokenCredential implementasi yang dapat digunakan untuk membangun klien Azure SDK yang mendukung autentikasi token Microsoft Entra. DefaultAzureCredential mendukung beberapa metode autentikasi dan menentukan metode autentikasi yang harus digunakan saat runtime bahasa umum.

Menetapkan peran ke akun pengguna Microsoft Entra Anda

Saat mengembangkan secara lokal, pastikan bahwa akun pengguna yang mengakses data blob memiliki izin yang benar. Anda akan memerlukan Kontributor Data Blob Penyimpanan untuk membaca dan menulis data blob. Untuk menetapkan sendiri peran ini, Anda harus diberi peran Administrator Akses Pengguna, atau peran lain yang menyertakan tindakan Microsoft.Authorization/roleAssignments/write . Anda dapat menetapkan peran Azure RBAC kepada pengguna menggunakan portal Azure, Azure CLI, atau Azure PowerShell. Anda dapat mempelajari selengkapnya tentang cakupan yang tersedia untuk penetapan peran di halaman gambaran umum cakupan.

Dalam skenario ini, Anda akan menetapkan izin ke akun pengguna, yang tercakup ke akun penyimpanan, untuk mengikuti Prinsip Hak Istimewa Paling Rendah. Praktik ini hanya memberi pengguna izin minimum yang diperlukan dan menciptakan lingkungan produksi yang lebih aman.

Contoh berikut akan menetapkan peran Kontributor Data Blob Penyimpanan ke akun pengguna Anda, yang menyediakan akses baca dan tulis ke data blob di akun penyimpanan Anda.

Penting

Dalam kebanyakan kasus, dibutuhkan satu atau dua menit agar penetapan peran disebarluaskan di Azure, tetapi dalam kasus yang jarang terjadi mungkin perlu waktu hingga delapan menit. Jika Anda menerima kesalahan autentikasi saat pertama kali menjalankan kode, tunggu beberapa saat dan coba lagi.

Portal Azure

1. Di portal Azure, temukan akun penyimpanan Anda menggunakan bilah pencarian utama atau navigasi kiri.

2. Di halaman gambaran umum akun penyimpanan, pilih Kontrol akses (IAM) dari menu kiri.

3. Di halaman Kontrol akses (IAM), pilih tab Penetapan peran.

4. Pilih + Tambahkan dari menu atas lalu Tambahkan penetapan peran dari menu drop-down yang dihasilkan.

   

5. Gunakan kotak pencarian untuk memfilter hasil ke peran yang diinginkan. Untuk contoh ini, cari Kontributor Data Blob Penyimpanan dan pilih hasil yang cocok, lalu pilih Berikutnya.

6. Di bagian Tetapkan akses ke, pilih Pengguna, grup, atau perwakilan layanan, lalu pilih + Pilih anggota.

7. Dalam dialog, cari nama pengguna Microsoft Entra Anda (biasanya alamat email user@domain Anda) lalu pilih Pilih di bagian bawah dialog.

8. Pilih Tinjau + tetapkan untuk masuk ke halaman akhir, lalu Tinjau + tetapkan lagi untuk menyelesaikan proses.

Azure CLI

Untuk menetapkan peran di tingkat sumber daya menggunakan Azure CLI, Anda harus terlebih dahulu mengambil id sumber daya menggunakan perintah az storage account show. Anda dapat memfilter properti output menggunakan parameter --query.

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

Salin output Id dari perintah sebelumnya. Anda kemudian dapat menetapkan peran menggunakan perintah az role di Azure CLI.

az role assignment create --assignee "<user@domain>" \
    --role "Storage Blob Data Contributor" \
    --scope "<your-resource-id>"

PowerShell

Untuk menetapkan peran di tingkat sumber daya menggunakan Azure PowerShell, Anda harus terlebih dahulu mengambil ID sumber daya menggunakan Get-AzResource perintah .

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

Salin nilai Id dari output perintah sebelumnya. Anda kemudian dapat menetapkan peran menggunakan perintah New-AzRoleAssignment di PowerShell.

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Blob Data Contributor" `
    -Scope <yourStorageAccountId>

Masuk dan sambungkan kode aplikasi Anda ke Azure menggunakan DefaultAzureCredential

Anda dapat mengotorisasi akses ke data di akun penyimpanan Anda menggunakan langkah-langkah berikut:

1. Pastikan Anda diautentikasi dengan akun Microsoft Entra yang sama dengan yang Anda tetapkan perannya di akun penyimpanan Anda. Anda dapat mengautentikasi melalui Azure CLI. Masuk ke Azure melalui Azure CLI menggunakan perintah berikut:

   az login
   

2. Untuk menggunakan DefaultAzureCredential, pastikan bahwa paket azure-identity-cpp diinstal dan berikut ini #include ditambahkan:

   #include <azure/identity/default_azure_credential.hpp>
   

3. Tambahkan kode ini ke akhir main(). Saat kode berjalan di stasiun kerja lokal Anda, DefaultAzureCredential menggunakan kredensial pengembang untuk Azure CLI untuk mengautentikasi ke Azure.

   // Initialize an instance of DefaultAzureCredential
    auto defaultAzureCredential = std::make_shared<DefaultAzureCredential>();
   
    auto accountURL = "https://<storage-account-name>.blob.core.windows.net";
    BlobServiceClient blobServiceClient(accountURL, defaultAzureCredential);
   

4. Pastikan untuk memperbarui nama akun penyimpanan di URI objek Anda BlobServiceClient . Nama akun penyimpanan dapat ditemukan di halaman gambaran umum portal Azure.

   

   Catatan

   Saat menggunakan C++ SDK di lingkungan produksi, disarankan agar Anda hanya mengaktifkan kredensial yang Anda tahu yang akan digunakan aplikasi Anda. Alih-alih menggunakan DefaultAzureCredential, Anda harus mengotorisasi menggunakan jenis kredensial tertentu, atau dengan menggunakan ChainedTokenCredential kredensial yang didukung.

String Koneksi

String koneksi menyertakan kunci akses akun penyimpanan dan menggunakannya untuk mengotorisasi permintaan. Selalu berhati-hatilah untuk tidak mengekspos kunci di lokasi yang tidak aman.

Catatan

Untuk mengotorisasi akses data dengan kunci akses akun penyimpanan, Anda memerlukan izin untuk tindakan Azure RBAC berikut: Microsoft.Storage/storageAccounts/listkeys/action. Peran bawaan yang paling tidak istimewa dengan izin untuk tindakan ini adalah Pembaca dan Akses Data, tetapi peran apa pun yang menyertakan tindakan ini akan berfungsi.

Portal Azure

1. Masuk ke portal Azure.

2. Temukan akun penyimpanan Anda.

3. Di panel menu akun penyimpanan, di Keamanan + jaringan, pilih Kunci akses. Di sini, Anda dapat melihat kunci akses akun dan string koneksi lengkap untuk setiap kunci.

4. Di panel Kunci akses, pilih Tampilkan kunci.

5. Di bagian kunci1, cari nilai String koneksi. Pilih ikon Salin ke clipboard untuk menyalin string koneksi. Anda akan menambah nilai string koneksi ke variabel lingkungan di bagian berikutnya.

   

Azure CLI

Anda dapat melihat string koneksi untuk akun penyimpanan Anda menggunakan perintah az storage account show-connection-string.

az storage account show-connection-string --name "<your-storage-account-name>"

PowerShell

Anda dapat menyusun string koneksi dengan PowerShell menggunakan perintah Get-AzStorageAccount dan Get-AzStorageAccountKey.

$saName = "yourStorageAccountName"
$rgName = "yourResourceGroupName"
$sa = Get-AzStorageAccount -StorageAccountName $saName -ResourceGroupName $rgName

$saKey = (Get-AzStorageAccountKey -ResourceGroupName $rgName -Name $saName)[0].Value

'DefaultEndpointsProtocol=https;AccountName=' + $saName + ';AccountKey=' + $saKey + ';EndpointSuffix=core.windows.net'

Mengonfigurasi string koneksi penyimpanan Anda

Setelah menyalin string koneksi Anda, tuliskan ke variabel lingkungan baru di komputer lokal yang menjalankan aplikasi. Untuk mengatur variabel lingkungan, buka jendela konsol, dan ikuti petunjuk untuk sistem operasi Anda. Ganti <yourconnectionstring> dengan string koneksi aktual Anda.

Windows:

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

Setelah menambahkan variabel lingkungan di Windows, Anda harus memulai instans baru dari jendela perintah.

Linux:

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

Contoh kode berikut mengambil string koneksi untuk akun penyimpanan dari variabel lingkungan yang dibuat sebelumnya, dan menggunakan string koneksi untuk membuat objek klien layanan.

Tambahkan kode ini ke akhir main():

    // Retrieve the connection string for use with the application. The storage
    // connection string is stored in an environment variable on the machine
    // running the application called AZURE_STORAGE_CONNECTION_STRING.
    // Note that _MSC_VER is set when using MSVC compiler.
    static const char* AZURE_STORAGE_CONNECTION_STRING = "AZURE_STORAGE_CONNECTION_STRING";

#if !defined(_MSC_VER)
    const char* connectionString = std::getenv(AZURE_STORAGE_CONNECTION_STRING);
#else
	// Use getenv_s for MSVC
	size_t requiredSize;
	getenv_s(&requiredSize, NULL, NULL, AZURE_STORAGE_CONNECTION_STRING);
	if (requiredSize == 0) {
		throw std::runtime_error("missing connection string from env.");
	}
	std::vector<char> value(requiredSize);
	getenv_s(&requiredSize, value.data(), value.size(), AZURE_STORAGE_CONNECTION_STRING);
	std::string connectionStringStr = std::string(value.begin(), value.end());
	const char* connectionString = connectionStringStr.c_str();
#endif

	auto blobServiceClient = BlobServiceClient::CreateFromConnectionString(connectionString);

Penting

Kunci akses akun harus digunakan dengan hati-hati. Jika kunci akses akun Anda hilang atau tidak sengaja ditempatkan di lokasi yang tidak aman, layanan Anda mungkin menjadi rentan. Siapa pun yang memiliki kunci akses dapat mengotorisasi permintaan terhadap akun penyimpanan, dan secara efektif memiliki akses ke semua data. DefaultAzureCredential memberikan fitur dan manfaat keamanan yang ditingkatkan dan merupakan pendekatan yang direkomendasikan untuk mengelola otorisasi ke layanan Azure.

Membuat kontainer

Tentukan nama untuk kontainer baru. Kemudian buat instans BlobContainerClient dan buat kontainer.

Penting

Nama kontainer harus menggunakan huruf kecil. Untuk informasi selengkapnya tentang penamaan kontainer dan blob, lihat Menamai dan Mereferensikan Kontainer, Blob, dan Metadata.

Tambahkan kode ini ke akhir main():

std::string containerName = "myblobcontainer";
auto containerClient = blobServiceClient.GetBlobContainerClient("myblobcontainer");

// Create the container if it does not exist
std::cout << "Creating container: " << containerName << std::endl;
containerClient.CreateIfNotExists();

Unggah blob ke kontainer

Cuplikan kode berikut:

1. Mendeklarasikan string yang berisi "Halo Azure!"
2. Mendapatkan referensi ke objek BlockBlobClient dengan memanggil GetBlockBlobClient pada kontainer dari bagian Buat kontainer.
3. Unggah string ke blob dengan memanggil fungsi ​UploadFrom. Fungsi ini membuat blob jika belum ada, atau memperbaruinya jika sudah ada.

Tambahkan kode ini ke akhir main():

std::string blobName = "blob.txt";
uint8_t blobContent[] = "Hello Azure!";
// Create the block blob client
BlockBlobClient blobClient = containerClient.GetBlockBlobClient(blobName);

// Upload the blob
std::cout << "Uploading blob: " << blobName << std::endl;
blobClient.UploadFrom(blobContent, sizeof(blobContent));

Cantumkan blob di kontainer

Buat daftar blob dalam kontainer dengan memanggil metode ListBlobs. Hanya satu blob yang telah ditambahkan ke kontainer, sehingga operasi mengembalikan blob itu saja.

Tambahkan kode ini ke akhir main():

std::cout << "Listing blobs..." << std::endl;
auto listBlobsResponse = containerClient.ListBlobs();
for (auto blobItem : listBlobsResponse.Blobs)
{
    std::cout << "Blob name: " << blobItem.Name << std::endl;
}

Unduh blob

Dapatkan properti blob yang diunggah. Kemudian, nyatakan dan ubah ukuran objek std::vector<uint8_t> baru dengan menggunakan properti blob yang diunggah. Unduh blob yang dibuat sebelumnya ke objek std::vector<uint8_t> baru dengan memanggil fungsi DownloadTo di kelas dasar BlobClient. Terakhir, tampilkan data blob yang diunduh.

Tambahkan kode ini ke akhir main():

auto properties = blobClient.GetProperties().Value;
std::vector<uint8_t> downloadedBlob(properties.BlobSize);

blobClient.DownloadTo(downloadedBlob.data(), downloadedBlob.size());
std::cout << "Downloaded blob contents: " << std::string(downloadedBlob.begin(), downloadedBlob.end()) << std::endl;

Menghapus blob

Kode berikut menghapus blob dari kontainer Azure Blob Storage dengan memanggil fungsi BlobClient.Delete.

std::cout << "Deleting blob: " << blobName << std::endl;
blobClient.Delete();

Menghapus kontainer

Kode berikut membersihkan sumber daya yang dibuat aplikasi dengan menghapus seluruh kontainer menggunakan BlobContainerClient.Delete.

Tambahkan kode ini ke akhir main():

std::cout << "Deleting container: " << containerName << std::endl;
containerClient.Delete();

Menjalankan kode

Aplikasi ini membuat kontainer dan mengunggah file teks ke Azure Blob Storage. Contoh ini kemudian mencantumkan blob dalam kontainer, mengunduh file, dan menampilkan isi file. Akhirnya, aplikasi menghapus blob dan kontainer.

Output aplikasi mirip dengan contoh berikut:

Azure Blob Storage - C++ quickstart sample
Creating container: myblobcontainer
Uploading blob: blob.txt
Listing blobs...
Blob name: blob.txt
Downloaded blob contents: Hello Azure!
Deleting blob: blob.txt
Deleting container: myblobcontainer

Langkah berikutnya

Di mulai cepat ini, Anda belajar cara mengunggah, mengunduh, dan mencantumkan blob menggunakan C++. Anda juga telah mempelajari cara membuat dan menghapus kontainer Azure Blob Storage.

Untuk melihat sampel Blob Storage C++, lanjutkan ke:

Pustaka klien Azure Blob Storage untuk sampel C++