Hızlı Başlangıç: C++ için Azure Blob Depolama istemci kitaplığı

C++ için Azure Blob Depolama istemci kitaplığını kullanmaya başlayın. Azure Blob Depolama, Microsoft'un bulut için nesne depolama çözümüdür. Paketi yüklemek için bu adımları izleyin ve temel görevler için örnek kodu deneyin.

| API başvuru belgeleri | Kitaplık kaynak kodu | Örnekleri |

Önkoşullar

• Azure aboneliği - ücretsiz bir abonelik oluşturun
• Azure depolama hesabı - depolama hesabı oluşturma
• C++ derleyicisi
• CMake
• vcpkg - C ve C++ paket yöneticisi

Kurulum

Bu bölümde, C++ için Azure Blob Depolama istemci kitaplığıyla çalışmak üzere bir proje hazırlama işleminde size yol gösterilir. C++ için Azure SDK'sını edinmenin en kolay yolu paket yöneticisini vcpkg kullanmaktır.

Paketleri yükleme

vcpkg install C++ için Azure Blob Depolama kitaplığını ve gerekli bağımlılıkları yüklemek için komutunu kullanın:

vcpkg.exe install azure-storage-blobs-cpp

Azure hizmetlerine parolasız bağlantılar için Azure Kimlik kitaplığı gereklidir:

vcpkg.exe install azure-identity-cpp

Proje kurulumu ve C++ için Azure SDK ile çalışma hakkında daha fazla bilgi için bkz. C++ için Azure SDK benioku.

Projeyi oluşturma

Visual Studio'da, Windows için BlobQuickstart adlı yeni bir C++ konsol uygulaması oluşturun.

Nesne modeli

Azure Blob Depolama, çok büyük miktarlarda yapılandırılmamış verileri depolamak için iyileştirilmiştir. Yapılandırılmamış veriler, metin veya ikili veriler gibi belirli bir veri modeline veya tanımına uymayan verilerdir. Blob Depolama üç tür kaynak sunar:

• Depolama hesabı
• Depolama hesabındaki bir kapsayıcı
• Kapsayıcıdaki bir blob

Aşağıdaki diyagramda bu kaynaklar arasındaki ilişki gösterilmektedir.

Bu kaynaklarla etkileşime geçmek için şu C++ sınıflarını kullanın:

• BlobServiceClient: sınıfı, BlobServiceClient Azure Depolama kaynaklarını ve blob kapsayıcılarını işlemenize olanak tanır.
• BlobContainerClient: sınıfı, BlobContainerClient Azure Depolama kapsayıcılarını ve bloblarını işlemenize olanak tanır.
• BlobClient: sınıfı, BlobClient Azure Depolama bloblarını işlemenize olanak tanır. Tüm özel blob sınıfları için temel sınıftır.
• BlockBlobClient: sınıfı, BlockBlobClient Azure Depolama blok bloblarını işlemenize olanak tanır.

Kod örnekleri

Bu örnek kod parçacıkları, C++ için Azure Blob Depolama istemci kitaplığıyla aşağıdaki görevlerin nasıl yapılacağını gösterir:

• Include dosyaları ekle
• Azure'da kimlik doğrulaması ve blob verilerine erişim yetkisi verme
• Kapsayıcı oluşturma
• Blobları kapsayıcıya yükleme
• Kapsayıcıdaki blobları listeleme
• Blobları indirme
• Kapsayıcıyı silme

Include dosyaları ekle

Proje dizininden:

1. BlobQuickstart.sln çözüm dosyasını Visual Studio'da açma
2. Visual Studio'da BlobQuickstart.cpp kaynak dosyasını açın
3. Otomatik oluşturulan kodun içindeki main tüm kodları kaldırma
4. #include ve using namespace ifadelerini ekle

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

Azure'da kimlik doğrulaması ve blob verilerine erişim yetkisi verme

Azure Blob Depolama'ya yönelik uygulama istekleri yetkilendirilmelidir. DefaultAzureCredential Azure Identity istemci kitaplığı tarafından sağlanan sınıfı kullanmak, Blob Depolama da dahil olmak üzere kodunuzdaki Azure hizmetlerine parolasız bağlantılar uygulamak için önerilen yaklaşımdır.

Ayrıca hesap erişim anahtarını kullanarak Azure Blob Depolama'ya yönelik istekleri yetkilendirilebilirsiniz. Ancak bu yaklaşım dikkatli kullanılmalıdır. Geliştiriciler, erişim anahtarını güvenli olmayan bir konumda asla kullanıma sunmamak için dikkatli olmalıdır. Erişim anahtarına sahip olan herkes, depolama hesabına yönelik istekleri yetkilendirebiliyor ve tüm verilere etkin bir şekilde erişim sahibi oluyor. DefaultAzureCredential parolasız kimlik doğrulamasına izin vermek için hesap anahtarı üzerinde gelişmiş yönetim ve güvenlik avantajları sunar. Her iki seçenek de aşağıdaki örnekte gösterilmiştir.

Parolasız (Önerilen)

Azure Kimlik kitaplığı, Azure SDK genelinde Microsoft Entra belirteci kimlik doğrulaması desteği sağlar. Microsoft Entra belirteci kimlik doğrulamasını TokenCredential destekleyen Azure SDK istemcileri oluşturmak için kullanılabilecek bir dizi uygulama sağlar. DefaultAzureCredential birden çok kimlik doğrulama yöntemini destekler ve çalışma zamanında hangi yöntemin kullanılacağını belirler.

Microsoft Entra kullanıcı hesabınıza rol atama

Yerel olarak geliştirme yaparken blob verilerine erişen kullanıcı hesabının doğru izinlere sahip olduğundan emin olun. Blob verilerini okumak ve yazmak için "Storage Blob Data Contributor" rolüne ihtiyacınız vardır. Kendinize bu rolü atamak için Kullanıcı Erişimi Yöneticisi rolüne veya Microsoft.Authorization/roleAssignments/write eylemini içeren başka bir role atanmalısınız. Azure portalı, Azure CLI veya Azure PowerShell'i kullanarak kullanıcıya Azure RBAC rolleri atayabilirsiniz. Depolama Blob Verisi Katkıda Bulunan rolü hakkında daha fazla bilgi için Depolama Blob Verisi Katkıda Bulunan sayfasına bakın. Rol atamaları için kullanılabilir kapsamlar hakkında daha fazla bilgi için bkz. Azure RBAC kapsamını anlama.

Bu senaryoda, En Az Ayrıcalık İlkesi'ni izlemek için depolama hesabı kapsamındaki kullanıcı hesabınıza izinler atayacaksınız. Bu uygulama kullanıcılara yalnızca gereken minimum izinleri verir ve daha güvenli üretim ortamları oluşturur.

Aşağıdaki örnek, depolama hesabınızdaki blob verilerine hem okuma hem de yazma erişimi sağlayan Depolama Blob Verileri Katkıda Bulunanı rolünü kullanıcı hesabınıza atar.

Önemli

Çoğu durumda rol atamasının Azure'a yayılması bir veya iki dakika sürer, ancak nadir durumlarda sekiz dakikaya kadar sürebilir. Kodunuzu ilk kez çalıştırdığınızda kimlik doğrulama hataları alıyorsanız, birkaç dakika bekleyin ve yeniden deneyin.

Azure portalı

1. Azure portalında ana arama çubuğunu veya sol gezintiyi kullanarak depolama hesabınızı bulun.

2. Depolama hesabına genel bakış sayfasında sol taraftaki menüden Erişim denetimi (IAM) öğesini seçin.

3. Erişim denetimi (IAM) sayfasında Rol atamaları sekmesini seçin.

4. Üstteki menüden + ekle'yi seçin ve ardından açılan menüden Rol ataması ekle'ü seçin.

   

5. Sonuçları istenen role göre filtrelemek için arama kutusunu kullanın. Bu örnek için Depolama Blobu Veri Katkıda Bulunanı'nı arayın ve eşleşen sonucu seçin ve ardından İleri'yi seçin.

6. Erişim atama altında, Kullanıcı, grup veya hizmet sorumlusu seçeneğini seçin ve ardından + Üyeleri seç seçeneğine tıklayın.

7. İletişim kutusunda Microsoft Entra kullanıcı adınızı (genellikle user@domain e-posta adresiniz) arayın ve iletişim kutusunun alt kısmındaki Seç'i seçin.

8. Son sayfaya gitmek için Gözden geçir + ata'yı seçin ve işlemi tamamlamak için Gözden geçir + ata'yı tekrar seçin.

Azure CLI

Azure CLI kullanarak kaynak düzeyinde bir rol atamak için önce komutunu kullanarak az storage account show kaynak kimliğini almanız gerekir. parametresini kullanarak --query çıkış özelliklerini filtreleyebilirsiniz.

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

Önceki komuttan çıktıyı Id kopyalayın. Ardından Azure CLI'nın az role komutunu kullanarak roller atayabilirsiniz.

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

PowerShell

Azure PowerShell kullanarak kaynak düzeyinde bir rol atamak için önce komutunu kullanarak Get-AzResource kaynak kimliğini almanız gerekir.

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

Id Önceki komut çıkışındaki değeri kopyalayın. Ardından PowerShell'de New-AzRoleAssignment komutunu kullanarak roller atayabilirsiniz.

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

DefaultAzureCredential kullanarak oturum açın ve uygulama kodunuzu Azure'a bağlayın

Aşağıdaki adımları kullanarak depolama hesabınızdaki verilere erişimi yetkileyebilirsiniz:

1. Depolama hesabınızda rolü atadığınız Microsoft Entra hesabıyla kimliğinizin doğrulanmış olduğundan emin olun. Azure CLI aracılığıyla kimlik doğrulaması yapabilirsiniz. Aşağıdaki komutu kullanarak Azure CLI aracılığıyla Azure'da oturum açın:

   az login
   

2. kullanmak için DefaultAzureCredential, azure-identity-cpp paketinin yüklendiğinden ve aşağıdakinin #include eklendiğinden emin olun.

   #include <azure/identity/default_azure_credential.hpp>
   

3. Bu kodu sonuna main()ekleyin. Kod yerel iş istasyonunuzda çalıştırıldığında, DefaultAzureCredential Azure'da kimlik doğrulaması yapmak için Azure CLI için geliştirici kimlik bilgilerini kullanır.

   // 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. Nesnenizin URI'sindeki depolama hesabı adını güncellediğinizden BlobServiceClient emin olun. Depolama hesabı adı, Azure portalının genel bakış sayfasında bulunabilir.

   

   Uyarı

   C++ SDK'sını üretim ortamında kullanırken yalnızca uygulamanızın kullanacağını bildiğiniz kimlik bilgilerini etkinleştirmeniz önerilir. DefaultAzureCredential kullanmak yerine, belirli bir kimlik bilgisi türünü veya desteklenen kimlik bilgileriyle ChainedTokenCredential kullanarak yetkilendirmeniz gerekir.

Bağlantı Dizesi

bağlantı dizesi depolama hesabı erişim anahtarını içerir ve istekleri yetkilendirmek için bunu kullanır. Anahtarları güvenli olmayan bir konumda asla kullanıma sunmamaya dikkat edin.

Uyarı

Depolama hesabı erişim anahtarıyla veri erişimini yetkilendirmek için şu Azure RBAC eylemi için izinlere ihtiyacınız vardır: Microsoft.Storage/storageAccounts/listkeys/action. Bu eylem için izinlere sahip en az ayrıcalıklı yerleşik rol Okuyucu ve Veri Erişimi'dir, ancak bu eylemi içeren herhangi bir rol çalışır.

Azure portalı

1. Azure portalınaoturum açın.

2. Depolama hesabınızı bulun.

3. Depolama hesabı menü bölmesinde, Güvenlik + ağ altında Erişim anahtarları'nı seçin. Burada hesap erişim anahtarlarını ve her anahtar için tam bağlantı dizesini görüntüleyebilirsiniz.

4. Erişim anahtarları bölmesinde Anahtarlarıgöster'i seçin.

5. anahtar1 bölümünde Bağlantı dizesi değerini bulun. Bağlantı dizesini kopyalamak için Panoya kopyala simgesini seçin. Sonraki bölümde bağlantı dizesi değerini bir ortam değişkenine ekleyeceksiniz.

   

Azure CLI

az storage account show-connection-string komutunu kullanarak depolama hesabınızın bağlantı dizesini görebilirsiniz.

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

PowerShell

Get-AzStorageAccount ve Get-AzStorageAccountKey komutlarını kullanarak PowerShell ile bir bağlantı dizesi oluşturabilirsiniz.

$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'

Depolama bağlantı dizenizi yapılandırma

Bağlantı dizesini kopyaladıktan sonra, uygulamayı çalıştıran yerel makinede yeni bir ortam değişkenine yazın. Ortam değişkenini ayarlamak için bir konsol penceresi açın ve işletim sisteminizin yönergelerini izleyin. <yourconnectionstring> ile gerçek bağlantı dizesini değiştirin.

Windows:

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

Windows'da ortam değişkenini ekledikten sonra komut penceresinin yeni bir örneğini başlatmanız gerekir.

Linux:

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

Aşağıdaki kod örneği, depolama hesabının bağlantı dizesini daha önce oluşturulan ortam değişkeninden alır ve bağlantı dizesini kullanarak bir hizmet istemci nesnesi oluşturur.

Bu kodu sonuna main()ekleyin:

    // 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);

Önemli

Hesap erişim anahtarı dikkatli kullanılmalıdır. Hesap erişim anahtarınız kaybolursa veya yanlışlıkla güvenli olmayan bir konuma yerleştirilirse, hizmetiniz güvenlik açığına maruz kalabilir. Erişim anahtarına sahip olan herkes, depolama hesabına yönelik istekleri yetkilendirebiliyor ve tüm verilere etkin bir şekilde erişim sahibi oluyor. DefaultAzureCredential gelişmiş güvenlik özellikleri ve avantajları sağlar ve Azure hizmetlerine yetkilendirmeyi yönetmek için önerilen yaklaşımdır.

Kapsayıcı oluşturma

Yeni kapsayıcı için bir ad belirleyin. Ardından BlobContainerClient öğesinin bir örneğini oluşturun ve kapsayıcıyı oluşturun.

Önemli

Kapsayıcı adları küçük harfle yazılmalıdır. Kapsayıcıları ve blobları adlandırma hakkında daha fazla bilgi için bkz. Kapsayıcıları, Blobları ve Meta Verileri Adlandırma ve Başvurma.

Bu kodu sonuna main()ekleyin:

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();

Blobları kapsayıcıya yükleme

Aşağıdaki kod parçacığı:

1. "Hello Azure!" içeren bir dize bildirir
2. Create a container bölümünden GetBlockBlobClient metodunu çağırarak bir BlockBlobClient nesnesine referans alır.
3. UploadFrom işlevini çağırarak dizeyi bloba yükler. Bu işlev, blob mevcut değilse oluşturur veya mevcutsa günceller.

Bu kodu sonuna main()ekleyin:

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

Kapsayıcıdaki blobları listeleme

ListBlobs işlevini çağırarak kapsayıcıdaki blobları listeleyin. Kapsayıcıya yalnızca bir blob eklendiğinden işlem yalnızca bu blobu döndürür.

Bu kodu sonuna main()ekleyin:

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

Blobları indirme

Karşıya yüklenen blobun özelliklerini alın. Ardından, karşıya yüklenen blobun özelliklerini kullanarak yeni std::vector<uint8_t> bir nesne bildirin ve yeniden boyutlandırın. std::vector<uint8_t> temel sınıfında DownloadTo işlevini çağırarak daha önce oluşturulan blobu yeni nesneye indirin. Son olarak, indirilen blob verilerini görüntüleyin.

Bu kodu sonuna main()ekleyin:

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;

Bir Blob silme

Aşağıdaki kod BlobClient.Delete işlevini çağırarak Blobu Azure Blob Depolama kapsayıcısından siler.

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

Kapsayıcıyı silme

Aşağıdaki kod, BlobContainerClient kullanarak kapsayıcının tamamını silerek uygulamanın oluşturduğu kaynakları temizler .Sil'i seçin.

Bu kodu sonuna main()ekleyin:

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

Kodu çalıştır

Bu uygulama bir kapsayıcı oluşturur ve bir metin dosyasını Azure Blob Depolama'ya yükler. Örnek daha sonra kapsayıcıdaki blobları listeler, dosyayı indirir ve dosya içeriğini görüntüler. Son olarak, uygulama blobu ve kapsayıcıyı siler.

Uygulamanın çıkışı aşağıdaki örneğe benzer:

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

Sonraki Adımlar

Bu hızlı başlangıçta, C++ kullanarak blobları karşıya yüklemeyi, indirmeyi ve listelemeyi öğrendiniz. Ayrıca Azure Blob Depolama kapsayıcısı oluşturmayı ve silmeyi de öğrendinsiniz.

C++ Blob Depolama örneğini görmek için devam edin:

C++ örnekleri için Azure Blob Depolama istemci kitaplığı