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 |

Ön koş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

Ayarlama

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++ ve gerekli bağımlılıklar için Azure Blob Depolama kitaplığını 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.

Proje 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ıma bağlı olmayan 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şlemenizi sağlar.

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:

• Ekleme dosyaları ekleme
• 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ı silme

Ekleme dosyaları ekleme

Proje dizininden:

1. Visual Studio'da BlobQuickstart.sln çözüm dosyasını 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. ve using namespace deyimleri ekleme #include

#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 uygulama istekleri yetkilendirilmelidir. DefaultAzureCredential Azure Identity istemci kitaplığı tarafından sağlanan sınıfın kullanılması, Blob Depolama dahil olmak üzere kodunuzda Azure hizmetlerine parolasız bağlantılar uygulamak için önerilen yaklaşımdır.

Ayrıca, hesap erişim anahtarını kullanarak istekleri Azure Blob Depolama yetkilendirmeniz de gerekir. 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 Depolama Blob Veri Katkıda Bulunanı gerekir. Kendinize bu rolü atamak için Kullanıcı Erişimi Yönetici istrator 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. Rol atamaları için kullanılabilir kapsamlar hakkında daha fazla bilgiyi kapsam genel bakış sayfasından öğrenebilirsiniz.

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. Üst menüden + Ekle'yi seçin ve ardından açılan menüden Rol ataması ekle'yi seçin.

   

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

6. Erişim ata'nın altında Kullanıcı, grup veya hizmet sorumlusu'na tıklayın ve ardından + Üye seç'e 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 ardından işlemi tamamlamak için Gözden geçir + yeniden ata'yı 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 DefaultAzureCredentialiçin azure-identity-cpp paketinin yüklendiğinden ve aşağıdakilerin #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üncelleştirdiğinden BlobServiceClient emin olun. Depolama hesabı adı, Azure portalının genel bakış sayfasında bulunabilir.

   

   Dekont

   C++ SDK'sını üretim ortamında kullanırken yalnızca uygulamanızın kullanacağını bildiğiniz kimlik bilgilerini etkinleştirmeniz önerilir. kullanmak DefaultAzureCredentialyerine, belirli bir kimlik bilgisi türünü veya desteklenen kimlik bilgilerini kullanarak ChainedTokenCredential 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.

Dekont

Depolama hesabı erişim anahtarıyla veri erişimini yetkilendirmek için aşağıdaki Azure RBAC eylemi için izinlere sahip olmanız gerekir: Microsoft.Depolama/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 oturum 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ı dizesi görüntüleyebilirsiniz.

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

5. key1 bölümünde, Bağlan ion dizesi değerini bulun. bağlantı dizesi kopyalamak için Panoya kopyala simgesini seçin. sonraki bölümde ortam değişkenine bağlantı dizesi değeri ekleyeceksiniz.

   

Azure CLI

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

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

PowerShell

Get-Az Depolama Account ve Get-Az Depolama AccountKey komutlarını kullanarak PowerShell ile bir bağlantı dizesi birleştirebilirsiniz.

$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ı dizelerinizi yapılandırma

bağlantı dizesi 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. değerini gerçek bağlantı dizesi ile değiştirin<yourconnectionstring>.

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ı dizesi daha önce oluşturulan ortam değişkeninden alır ve hizmet istemci nesnesi oluşturmak için bağlantı dizesi kullanır.

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 öğesinin bir örneğini BlobContainerClient oluşturun ve kapsayıcıyı oluşturun.

Önemli

Kapsayıcı adlarının küçük harfle yazılması gerekir. 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 Bunlara 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. Kapsayıcı oluşturma bölümünden kapsayıcıda GetBlockBlobClient çağrısı yaparak BlockBlobClient nesnesine başvuru alır.
3. UploadFrom işlevini çağırarak dizeyi bloba yükler. Bu işlev, henüz yoksa blobu oluşturur veya varsa güncelleştirir.

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

Blob’ları 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. BlobClient temel sınıfında DownloadTo işlevini çağırarak daha önce oluşturulan blobu yeni std::vector<uint8_t> 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;

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ı 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ırma

Bu uygulama bir kapsayıcı oluşturur ve Azure Blob Depolama bir metin dosyası 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 bir 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ığı