Hızlı Başlangıç: .NET için Azure Blob Depolama istemci kitaplığı v12

.NET için Azure Blob Depolama istemci kitaplığı v12'yi kullanmaya başlayın. Azure Blob Depolama, Microsoft'un bulut için nesne depolama çözümüdür. Paketi yüklemek için adımları izleyin ve temel görevler için örnek kodu deneyin. Blob depolama, çok miktarda yapılandırılmamış veriyi depolamak için iyileştirilmiştir.

Bu hızlı başlangıçtaki örneklerde .NET için Azure Blob Depolama istemci kitaplığı v12'nin nasıl kullanılacağı gösterilmektedir:

Ek kaynaklar:

Önkoşullar

Ayarlama

Bu bölümde, .NET için Azure Blob Depolama istemci kitaplığı v12 ile çalışmak üzere bir proje hazırlama işleminde size yol gösterir.

Proje oluşturma

İlerideki adımlar için .NET CLI veya Visual Studio 2022 kullanarak bir .NET konsol uygulaması oluşturmanız gerekir.

  1. Visual Studio'nun üst kısmında Dosya>Yeni>Proje... seçeneğine gidin.

  2. İletişim kutusu penceresinde, konsol uygulamasını proje şablonu arama kutusuna girin ve ilk sonucu seçin. İletişim kutusunun alt kısmındaki İleri'yi seçin.

    Visual Studio kullanarak yeni proje oluşturmayı gösteren ekran görüntüsü.

  3. Proje Adı için BlobQuickstartV12 girin. Kalan alanlar için varsayılan değerleri bırakın ve İleri'yi seçin.

  4. Çerçeve için .NET 6.0'ın seçili olduğundan emin olun. Ardından Oluştur’u seçin. Yeni proje Visual Studio ortamında açılır.

Paketi yükleme

Azure Blob Depolama ile etkileşim kurmak için .NET için Azure Blob Depolama istemci kitaplığını yükleyin.

  1. Çözüm Gezgini'da projenizin Bağımlılıklar düğümüne sağ tıklayın. NuGet Paketlerini Yönet'i seçin.

  2. Sonuçta elde edilen pencerede Azure.Storage.Blobs araması yapın. Uygun sonucu seçin ve Yükle'yi seçin.

    Visual Studio kullanarak yeni paket eklemeyi gösteren ekran görüntüsü.

Uygulama kodunu ayarlama

Dosyadaki Program.cs başlangıç kodunu, bu alıştırma için gerekli using deyimleri içeren aşağıdaki örnekle eşleşmesi için değiştirin.

using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using System;
using System.IO;

// See https://aka.ms/new-console-template for more information
Console.WriteLine("Hello, World!");

Azure'da uygulamanın kimliğini doğrulama

Azure Blob Depolama uygulama istekleri yetkilendirilmelidir. DefaultAzureCredential Azure.Identity istemci kitaplığı tarafından sağlanan sınıfı kullanmak, Blob Depolama dahil olmak üzere kodunuzdaKimliksiz 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 erişim kazanan herkes kimlik doğrulaması yapabilir. 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.

DefaultAzureCredential , .NET için Azure Identity istemci kitaplığı tarafından sağlanan ve DefaultAzureCredential genel bakışı hakkında daha fazla bilgi edinebileceğiniz bir sınıftır. DefaultAzureCredential birden çok kimlik doğrulama yöntemini destekler ve çalışma zamanında hangi yöntemin kullanılacağını belirler. Bu yaklaşım, uygulamanızın ortama özgü kod uygulamadan farklı ortamlarda (yerel ve üretim) farklı kimlik doğrulama yöntemleri kullanmasını sağlar.

Kimlik bilgilerinin arandığı DefaultAzureCredential sıra ve konumlar Azure Kimlik kitaplığına genel bakış sayfasında bulunabilir.

Kimlik bilgisi akışının diyagramı.

Örneğin, uygulamanız yerel olarak geliştirme yaparken Ile Visual Studio oturum açma kimlik bilgilerinizi kullanarak kimlik doğrulaması yapabilir. Uygulamanız, Azure'a dağıtıldıktan sonra yönetilen kimliği kullanabilir. Bu geçiş için kod değişikliği gerekmez.

Azure AD kullanıcı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 Verileri Katkıda Bulunanı gerekir. 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 ihtiyacınız vardır. Azure portal, Azure CLI veya Azure PowerShell kullanarak kullanıcıya Azure RBAC rolleri atayabilirsiniz. Kapsam genel bakış sayfasında rol atamaları için kullanılabilir kapsamlar hakkında daha fazla bilgi edinebilirsiniz.

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 en düşük izinleri verir ve daha güvenli üretim ortamları oluşturur.

Aşağıdaki örnek, rolü depolama hesabınızdaki Storage Blob Data Contributor blob verilerine hem okuma hem de yazma erişimi sağlayan 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 dakika kadar sürebilir. Kodunuzu ilk kez çalıştırdığınızda kimlik doğrulama hataları alıyorsanız birkaç dakika bekleyin ve yeniden deneyin.

  1. Azure portal 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 ve ardından sonuçta elde edilen açılan menüden Rol ataması ekle'yi seçin.

    Rol atamayı gösteren ekran görüntüsü.

  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 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, Azure AD kullanıcı adınızı (genellikle user@domain e-posta adresiniz) arayın ve iletişim kutusunun altı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 ve yeniden ata'yı seçin.

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şim yetkisi vekleyebilirsiniz:

  1. Blob Depolama hesabınızda rolü atadığınız Azure AD hesabıyla kimliğinizin doğrulanmış olduğundan emin olun. Azure CLI, Visual Studio veya Azure PowerShell 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 paketini uygulamanıza ekleyin.

    1. Çözüm Gezgini'da projenizin Bağımlılıklar düğümüne sağ tıklayın. NuGet Paketlerini Yönet'i seçin.

    2. Sonuçta elde edilen pencerede Azure.Identity araması yapın. Uygun sonucu seçin ve Yükle'yi seçin.

      Kimlik paketinin nasıl ekleneceğini gösteren ekran görüntüsü.

  3. Program.cs kodunuzu aşağıdaki örnekle eşleşecek şekilde güncelleştirin. Kod geliştirme sırasında yerel iş istasyonunuzda çalıştırıldığında, Azure CLI veya Visual Studio gibi Azure'da kimlik doğrulaması yapmak için oturum açtığınız öncelikli aracın geliştirici kimlik bilgilerini kullanır.

    using Azure.Storage.Blobs;
    using Azure.Storage.Blobs.Models;
    using System;
    using System.IO;
    using Azure.Identity;
    
    // TODO: Replace <storage-account-name> with your actual storage account name
    var blobServiceClient = new BlobServiceClient(
            new Uri("https://<storage-account-name>.blob.core.windows.net"),
            new DefaultAzureCredential());
    
  4. URI'nizdeki Depolama hesabı adını güncelleştirdiğinden BlobServiceClientemin olun. Depolama hesabı adı, Azure portal genel bakış sayfasında bulunabilir.

    Depolama hesabı adını bulma işlemini gösteren ekran görüntüsü.

    Not

    Azure'a dağıtıldığında, Azure'da çalışan bir uygulamadan Azure Depolama'ya yönelik istekleri yetkilendirmek için de aynı kod kullanılabilir. Ancak Azure'da uygulamanızda yönetilen kimliği etkinleştirmeniz gerekir. Ardından Blob Depolama hesabınızı bu yönetilen kimliğin bağlanmasına izin verecek şekilde yapılandırın. Azure hizmetleri arasında bu bağlantıyı yapılandırma hakkında ayrıntılı yönergeler için Bkz. Azure'da barındırılan uygulamalardan kimlik doğrulama öğreticisi.

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.

Blob depolama mimarisinin diyagramı.

Bu kaynaklarla etkileşime geçmek için aşağıdaki .NET 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.

Kod örnekleri

Aşağıdaki bölümlerde yer alan örnek kod parçacıkları, .NET için Azure Blob Depolama istemci kitaplığıyla temel veri işlemlerinin nasıl gerçekleştirileceklerini göstermektedir.

Önemli

Ayarlama bölümünde açıklandığı gibi, kod örneklerinin çalışması için doğru NuGet paketlerini yüklediğinizden ve gerekli using deyimlerini eklediğinizden emin olun.

  • Azure.Identity (parolasız yaklaşımı kullanıyorsanız)
  • Azure.Storage.Blobs

Kapsayıcı oluşturma

Yeni kapsayıcı için bir ad belirleyin. Aşağıdaki kod, benzersiz olduğundan emin olmak için kapsayıcı adına bir GUID değeri ekler.

Ö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.

Depolama hesabınızda bir kapsayıcı oluşturmak için üzerinde blobServiceClientCreateBlobContainerAsync yöntemini çağırabilirsiniz.

Bu kodu sınıfın Program.cs sonuna ekleyin:

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.windows.net"),
        new DefaultAzureCredential());

//Create a unique name for the container
string containerName = "quickstartblobs" + Guid.NewGuid().ToString();

// Create the container and return a container client object
BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);

Bir kapsayıcıya blob yükleme

Sınıfın sonuna Program.cs aşağıdaki kodu ekleyin:

// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "data";
Directory.CreateDirectory(localPath);
string fileName = "quickstart" + Guid.NewGuid().ToString() + ".txt";
string localFilePath = Path.Combine(localPath, fileName);

// Write text to the file
await File.WriteAllTextAsync(localFilePath, "Hello, World!");

// Get a reference to a blob
BlobClient blobClient = containerClient.GetBlobClient(fileName);

Console.WriteLine("Uploading to Blob storage as blob:\n\t {0}\n", blobClient.Uri);

// Upload data from the local file
await blobClient.UploadAsync(localFilePath, true);

Kod parçacığı aşağıdaki adımları tamamlar:

  1. Yerel veri dizininde bir metin dosyası oluşturur.
  2. Kapsayıcı oluşturma bölümünden kapsayıcıdaki GetBlobClient yöntemini çağırarak birBlobClient nesnesine başvuru alır.
  3. UploadAsync yöntemini çağırarak yerel metin dosyasını bloba yükler. Bu yöntem, daha önce oluşturulmadıysa bir blob oluşturur, aksi takdirde üzerine yazar.

Kapsayıcıdaki blobları listeleme

GetBlobsAsync yöntemini çağırarak kapsayıcıdaki blobları listeleyin. Bu durumda kapsayıcıya yalnızca bir blob eklendiğinden listeleme işlemi yalnızca bu blobu döndürür.

Sınıfın sonuna Program.cs aşağıdaki kodu ekleyin:

Console.WriteLine("Listing blobs...");

// List all blobs in the container
await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
{
    Console.WriteLine("\t" + blobItem.Name);
}

Blobu indirme

DownloadToAsync yöntemini çağırarak daha önce oluşturulan blobu indirin. Örnek kod, her iki dosyayı da yerel dosya sisteminde görebilmeniz için dosya adına "İnDİrİlDİ" son ekini ekler.

Sınıfın sonuna Program.cs aşağıdaki kodu ekleyin:

// Download the blob to a local file
// Append the string "DOWNLOADED" before the .txt extension 
// so you can compare the files in the data directory
string downloadFilePath = localFilePath.Replace(".txt", "DOWNLOADED.txt");

Console.WriteLine("\nDownloading blob to\n\t{0}\n", downloadFilePath);

// Download the blob's contents and save it to a file
await blobClient.DownloadToAsync(downloadFilePath);

Kapsayıcı silme

Aşağıdaki kod DeleteAsync kullanarak kapsayıcının tamamını silerek uygulamanın oluşturduğu kaynakları temizler. Ayrıca uygulama tarafından oluşturulan yerel dosyaları da siler.

Uygulama blobu, kapsayıcıyı ve yerel dosyaları silmeden önce çağırarak Console.ReadLine kullanıcı girişi için duraklatılır. Bu, kaynakların silinmeden önce doğru şekilde oluşturulduğunu doğrulamak için iyi bir fırsattır.

Sınıfın sonuna Program.cs aşağıdaki kodu ekleyin:

// Clean up
Console.Write("Press any key to begin clean up");
Console.ReadLine();

Console.WriteLine("Deleting blob container...");
await containerClient.DeleteAsync();

Console.WriteLine("Deleting the local source and downloaded files...");
File.Delete(localFilePath);
File.Delete(downloadFilePath);

Console.WriteLine("Done");

Tamamlanan kod

Bu adımları tamamladıktan sonra dosyanızdaki Program.cs kod artık aşağıdakine benzer olmalıdır:

using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using Azure.Identity;

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.windows.net"),
        new DefaultAzureCredential());

//Create a unique name for the container
string containerName = "quickstartblobs" + Guid.NewGuid().ToString();

// Create the container and return a container client object
BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);

// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "data";
Directory.CreateDirectory(localPath);
string fileName = "quickstart" + Guid.NewGuid().ToString() + ".txt";
string localFilePath = Path.Combine(localPath, fileName);

// Write text to the file
await File.WriteAllTextAsync(localFilePath, "Hello, World!");

// Get a reference to a blob
BlobClient blobClient = containerClient.GetBlobClient(fileName);

Console.WriteLine("Uploading to Blob storage as blob:\n\t {0}\n", blobClient.Uri);

// Upload data from the local file
await blobClient.UploadAsync(localFilePath, true);

Console.WriteLine("Listing blobs...");

// List all blobs in the container
await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
{
    Console.WriteLine("\t" + blobItem.Name);
}

// Download the blob to a local file
// Append the string "DOWNLOADED" before the .txt extension 
// so you can compare the files in the data directory
string downloadFilePath = localFilePath.Replace(".txt", "DOWNLOADED.txt");

Console.WriteLine("\nDownloading blob to\n\t{0}\n", downloadFilePath);

// Download the blob's contents and save it to a file
await blobClient.DownloadToAsync(downloadFilePath);

// Clean up
Console.Write("Press any key to begin clean up");
Console.ReadLine();

Console.WriteLine("Deleting blob container...");
await containerClient.DeleteAsync();

Console.WriteLine("Deleting the local source and downloaded files...");
File.Delete(localFilePath);
File.Delete(downloadFilePath);

Console.WriteLine("Done");

Kodu çalıştırma

Bu uygulama, yerel veri klasörünüzde bir test dosyası oluşturur ve Blob depolamaya yükler. Örnek daha sonra kapsayıcıdaki blobları listeler ve eski ve yeni dosyaları karşılaştırabilmeniz için dosyayı yeni bir adla indirir.

Visual Studio kullanıyorsanız kodu derleyip çalıştırmak ve konsol uygulamasıyla etkileşim kurmak için F5 tuşuna basın. .NET CLI kullanıyorsanız uygulama dizininize gidin ve uygulamayı derleyip çalıştırın.

dotnet build
dotnet run

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

Azure Blob Storage v12 - .NET quickstart sample

Uploading to Blob storage as blob:
         https://mystorageacct.blob.core.windows.net/quickstartblobs60c70d78-8d93-43ae-954d-8322058cfd64/quickstart2fe6c5b4-7918-46cb-96f4-8c4c5cb2fd31.txt

Listing blobs...
        quickstart2fe6c5b4-7918-46cb-96f4-8c4c5cb2fd31.txt

Downloading blob to
        ./data/quickstart2fe6c5b4-7918-46cb-96f4-8c4c5cb2fd31DOWNLOADED.txt

Press any key to begin clean up
Deleting blob container...
Deleting the local source and downloaded files...
Done

Temizleme işlemine başlamadan önce iki dosya için veri klasörünüzü denetleyin. Dosyaları açarak aynı olduklarını görebilirsiniz.

Dosyaları doğruladıktan sonra Test dosyalarını silmek ve tanıtımı tamamlamak için Enter tuşuna basın.

Sonraki adımlar

Bu hızlı başlangıçta .NET kullanarak blobları karşıya yükleme, indirme ve listeleme hakkında bilgi edindiniz.

Blob depolama örnek uygulamalarını görmek için devam edin: