Aracılığıyla paylaş

.NET ile blob yükleme

Bu makalede, .NET için Azure Depolama istemci kitaplığını kullanarak bir blobun nasıl karşıya yükleneceği gösterilmektedir. Bir dosya yolundan, akıştan, ikili nesneden veya metin dizesinden blok bloba veri yükleyebilirsiniz. Ayrıca bir blob akışını açıp bu akışa yazabilir veya büyük blobları bloklar halinde karşıya yükleyebilirsiniz.

Önkoşullar

Ortamınızı ayarlama

Var olan bir projeniz yoksa, bu bölümde bir projenin .NET için Azure Blob Depolama istemci kitaplığıyla çalışacak şekilde nasıl ayarlanacağı gösterilir. Adımlar arasında paket yükleme, yönergeler ekleme using ve yetkili istemci nesnesi oluşturma yer alır. Ayrıntılar için bkz. Azure Blob Depolama ve .NET'i kullanmaya başlama.

Paketleri yükleme

Proje dizininizden komutunu kullanarak dotnet add package Azure Blob Depolama ve Azure Identity istemci kitaplıkları için paketleri yükleyin. Azure hizmetlerine parolasız bağlantılar için Azure.Identity paketi gereklidir.

dotnet add package Azure.Storage.Blobs
dotnet add package Azure.Identity

using yönergeleri ekle

Kod dosyanızın en üstüne şu using yönergeleri ekleyin:

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

Bu makaledeki bazı kod örnekleri için ek using yönergeler gerekebilir.

İstemci nesnesi oluşturma

Bir uygulamayı Blob Depolama'ya bağlamak için bir BlobServiceClient örneği oluşturun. Aşağıdaki örnekte yetkilendirme için kullanarak DefaultAzureCredential bir istemci nesnesinin nasıl oluşturulacağı gösterilmektedir:

public BlobServiceClient GetBlobServiceClient(string accountName)
{
    BlobServiceClient client = new(
        new Uri($"https://{accountName}.blob.core.windows.net"),
        new DefaultAzureCredential());

    return client;
}

Bir .NET uygulamasına bağımlılık ekleme için bir hizmet istemcisi kaydedebilirsiniz.

Ayrıca, belirli kapsayıcılar veya bloblar için istemci nesneleri de oluşturabilirsiniz. İstemci nesneleri oluşturma ve yönetme hakkında daha fazla bilgi edinmek için bkz . Veri kaynaklarıyla etkileşim kuran istemci nesneleri oluşturma ve yönetme.

Yetkilendirme

Yetkilendirme mekanizması, bir blob yüklemek için gerekli izinlere sahip olmalıdır. Microsoft Entra ID ile yetkilendirme için (önerilir), Azure RBAC yerleşik rolü Depolama Blob Verileri Katılımcısı veya üzeri gerekir. Daha fazla bilgi edinmek için Put Blob (REST API) ve Put Block (REST API) yetkilendirme kılavuzuna bakın.

Blok bloba veri yükleme

Blok bloba veri yüklemek için aşağıdaki yöntemlerden birini kullanabilirsiniz:

Bu karşıya yükleme yöntemlerini kullanırken, istemci kitaplığı Put Blob veya bir dizi Put Block çağrısını takip eden Put Block List çağrısını yapabilir. Bu davranış, nesnenin genel boyutuna ve veri aktarımı seçeneklerinin nasıl ayarlandığına bağlıdır.

Blob Depolama'da bir akışı açmak ve bu akışa yazmak için aşağıdaki yöntemlerden birini kullanın:

Note

Azure Depolama istemci kitaplıkları aynı bloba eş zamanlı yazmaları desteklemez. Uygulamanız aynı bloba birden çok işlem yazma gerektiriyorsa, öngörülebilir bir deneyim sağlamak için eşzamanlılık denetimine yönelik bir strateji uygulamanız gerekir. Eşzamanlılık stratejileri hakkında daha fazla bilgi edinmek için bkz. Blob Depolama'da eşzamanlılığı yönetme.

Yerel dosya yolundan blok blobu yükleme

Aşağıdaki örnek yerel bir dosya yolundan blok blobunu karşıya yükler:

public static async Task UploadFromFileAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    await blobClient.UploadAsync(localFilePath, true);
}

Akıştan blok blobu yükleme

Aşağıdaki örnek, bir Stream nesnesi oluşturur ve bu akışı karşıya yükleyerek blok blobunu karşıya yükler.

public static async Task UploadFromStreamAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    FileStream fileStream = File.OpenRead(localFilePath);
    await blobClient.UploadAsync(fileStream, true);
    fileStream.Close();
}

BinaryData nesnesinden blok blobu yükleme

Aşağıdaki örnek bir BinaryData nesnesinden blok blobu yükler.

public static async Task UploadFromBinaryDataAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    FileStream fileStream = File.OpenRead(localFilePath);
    BinaryReader reader = new BinaryReader(fileStream);

    byte[] buffer = new byte[fileStream.Length];
    reader.Read(buffer, 0, buffer.Length);
    BinaryData binaryData = new BinaryData(buffer);

    await blobClient.UploadAsync(binaryData, true);

    fileStream.Close();
}

Bir dizgiden blok blob yükle

Aşağıdaki örnek, bir dizeden bir blok bloğu yükler:

public static async Task UploadFromStringAsync(
    BlobContainerClient containerClient,
    string blobName)
{
    BlobClient blobClient = containerClient.GetBlobClient(blobName);
    string blobContents = "Sample blob data";

    await blobClient.UploadAsync(BinaryData.FromString(blobContents), overwrite: true);
}

Blob Depolama'da bir veri akışına yükleme

Blob Depolama'da bir akışı açabilir ve buna yazabilirsiniz. Aşağıdaki örnek, Blob Depolama'da bir zip dosyası oluşturur ve dosyaları bu dosyaya yazar. Yerel bellekte zip dosyası oluşturmak yerine, aynı anda yalnızca bir dosya bellektedir.

Uyarı

Akışa her yazma işlemi zip dosyasının yeni bir sürümünü oluşturduğundan ve her sürüm hedef hesaba kopyalandığından nesne çoğaltma ilkesi etkinleştirildiğinde bu yaklaşım çok pahalı olabilir. Kasalı yedekleme nesne çoğaltma kullandığından Azure Blob kasalı yedekleme etkinleştirildiyse aynı durum geçerlidir.

public static async Task UploadToStreamAsync(
    BlobContainerClient containerClient,
    string localDirectoryPath)
{
    string zipFileName = Path.GetFileName(
        Path.GetDirectoryName(localDirectoryPath)) + ".zip";

    BlockBlobClient blockBlobClient = containerClient.GetBlockBlobClient(zipFileName);

    using (Stream stream = await blockBlobClient.OpenWriteAsync(true))
    {
        using (ZipArchive zip = new ZipArchive(stream, ZipArchiveMode.Create, leaveOpen: false))
        {
            foreach (var fileName in Directory.EnumerateFiles(localDirectoryPath))
            {
                using (var fileStream = File.OpenRead(fileName))
                {
                    var entry = zip.CreateEntry(
                        Path.GetFileName(fileName), CompressionLevel.Optimal);
                    using (var innerFile = entry.Open())
                    {
                        await fileStream.CopyToAsync(innerFile);
                    }
                }
            }
        }
    }
}

Yapılandırma seçenekleriyle blok blobu karşıya yükleme

Blob yüklerken istemci kitaplığı yapılandırma seçeneklerini tanımlayabilirsiniz. Bu seçenekler performansı geliştirmek, güvenilirliği artırmak ve maliyetleri iyileştirmek için ayarlanabilir. Aşağıdaki kod örnekleri, karşıya yükleme yöntemini çağırırken yapılandırma seçeneklerini tanımlamak için BlobUploadOptions'ın nasıl kullanılacağını gösterir.

Karşıya yüklemede veri aktarımı seçeneklerini belirtme

Veri aktarımı işlemlerinin performansını artırmak için StorageTransferOptions içindeki değerleri yapılandırabilirsiniz. Aşağıdaki kod örneği, StorageTransferOptions değerlerini nasıl ayarlayacağınızı ve seçenekleri bir BlobUploadOptions örneğine nasıl dahil edeceğinizi gösterir. Bu örnekte sağlanan değerler bir öneri olarak tasarlanmamıştır. Bu değerleri düzgün ayarlamak için uygulamanızın belirli gereksinimlerini dikkate almanız gerekir.

public static async Task UploadWithTransferOptionsAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    var transferOptions = new StorageTransferOptions
    {
        // Set the maximum number of parallel transfer workers
        MaximumConcurrency = 2,

        // Set the initial transfer length to 8 MiB
        InitialTransferSize = 8 * 1024 * 1024,

        // Set the maximum length of a transfer to 4 MiB
        MaximumTransferSize = 4 * 1024 * 1024
    };

    var uploadOptions = new BlobUploadOptions()
    {
        TransferOptions = transferOptions
    };

    FileStream fileStream = File.OpenRead(localFilePath);
    await blobClient.UploadAsync(fileStream, uploadOptions);
    fileStream.Close();
}

Veri aktarımı seçeneklerini ayarlama hakkında daha fazla bilgi edinmek için bkz . .NET ile karşıya yükleme ve indirme işlemleri için performans ayarlama.

Karşıya yüklemede aktarım doğrulama seçeneklerini belirtin

Aktarım sırasında verilerin düzgün bir şekilde karşıya yüklendiğinden ve üzerinde oynanmadığından emin olmak için aktarım doğrulama seçeneklerini belirtebilirsiniz. Aktarım doğrulama seçenekleri, istemci düzeyinde tanımlanabilir ve BlobClientOptions kullanılarak BlobClient örneğinden çağrılan tüm yöntemlere doğrulama seçenekleri uygulanır.

BlobUploadOptions kullanarak yöntem düzeyinde aktarım doğrulama seçeneklerini de geçersiz kılabilirsiniz. Aşağıdaki kod örneği, bir BlobUploadOptions nesnenin nasıl oluşturulacağını ve sağlama toplamı oluşturmak için bir algoritmanın nasıl belirtileceğini gösterir. Sağlama toplamı daha sonra hizmet tarafından karşıya yüklenen içeriğin veri bütünlüğünü doğrulamak için kullanılır.

public static async Task UploadWithChecksumAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    var validationOptions = new UploadTransferValidationOptions
    {
        ChecksumAlgorithm = StorageChecksumAlgorithm.Auto
    };

    var uploadOptions = new BlobUploadOptions()
    {
        TransferValidation = validationOptions
    };

    FileStream fileStream = File.OpenRead(localFilePath);
    await blobClient.UploadAsync(fileStream, uploadOptions);
    fileStream.Close();
}

Aşağıdaki tabloda, StorageChecksumAlgorithm tarafından tanımlanan sağlama toplamı algoritması için kullanılabilir seçenekler gösterilmektedir:

Adı Value Açıklama
Otomatik 0 Tavsiye edilir. Kitaplığın bir algoritma seçmesine izin verir. Farklı kitaplık sürümleri farklı algoritmalar seçebilir.
Hiçbiri 1 Seçili algoritma yok. Sağlama toplamlarını hesaplamayın veya istemeyin.
MD5 2 Standart MD5 karma algoritması.
StorageCrc64 3 Azure Depolama özel 64 bit CRC.

Note

İstekte belirtilen sağlama toplamı hizmet tarafından hesaplanan sağlama toplamıyla eşleşmiyorsa karşıya yükleme işlemi başarısız olur. Varsayılan yeniden deneme ilkesi kullanılırken işlem yeniden denenmiyor. .NET'te, hangi algoritmanın kullanıldığına bağlı olarak durum kodu 400 ve hata kodu RequestFailedException veya Md5Mismatch ile bir Crc64Mismatch fırlatılır.

Dizin etiketleriyle yükle

Blob dizin etiketleri, anahtar-değer etiketi özniteliklerini kullanarak depolama hesabınızdaki verileri kategorilere ayırır. Bu etiketler otomatik olarak dizinlenir ve verileri kolayca bulmak için aranabilir çok boyutlu bir dizin olarak kullanıma sunulur. BlobUploadOptions örneğine etiket ekleyebilir ve bu örneği yöntemine UploadAsync geçirebilirsiniz.

Aşağıdaki örnek, indeks etiketleri bulunan bir blok blobunu yükler.

public static async Task UploadBlobWithTagsAsync(
    BlobContainerClient containerClient,
    string blobName)
{
    BlobClient blobClient = containerClient.GetBlobClient(blobName);
    string blobContents = "Sample blob data";

    BlobUploadOptions options = new BlobUploadOptions();
    options.Tags = new Dictionary<string, string>
    {
        { "Sealed", "false" },
        { "Content", "image" },
        { "Date", "2020-04-20" }
    };

    await blobClient.UploadAsync(BinaryData.FromString(blobContents), options);
}

Yüklerken bir blob'un erişim katmanını ayarla

BlobUploadOptions sınıfını kullanarak karşıya yükleme sırasında bir blob'un erişim katmanını ayarlayabilirsiniz. Aşağıdaki kod örneğinde blob karşıya yüklenirken erişim katmanının nasıl ayarlanacağı gösterilmektedir:

public static async Task UploadWithAccessTierAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlockBlobClient blockBlobClient = containerClient.GetBlockBlobClient(fileName);

    var uploadOptions = new BlobUploadOptions()
    {
        AccessTier = AccessTier.Cool
    };

    FileStream fileStream = File.OpenRead(localFilePath);
    await blockBlobClient.UploadAsync(fileStream, uploadOptions);
    fileStream.Close();
}

Erişim katmanının ayarlanmasına yalnızca blok blobları için izin verilir. Blok blobu için erişim katmanını Hot, , CoolColdveya Archiveolarak ayarlayabilirsiniz. Erişim katmanını olarak ayarlamak için Colden az 12.15.0 istemci kitaplığı sürümünü kullanmanız gerekir.

Erişim katmanları hakkında daha fazla bilgi edinmek için bkz . Erişim katmanlarına genel bakış.

Blokları hazırlama ve işleme yoluyla blok blobu yükleme

Bireysel veri bloklarını aşamalı olarak düzenleyerek yüklemeleri bloklara bölme konusunda daha fazla denetime sahip olabilirsiniz. Blobu oluşturan tüm bloklar hazırlandığında, bunları Blob Depolama'ya işleyebilirsiniz. Blokları paralel olarak karşıya yükleyerek performansı geliştirmek için bu yaklaşımı kullanabilirsiniz.

public static async Task UploadBlocksAsync(
    BlobContainerClient blobContainerClient,
    string localFilePath,
    int blockSize)
{
    string fileName = Path.GetFileName(localFilePath);
    BlockBlobClient blobClient = blobContainerClient.GetBlockBlobClient(fileName);

    FileStream fileStream = File.OpenRead(localFilePath);
    ArrayList blockIDArrayList = new ArrayList();
    byte[] buffer;

    var bytesLeft = (fileStream.Length - fileStream.Position);

    while (bytesLeft > 0)
    {
        if (bytesLeft >= blockSize)
        {
            buffer = new byte[blockSize];
            await fileStream.ReadAsync(buffer, 0, blockSize);
        }
        else
        {
            buffer = new byte[bytesLeft];
            await fileStream.ReadAsync(buffer, 0, Convert.ToInt32(bytesLeft));
            bytesLeft = (fileStream.Length - fileStream.Position);
        }

        using (var stream = new MemoryStream(buffer))
        {
            string blockID = Convert.ToBase64String(
                Encoding.UTF8.GetBytes(Guid.NewGuid().ToString()));

            blockIDArrayList.Add(blockID);
            await blobClient.StageBlockAsync(blockID, stream);
        }
        bytesLeft = (fileStream.Length - fileStream.Position);
    }

    string[] blockIDArray = (string[])blockIDArrayList.ToArray(typeof(string));

    await blobClient.CommitBlockListAsync(blockIDArray);
}

Kaynaklar

.NET için Azure Blob Depolama istemci kitaplığını kullanarak blobları karşıya yükleme hakkında daha fazla bilgi edinmek için aşağıdaki kaynaklara bakın.

Kod örnekleri

REST API işlemleri

.NET için Azure SDK, Azure REST API'sinin üzerinde derlenmiş kitaplıklar içerir ve tanıdık .NET paradigmalarıyla REST API işlemleriyle etkileşim kurmanızı sağlar. Blobları karşıya yüklemek için istemci kitaplığı yöntemleri aşağıdaki REST API işlemlerini kullanır:

Ayrıca bkz.

İlgili içerik

  • Bu makale, .NET için Blob Depolama geliştirici kılavuzunun bir parçasıdır. Daha fazla bilgi edinmek için .NET uygulamanızı geliştirin geliştirme kılavuzu makalelerinin tam listesine göz atın.
  • Last updated on